Développeurs

Référence de l’API

Une API REST légère pour les factures, les liens de paiement, les soldes et les cryptos acceptées. Elle utilise du JSON sur HTTPS, et chaque requête est effectuée avec votre clé secrète.

URL de base

Production: https://cryptomerchant.online/api/v1
Développement local: http://localhost:3000/api/v1

Une description de cette API lisible par machine se trouve sur /openapi.json (OpenAPI 3.1). Vous pouvez l'importer dans Postman ou un générateur de clients.

Authentification

Envoyez votre clé secrète dans l’en-tête Authorization de chaque requête, en tant que jeton Bearer. Créez des clés dans le portail sous Développeurs.

HTTP

Authorization: Bearer cm_live_…

Les clés commencent par cm_live_ sur le mainnet et par cm_test_ sur le testnet.
La clé complète n’est affichée qu’une seule fois, lors de sa création. Nous n’en stockons qu’un hash : conservez-la donc en lieu sûr.
Utilisez les clés uniquement sur votre serveur. Ne les mettez jamais dans une page web, une application mobile ou un dépôt de code public.
Si une clé a pu fuiter, révoquez-la dans le portail et créez-en une nouvelle.

Erreurs

Lorsqu’une requête échoue, la réponse a un statut d’erreur HTTP et un corps JSON avec un code lisible par une machine et un message lisible par un humain :

JSON

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

Statut HTTP

400: La requête n’est pas valide, par exemple un champ manquant ou un montant trop faible.
401: La clé API est manquante, erronée ou révoquée.
403: Votre compte ne peut pas effectuer cette action : il n’est pas encore actif, ou il est suspendu.
404: L’objet n’existe pas, ou il appartient à une autre entreprise.
409: La facture ne permet pas cette action dans son statut actuel, par exemple l’annulation d’une facture qui a déjà reçu un paiement.
500: Une erreur s’est produite de notre côté. Réessayez un peu plus tard.

Codes que vous pouvez rencontrer

invalid_json: Le corps de la requête n’est pas un objet JSON.
invalid_request: Un champ est manquant ou non valide. Le message indique le nom du champ.
unauthorized: La clé API est manquante, erronée ou révoquée.
account_suspended: Ce compte marchand est suspendu.
merchant_not_live: Votre compte n’est pas encore actif. Terminez d’abord la configuration dans le portail.
invalid_amount: Le montant est manquant, n’est pas un nombre, ou n’est pas supérieur à zéro.
amount_too_small: Le montant vaut moins de 0,50 dollar américain.
invalid_asset: L’ID de crypto ne correspond à aucune crypto connue.
asset_not_accepted: Vous n’acceptez pas cette crypto.
invalid_state: La facture ne permet pas cette action dans son statut actuel.
not_found: Aucun objet ne correspond à cet ID.
server_error: Une erreur s’est produite de notre côté.

L’objet facture

Les factures ont cette forme dans les réponses de l’API et dans les webhooks. Les montants sont des chaînes décimales, pour ne perdre aucune précision.

idstring: ID de la facture, commençant par inv_.
objectstring: Toujours invoice.
statusstring: Le statut actuel. Voir la liste des statuts ci-dessous.
amountstring: Le prix que vous avez demandé, dans la devise currency.
currencystring: La devise du prix, par exemple USD.
amount_usdstring: Le prix en dollars américains.
descriptionstring | null: Votre description, affichée au client.
order_idstring | null: Votre propre référence de commande.
customer_emailstring | null: L’e-mail du client, si vous en avez fourni un.
metadataobject: L’objet que vous avez transmis lors de la création de la facture, renvoyé tel quel.
coinobject | null: La crypto choisie par le client, ou celle dans laquelle il a réellement payé, avec son id, son symbol et son network. null tant qu’aucune crypto n’est choisie.
requested_coinobject | null: Généralement null. Lorsque le client a payé dans une autre crypto ou sur un autre réseau et que le paiement a été pris en compte, il s’agit de la crypto demandée par la facture, avec les mêmes champs que coin. Voir mauvaise crypto ou mauvais réseau.
pay_addressstring | null: L’adresse de dépôt de cette facture. null tant qu’aucune crypto n’est choisie.
pay_amountstring | null: Le montant exact à envoyer, dans la crypto choisie.
network_fee_amountstring: Partie de pay_amount : les frais de gas que le client paie en plus du prix, dans la crypto. 0 s’il n’y en a pas.
network_fee_usdstring: Les mêmes frais de gas en dollars américains.
rate_usdstring | null: Le prix bloqué d’une unité de la crypto choisie, en dollars américains.
received_amountstring: Le montant arrivé jusqu’à présent, dans la crypto choisie.
received_usdstring: La valeur en dollars américains de ce qui est arrivé.
overpaid_amountstring: Le montant payé en plus de ce que demandait la facture, dans la crypto choisie.
refunded_amountstring: Le montant que vous avez remboursé sur ce paiement avec des liens de remboursement, dans la crypto payée. 0 si rien n’a été remboursé.
checkout_urlstring: La page de la facture. Envoyez-y votre client pour qu’il paie.
redirect_urlstring | null: L’adresse où le client peut aller après avoir payé.
expires_atISO 8601: La date d’expiration de la facture si aucun paiement n’est détecté.
paid_atISO 8601 | null: La date de paiement de la facture, ou null.
created_atISO 8601: La date de création de la facture.

invoice

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Statuts des factures

openOuverte: Créée. Le client n’a pas encore choisi de crypto.
awaiting_paymentEn attente de paiement: Une crypto est choisie, l’adresse de dépôt est attribuée et le taux est bloqué.
confirmingEn confirmation: Un paiement a été détecté sur la blockchain et attend des confirmations.
underpaidPaiement insuffisant: Il manque au paiement confirmé plus que votre tolérance. Le client peut payer le reste ou demander un remboursement.
paidPayée: Payée et confirmée. Le montant, moins les frais, est sur votre solde. Un remboursement partiel conserve ce statut.
expiredExpirée: Le délai a expiré avant qu’un paiement soit détecté.
cancelledAnnulée: La facture a été annulée avant qu’un paiement soit détecté.
refundedRemboursée: Le client a été remboursé de ce qu’il avait envoyé sur une facture insuffisamment payée, ou vous avez remboursé tout ce que vous aviez conservé sur une facture payée.

Créer une facture

POST/invoices

Crée une facture et renvoie l’objet facture avec le statut 201. Envoyez votre client vers son checkout_url.

Paramètres du corps

amountObligatoirenumber | string: Le prix, sous forme de nombre ou de chaîne décimale. Doit valoir au moins 0,50 dollar américain.
currencyFacultatifstring: La devise du prix, par exemple USD. Par défaut : USD.
descriptionFacultatifstring: Ce que le client paie, jusqu’à 300 caractères. Affiché sur la page de la facture.
order_idFacultatifstring: Votre propre référence de commande, jusqu’à 120 caractères, pour faire correspondre la facture à une commande.
customer_emailFacultatifstring: L’adresse e-mail du client. Les paiements sont classés par client dans le portail.
customer_nameFacultatifstring: Le nom du client, jusqu’à 120 caractères.
redirect_urlFacultatifstring: Une URL complète où le client peut aller après avoir payé.
metadataFacultatifobject: N’importe quel objet JSON jusqu’à 4 Ko. Renvoyé tel quel sur la facture et dans les webhooks.
coinFacultatifstring: Présélectionne une crypto par son ID, par exemple USDT.TRON. Elle doit faire partie de vos cryptos acceptées.

Avec une coin présélectionnée, l’adresse de dépôt est attribuée et le taux bloqué immédiatement : pay_address et pay_amount sont donc renseignés, et vous pouvez afficher les détails du paiement dans votre propre interface.

curl

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

Node.js

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

Lister les factures

GET/invoices

Renvoie vos factures, des plus récentes aux plus anciennes, une page à la fois.

Paramètres de requête

statusFacultatifstring: Uniquement les factures ayant ce statut, par exemple paid. Doit être l’un des statuts ci-dessus.
limitFacultatifnumber: Le nombre de factures à renvoyer, de 1 à 100. Par défaut : 20.
starting_afterFacultatifstring: Un ID de facture. Renvoie les factures qui suivent celle-ci, pour obtenir la page suivante.

Les factures se trouvent dans data. Lorsque has_more vaut true, demandez la page suivante avec starting_after défini sur l’ID de la dernière facture reçue.

curl

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Réponse

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

Récupérer une facture

GET/invoices/{id}

Renvoie une facture à partir de son ID.

curl

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Annuler une facture

POST/invoices/{id}/cancel

Annule une facture. Cela ne fonctionne que tant que la facture est impayée et qu’aucun paiement n’a été détecté pour elle.

curl

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Soldes

GET/balances

Renvoie ce que votre entreprise détient dans chaque crypto, le total en dollars américains et votre solde de gas.

data[].coin: L’ID de la crypto, par exemple USDT.TRON.
data[].symbol: Le symbole de la crypto, par exemple USDT.
data[].network: Le réseau sur lequel se trouve la crypto.
data[].amount: La quantité de cette crypto que vous détenez, sous forme de chaîne décimale.
data[].usd: Sa valeur en dollars américains au prix actuel.
total_usd: La valeur de toutes vos cryptos en dollars américains.
gas_balance_usd: Votre solde de gas en dollars américains, utilisé pour payer les frais de gas.

curl

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Réponse

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

Cryptos acceptées

GET/coins

Renvoie les cryptos que vous acceptez actuellement, chacune avec son id, son symbol, son name, son network et ses decimals. Utilisez l’id comme valeur de coin lorsque vous créez une facture. Par exemple :

curl

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Réponse

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

Créer un lien de paiement

POST/payment-links

Crée un lien de paiement et le renvoie avec le statut 201, y compris son id et son url à partager.

Paramètres du corps

titleObligatoirestring: Le nom de ce que le client paie, jusqu’à 120 caractères.
amountFacultatifnumber | string: Un prix fixe. Omettez-le pour laisser le client saisir le montant.
currencyFacultatifstring: La devise du prix. Par défaut : USD.
descriptionFacultatifstring: Des détails supplémentaires affichés au client, jusqu’à 300 caractères.

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

Réponse

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

Lister les liens de paiement

GET/payment-links

Renvoie vos 100 liens de paiement les plus récents, des plus récents aux plus anciens, dans data.

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

L’objet versement

Les webhooks de versement (payout.sent et payout.failed) transportent cet objet dans data. Les versements de la part d’un partenaire issue d’un partage des revenus utilisent le même objet, avec partner_share défini sur true.

idstring: ID du versement.
objectstring: Toujours payout.
coinstring: L’ID de la crypto, par exemple USDT.TRON.
amountstring: Le montant versé, dans cette crypto.
network_feestring: Les frais de gas de l’envoi, dans cette crypto.
to_addressstring: L’adresse de portefeuille vers laquelle il a été envoyé.
statusstring: queued, running, done ou failed.
tx_hashstring | null: L’ID de la transaction sur la blockchain, une fois l’envoi effectué.
autoboolean: true si le versement a été effectué automatiquement, et non demandé par une personne.
partner_shareboolean: true si ce versement est la part d’un partenaire issue d’un partage des revenus, envoyée vers le portefeuille du partenaire.
created_atISO 8601: Date de création du versement.

payout

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Ensuite, configurez les webhooks pour que votre serveur soit informé des paiements dès qu’ils ont lieu.