Votre API crypto.
Sur votre domaine.

Démarrage

1. Créez un compte et attendez son activation.
2. Créez une clé API dans le dashboard ; sa valeur complète n’est affichée qu’une fois.
3. Envoyez une requête à POST /v1/payment depuis votre serveur.
4. Conservez le payment_id retourné et consultez GET /v1/payment/{payment_id} pour suivre l’état.

https://api-crypto-payment.com/v1/payment
https://api-crypto-payment.com/v1/payment/123456789
https://api-crypto-payment.com/v1/payout

Les URL propres ne nécessitent plus index.php?route=. Le suivi décrit ici fonctionne sans URL IPN ou webhook fournie par le client.

Authentification

x-api-key: sk_live_VOTRE_CLE
Accept: application/json
Content-Type: application/json

Utilisez votre clé Crypto Payment, jamais celle du compte prestataire principal. L’alternative Authorization: Bearer sk_live_VOTRE_CLE reste acceptée. Ne transmettez aucune clé au navigateur de l’acheteur.

POST /v1/auth

Si votre intégration utilise un jeton Bearer, fournissez les identifiants de votre compte Crypto Payment. L’authentification est traitée par Crypto Payment.

curl 'https://api-crypto-payment.com/v1/auth' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"email":"votre-compte@example.com","password":"VOTRE_MOT_DE_PASSE"}'

{"token":"JETON_JWT"}

Le jeton expire après cinq minutes. Utilisez ensuite Authorization: Bearer JETON_JWT avec x-api-key. Le jeton et la clé doivent appartenir au même compte. Le jeton ne remplace pas la clé marchande.

Protection contre les doublons

Idempotency-Key est recommandé pour les paiements et requis pour les retraits, sauf si chaque bénéficiaire possède un unique_external_id non vide : 1 à 128 lettres ASCII, chiffres ou caractères _ . : -. Une même clé et un même contenu renvoient l’opération existante ; un contenu différent renvoie 409. Conservez aussi le même ordre des bénéficiaires lors d’une reprise.

Sans cet en-tête sur POST /payment, chaque requête constitue une nouvelle création. Une clé générée est retournée dans l’en-tête de réponse, mais si la réponse réseau est perdue vous ne pourrez pas la récupérer : fournissez votre propre clé pour les reprises automatiques.

Routes & compatibilité

curl 'https://api-crypto-payment.com/v1/estimate?amount=25&currency_from=eur&currency_to=btc' \
  -H 'x-api-key: sk_live_VOTRE_CLE' \
  -H 'Accept: application/json'

Les noms de devises utilisent de 2 à 24 lettres minuscules ou chiffres. Précisez l’actif et son réseau, par exemple usdttrc20. Les options booléennes de recherche acceptent true, false, 1 et 0.

Factures & liens de paiement

Créez un lien depuis vos factures ou par API. Votre acheteur choisit sa crypto puis reçoit les instructions de paiement, sans compte Crypto Payment. Le prix reste celui enregistré par votre serveur.

POST /v1/invoice

curl 'https://api-crypto-payment.com/v1/invoice' \
  -H 'x-api-key: sk_live_VOTRE_CLE' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: facture-1042' \
  -d '{"price_amount":25,"price_currency":"eur","order_id":"1042","order_description":"Commande 1042","success_url":"https://votre-boutique.fr/merci"}'

Réponse 201 : id de facture, gateway_id interne, invoice_url sur https://api-crypto-payment.com/pay/…, prix, options, gateway_status, dates et expires_at. Un résultat de création incertain répond 202, avec gateway_status=creation_unknown et invoice_url=null : conservez la même clé d’idempotence, sans recréer une facture.

Le lien autorise son détenteur à consulter et payer cette commande : transmettez-le uniquement à l’acheteur concerné. Il permet de commencer un paiement pendant 7 jours. Après création du paiement, le délai de l’estimation crypto est distinct et apparaît dans ses instructions.

POST /v1/invoice-payment

curl 'https://api-crypto-payment.com/v1/invoice-payment' \
  -H 'x-api-key: sk_live_VOTRE_CLE' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"iid":"ID_FACTURE","pay_currency":"btc"}'

iid et pay_currency sont les seuls champs acceptés. Le prix et la référence viennent de la facture. La réponse suit le format des paiements : conservez payment_id et consultez GET /v1/payment/{payment_id}.

Une seule opération de paiement est autorisée par facture. Même facture et même devise renvoient le paiement déjà créé, y compris après une coupure réseau. Changer la devise après la première création renvoie 409. Une facture expirée sans paiement renvoie 410. Les champs purchase_id, customer_email et les changements de portefeuille de sortie ne sont pas exposés.

GET /v1/invoice/{id}

Cette extension consulte votre facture avec son id ou son gateway_id. Elle renvoie aussi payment_id et payment_status lorsqu’un paiement a été créé. Une facture d’un autre marchand renvoie 404.

Créer un paiement

curl 'https://api-crypto-payment.com/v1/payment' \
  -H 'x-api-key: sk_live_VOTRE_CLE' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: commande-1042' \
  -d '{"price_amount":25,"price_currency":"eur","pay_currency":"usdttrc20","order_id":"1042","order_description":"Commande 1042"}'

N’envoyez pas d’ipn_callback_url : le parcours client n’en utilise pas. Une valeur non vide est refusée. Les changements de portefeuille de sortie (payout_address et champs associés) et les achats partagés via purchase_id ne sont pas exposés.

Exemple de réponse · 201

{
  "payment_id": "123456789",
  "payment_status": "waiting",
  "pay_address": "ADRESSE_RETOURNEE_PAR_API",
  "price_amount": 25,
  "price_currency": "eur",
  "pay_amount": 27.15,
  "pay_currency": "usdttrc20",
  "actually_paid": 0,
  "outcome_amount": null,
  "outcome_currency": null,
  "order_id": "1042",
  "order_description": "Commande 1042",
  "ipn_callback_url": null,
  "created_at": "2026-09-09T10:00:00.000Z",
  "updated_at": "2026-09-09T10:00:00.000Z"
}

Exemple fictif : l’adresse et le montant ne sont pas utilisables pour payer. Selon la réponse du prestataire, d’autres champs propres au paiement peuvent être présents. Les montants peuvent être des nombres ou des chaînes ; ne les calculez pas avec des flottants pour votre comptabilité.

La passerelle conserve une correspondance entre votre marchand, votre order_id, son UUID interne et le payment_id. Votre référence de commande est restituée ; la référence technique utilisée en amont reste interne.

Création incertaine · 202

Un timeout ne prouve pas l’échec de la création. La réponse peut contenir payment_status: creation_unknown, payment_id: null et un gateway_id. Rejouez avec la même clé d’idempotence ou consultez GET /v1/payments/{gateway_id} pour le suivi local. Cette ancienne route utilise les champs id et status. Ne recréez pas l’opération avec une nouvelle clé.

Consulter & suivre sans IPN

curl 'https://api-crypto-payment.com/v1/payment/123456789' \
  -H 'x-api-key: sk_live_VOTRE_CLE' \
  -H 'Accept: application/json'

Conservez le payment_id dans votre base et consultez cette route depuis votre serveur. La propriété du paiement est vérifiée avant chaque rapprochement. Une opération d’un autre marchand renvoie 404.

Un intervalle de 30 à 60 secondes est un point de départ pour la consultation ; espacez davantage après une longue attente et respectez les limites de débit. Ce n’est pas une garantie de fraîcheur. Une consultation concurrente peut renvoyer le dernier état enregistré pendant qu’un autre rapprochement est en cours.

Un retour du navigateur ne prouve pas le paiement. Dédupliquez l’exécution de vos commandes par ID de paiement dans une transaction de base de données, et surveillez les éventuels remboursements ultérieurs.

Lister les paiements

GET https://api-crypto-payment.com/v1/payment/?limit=10&page=0&sortBy=created_at&orderBy=desc

La première page est 0. limit : 1 à 500, valeur par défaut 10. sortBy : created_at, updated_at, payment_id, payment_status. orderBy : asc ou desc. dateFrom et dateTo filtrent la date de création ; utilisez une date ISO avec fuseau.

{"data":[],"limit":10,"page":0,"pagesCount":0,"total":0}

La liste contient uniquement les paiements de votre marchand dont l’ID prestataire est connu. Elle utilise les données enregistrées localement ; consultez un paiement individuellement pour un rapprochement. Le filtre invoiceId accepte l’identifiant d’une de vos factures (alias invoiceid également accepté).

Retraits & solde marchand

curl 'https://api-crypto-payment.com/v1/payout' \
  -H 'x-api-key: sk_live_VOTRE_CLE' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: retrait-1042' \
  -d '{"withdrawals":[{"amount":"10","currency":"usdttrc20","address":"ADRESSE_DU_BENEFICIAIRE"}]}'

Réponse 202 : id du lot et tableau withdrawals. Chaque retrait contient id, batch_withdrawal_id, address, amount, currency, extra_id, unique_external_id, hash, status, gateway_status et les dates de création et modification. Les IDs sont des UUID Crypto Payment. hash reste nul tant que la transaction blockchain n’est pas connue.

Le montant doit être positif, avec au maximum 6 décimales et une valeur de 100 000 000. Le tableau accepte 1 à 50 bénéficiaires. Par bénéficiaire : address (10–512 caractères), currency, amount requis ; extra_id (mémo/tag, 256 caractères maximum) et unique_external_id (référence unique, 128 caractères maximum) facultatifs. Une référence externe déjà employée ne peut pas être réutilisée dans un autre lot.

{"withdrawals":[
  {"amount":"10","currency":"usdttrc20","address":"ADRESSE_A","unique_external_id":"retrait-A"},
  {"amount":"20","currency":"xrp","address":"ADRESSE_B","extra_id":"123456","unique_external_id":"retrait-B"}
]}

N’envoyez pas d’URL IPN ; une valeur vide ou nulle est acceptée. Les montants fiat, les retraits programmés et les conversions automatiques ne sont pas disponibles.

GET /v1/balance

Pour chaque devise, amount représente le solde disponible de votre marchand et pendingAmount le total réservé pour ses retraits non finalisés, sous forme de chaînes décimales. Aucun solde d’un autre marchand n’est exposé. Un règlement remboursé après réservation peut créer un déficit : les nouveaux envois sont alors bloqués jusqu’à régularisation.

Solde disponible dans une devise =
  outcome_amount des paiements finished du marchand
− retraits du marchand, sauf rejected et cancelled

Un retrait terminé reste déduit. Les paiements partiels ne sont pas disponibles. La devise de règlement peut différer de celle payée. Il n’existe pas de conversion automatique. Avant l’envoi, le serveur recontrôle le solde marchand, l’adresse, le minimum de retrait, l’estimation des frais et la liquidité disponible. Un échec de ces précontrôles ne déclenche pas d’envoi et pourra être réessayé automatiquement.

La réponse inclut automatic et last_error. preflight_unavailable indique un contrôle préalable non satisfait, avec réservation conservée. reconciliation_required indique un résultat incertain : aucun nouvel envoi automatique. Les frais réseau sont variables ; leur estimation n’est pas une garantie du coût final.

Suivre un retrait

Appelez GET /v1/payout/{id} avec l’UUID du retrait pour son détail actualisé, ou l’UUID du lot pour la liste de ses retraits enregistrée localement. La liste GET /v1/payout?page=0&limit=10 utilise la même enveloppe de pagination que les paiements.

Le statut est mis à jour de façon asynchrone. Ni une demande acceptée, ni la validation 2FA ne signifient que les fonds sont arrivés. La 2FA est gérée automatiquement côté serveur ; le client n’a aucun code à fournir. Un résultat incertain exige un rapprochement et ne libère jamais le solde automatiquement.

Annuler avant envoi

curl -X POST 'https://api-crypto-payment.com/v1/payout/UUID_DU_RETRAIT/cancel' \
  -H 'x-api-key: sk_live_VOTRE_CLE' -H 'Accept: application/json'

Réponse 200 avec le retrait annulé, ou 409 s’il a déjà été soumis. Pour un lot, utilisez son UUID et /cancel-batch. Si un seul retrait du lot a été soumis ou rejeté, aucune annulation du lot n’est effectuée. Aucun appel réseau d’annulation n’est nécessaire pour une demande jamais envoyée.

Erreurs & limites restantes

401 : clé ou jeton invalide ; 403 : compte désactivé ou identité incohérente ; 404 : opération introuvable ou hors de votre compte ; 409 : conflit ; 422 : paramètres invalides, non pris en charge ou solde insuffisant ; 429 : débit dépassé ; 501 : route non exposée ; 502 : communication prestataire ; 503 : fonctionnalité désactivée.

Les erreurs techniques sont filtrées pour ne pas exposer de données internes. Limite marchande : 120 requêtes par minute, avec un plafond supplémentaire par IP. Respectez Retry-After quand il est fourni.

Les modules suivants ne sont pas disponibles et répondent 501 : conversions (/conversion), comptes clients et transferts internes (/sub-partner/*), versements fiat (/fiat-payouts/*), abonnements et plans (/subscriptions/*). Les remboursements automatiques ne sont pas disponibles. POST /payout/{id}/verify n’est pas une opération marchande : le serveur effectue la vérification automatiquement.

Les anciennes routes /v1/payments et /v1/withdrawals restent disponibles pour les intégrations existantes, avec leur format historique. Pour une nouvelle intégration, utilisez les routes au singulier décrites ici.

Les comptes nouveaux sont en attente d’activation. Votre inscription ouvre directement le dashboard, où vous pouvez créer des clés, consulter les transactions et, après activation et règlement, demander un retrait. Les e-mails de récupération seront disponibles après activation du service d’envoi.