Crypto Payment Gateway API: Guide Complet d'Intégration pour 2026

Une crypto payment gateway API est l'interface programmatique qui permet à votre application de créer des demandes de paiement, de surveiller les confirmations de transactions on-chain et de régler les fonds — sans gérer directement des wallets ni des clés privées. Vous appelez un endpoint REST, le gateway prend en charge la couche blockchain, et votre backend reçoit un webhook quand le paiement arrive.

Cela diffère d'un processeur de paiement (qui gère les autorisations fiat) ou d'un wallet en autocustode (où les utilisateurs signent eux-mêmes les transactions). L'API se situe au milieu : votre application contrôle l'expérience utilisateur, le gateway gère les confirmations, les vérifications de conformité et la conversion optionnelle en fiat.

Dans le cycle de paiement, le crypto payment gateway remplit quatre fonctions : génération d'une adresse de dépôt ou d'une URL de paiement, surveillance de la blockchain pour les fonds entrants, déclenchement d'un webhook quand les seuils de confirmation sont atteints, et conversion optionnelle du montant reçu. Votre intégration ne doit gérer que les étapes 1 et 3.

Le flux de paiement complet comporte cinq étapes.

Étape 1 — Créer une intention de paiement

Votre serveur appelle `POST /payments` avec le montant attendu, la devise et un `orderId` que vous générez. Le gateway retourne un `paymentId`, une adresse de dépôt et un timestamp d'expiration.

Étape 2 — Redirection ou affichage

Pour les checkouts hébergés, redirigez l'utilisateur vers l'URL du gateway. Pour les intégrations directes, affichez l'adresse de dépôt et le QR code dans votre propre UI.

Étape 3 — Recevoir le callback webhook

Quand le gateway détecte une transaction entrante, il envoie une requête POST à votre URL webhook. Le payload contient `paymentId`, statut actuel, confirmations et montant reçu.

Étape 4 — Vérifier et confirmer

Avant toute action, vérifiez la signature HMAC dans les headers de la requête. Si elle ne correspond pas, rejetez la requête. Appelez ensuite `GET /payments/{id}` pour vérifier le statut canonique côté serveur.

Étape 5 — Exécuter la commande

Une fois le statut côté serveur confirmé comme `completed`, exécutez la commande de façon idempotente en utilisant `paymentId` comme clé d'idempotence. Les webhooks peuvent se déclencher plusieurs fois pour le même événement.

La configuration du crypto payment gateway détermine si le règlement est synchrone ou asynchrone.

Une API de payment gateway bien conçue expose quatre groupes d'endpoints essentiels.

Création d'intention de paiement — POST /payments

Une requête minimale ressemble à ceci :

```json

{

"orderId": "ord_abc123",

"amount": "250.00",

"currency": "USD",

"payCurrency": "ETH",

"callbackUrl": "https://yourapp.com/webhooks/payments",

"successUrl": "https://yourapp.com/orders/ord_abc123/success",

"expiresIn": 1800

}

```

La réponse inclut `paymentId`, `depositAddress`, `expectedAmount` en crypto et `expiresAt`.

Statut de transaction — GET /payments/{id}

Utilisez cet endpoint pour confirmer le statut après réception d'un webhook.

Remboursements — POST /refunds

Passez `paymentId` et `amount`. Le gateway initie un transfert on-chain vers l'adresse de l'expéditeur.

Rapports de règlement — GET /settlements

Interrogez les règlements par plage de dates pour la réconciliation.

Les webhooks surpassent le polling pour une raison : vous êtes informé des confirmations dès qu'elles surviennent.

Pourquoi les webhooks surpassent le polling

Le polling génère des appels API inutiles et augmente la latence. Les webhooks envoient des événements dès que les seuils de confirmation sont atteints.

Vérification de signature HMAC-SHA256

```javascript

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {

const expectedSig = crypto

.createHmac('sha256', secret)

.update(rawBody, 'utf8')

.digest('hex');

const expected = Buffer.from(expectedSig, 'hex');

const received = Buffer.from(signature, 'hex');

if (expected.length !== received.length) return false;

return crypto.timingSafeEqual(expected, received);

}

app.post('/webhooks/payments', express.raw({ type: 'application/json' }), (req, res) => {

const sig = req.headers['x-signature'];

if (!verifyWebhookSignature(req.body, sig, process.env.WEBHOOK_SECRET)) {

return res.status(401).json({ error: 'Invalid signature' });

}

const event = JSON.parse(req.body);

res.json({ received: true });

});

```

Passez le corps brut de la requête (Buffer), pas le JSON parsé.

Nouvelle tentative avec backoff exponentiel

Les gateways rejouent les webhooks échoués — généralement 3-5 fois avec backoff exponentiel.

Clés d'idempotence

Utilisez `paymentId` comme clé d'idempotence pour éviter les commandes dupliquées.

La plupart des gateways importants fournissent des SDKs pour TypeScript/Node, Python, Go et PHP.

Utilisez le SDK quand :

• •Votre stack correspond à un langage supporté
• •Vous avez besoin de la sûreté des types sur les objets requête/réponse
• •Vous voulez une logique de retry déjà intégrée

Utilisez REST brut quand :

• •Votre stack n'est pas supporté (Rust, Elixir)
• •Vous avez besoin d'un contrôle précis du comportement HTTP
• •La version SDK est en retard sur la version API

Pour la plupart des équipes, le SDK est le bon choix. Découvrez ce que les blockchain APIs pour développeurs font sous le capot.

Un guide d'intégration réaliste en cinq étapes.

Étape 1 : Choisir un fournisseur de Payment Gateway API

Évaluez cinq critères : chaînes supportées, structure des frais, qualité du sandbox, profondeur de la documentation et préparation à la conformité (KYC/AML intégré ou votre responsabilité).

Pour les entreprises avec des exigences DeFi, vérifiez également la compatibilité avec les plateformes DeFi.

Étape 2 : Obtenir les clés API et l'accès Sandbox

Votre ensemble de clés API comprend une clé publique (dans les headers de requête) et une clé secrète (pour la signature HMAC). Stockez les deux dans des variables d'environnement.

Étape 3 : Créer votre première intention de paiement

```javascript

const axios = require('axios');

async function createPayment(orderId, amountUSD) {

const response = await axios.post(

'https://api.yourgateway.com/v1/payments',

{

orderId,

amount: amountUSD.toString(),

currency: 'USD',

payCurrency: 'USDT_ETH',

callbackUrl: process.env.WEBHOOK_URL,

expiresIn: 3600,

},

{

headers: {

Authorization: `Bearer ${process.env.GATEWAY_API_KEY}`,

'Idempotency-Key': orderId,

'Content-Type': 'application/json',

},

}

);

return response.data;

}

```

Étape 4 : Gérer les callbacks webhook

Configurez votre endpoint webhook avant de tester. Dans le sandbox, la plupart des gateways permettent de déclencher manuellement des événements webhook.

Étape 5 : Vérifier et exécuter la commande

Après réception d'un webhook `completed`, faites toujours une vérification côté serveur (`GET /payments/{id}`), puis exécutez la commande de façon idempotente avec `paymentId` comme clé d'idempotence.

La sécurité n'est pas une préoccupation post-lancement. Ces exigences appartiennent à la phase de décisions architecturales.

Sécurité du transport

TLS 1.3 minimum pour toutes les communications API.

Gestion des clés API

Faites pivoter les clés API trimestriellement. Utilisez des paires de clés séparées pour le sandbox et la production.

Conformité KYC/AML

Pour les entreprises traitant au-dessus de certains seuils, les directives FATF sur le LCB s'appliquent. Les normes PCI DSS s'appliquent techniquement aux flux de paiement crypto.

Requêtes signées

Certains fournisseurs exigent des requêtes API signées (similaire à AWS Signature V4). Pour les entreprises développant des solutions fintech complètes, une revue d'architecture de sécurité API avant le lancement est incontournable.

Voici comment se comparent les principaux fournisseurs sur les dimensions qui comptent vraiment pour les décisions d'intégration.

Ce sont les erreurs que les équipes font en production, pas dans les tutoriels.

Mauvais seuils de confirmation

Bitcoin nécessite 6 confirmations pour les transactions de grande valeur — environ 60 minutes. Utiliser 1 confirmation vous expose aux attaques de double dépense. Définissez des seuils selon la valeur : 1 pour <$100, 3 pour $100-$1000, 6 pour >$1000 sur Bitcoin mainnet.

Gestion des timeouts on-chain

Les transactions crypto peuvent rester non confirmées pendant des heures. Gardez l'état `watchAddress` actif 24-72 heures après l'expiration de l'intention de paiement.

Erreurs d'estimation du gas

Pour les chaînes EVM, ajoutez un tampon de tolérance de 5-10% pour les paiements en ETH, ou passez aux stablecoins USDT/USDC.

Consultez l'article sur les coûts de développement de crypto payment gateway pour plus de détails.