L'API InstantPay

Vue d'ensemble

Avec InstantPay, votre site accepte des paiements en crypto sans que vous ayez à gérer un portefeuille. Votre client paie en SOL, USDC, USDT, ETH, BNB ou BTC sur une page de checkout hébergée par nous ; vous recevez un webhook signé et un crédit en EUR ou USD sur votre solde InstantPay. Chaque paiement confirmé coûte 1,66 % du montant de la facture, sans autres frais. Vous vous versez le solde sur votre propre portefeuille quand vous le souhaitez, en SOL, en stablecoin, ETH, BNB, POL, TRX, BTC ou LTC.

Un paiement se déroule ainsi :

1. Votre serveur crée une facture avec un prix en EUR ou USD et reçoit une URL de checkout.
2. Le client paie sur la page de checkout (ou dans un overlay sur votre site) : il choisit une monnaie, voit l'adresse et le montant exact, l'envoie. Le taux est figé à cet instant.
3. InstantPay surveille la chaîne. Dès que le paiement est définitif, votre URL de webhook reçoit invoice.confirmed.
4. Vous livrez. Le montant de la facture moins la commission est sur votre solde ; demandez un versement dans la monnaie de votre choix quand vous voulez.

Ce qu'il vous faut : un compte InstantNode, un serveur capable de faire des appels HTTPS (Node, PHP ou autre) et une URL publique https:// qui reçoit les webhooks. Vous ne manipulez jamais de monnaies, d'adresses ni de taux de change.

Premiers pas

Six étapes de zéro à une intégration en production. Les étapes 1 à 5 ne nécessitent aucune validation ; vous pouvez développer et tester pendant que nous examinons votre compte.

1. Connectez-vous. Ouvrez pay.instantnode.eu/dashboard et connectez-vous avec votre compte InstantNode. Un compte marchand est créé pour vous dans l'état pending.
2. Complétez votre compte. Sous Account, renseignez l'entreprise, le site web et une courte description de ce que vous vendez, acceptez les conditions et envoyez. InstantNode examine la demande et vous active, en général sous un jour.
3. Copiez votre clé de test. Sous API keys, vous avez déjà une paire production et une paire test : une clé secrète (sk_test_…, pour votre serveur) et une clé publique (pk_test_…, pour le navigateur). Révélez la clé secrète de test et placez-la dans la configuration de votre serveur, jamais dans du code navigateur.
4. Ajoutez un endpoint de webhook. Sous Webhooks, ajoutez l'adresse https:// de votre serveur qui doit recevoir les événements, puis cliquez sur Send test event sur la page de l'endpoint pour vérifier que votre contrôle de signature fonctionne.
5. Faites un achat de test. Créez une facture avec la clé de test (voir ci-dessous), ouvrez l'URL de checkout, cliquez sur Simulate payment. Quelques secondes plus tard, votre webhook reçoit invoice.confirmed avec livemode: false.
6. Passez en production. Une fois votre compte active, passez le tableau de bord en mode production, révélez la clé secrète de production (affichée une fois) et remplacez la clé de test ; ajoutez un endpoint de webhook de production. Les factures d'une clé réelle sont payées avec de vraies monnaies et créditées sur votre solde.

Modes d'intégration

Tous utilisent la même API ; la seule différence est l'endroit où le client paie. Une règle vaut pour tous : la facture est toujours créée sur votre serveur, jamais dans le navigateur, sinon votre clé d'API est publique.

Checkout hébergé

Le plus simple. Votre serveur crée la facture et redirige le client vers checkoutUrl. Après le paiement, le client revient sur votre redirectUrl. Fonctionne dans toute boutique, sans JavaScript.

// Node (Express) - le SDK tient en un seul fichier : /sdk/node/instapay.mjs
import { InstantPay } from './instapay.mjs';
const pay = new InstantPay({ baseUrl: 'https://pay.instantnode.eu', apiKey: process.env.INSTAPAY_KEY });

app.post('/checkout', async (req, res) => {
  const invoice = await pay.createInvoice({
    amount: '19.99',
    currency: 'EUR',
    orderId: order.id,
    description: 'T-shirt, bleu, M',
    redirectUrl: 'https://shop.example/merci?order=' + order.id,
    cancelUrl: 'https://shop.example/panier',
  }, order.id);                 // clé d'idempotence : une nouvelle tentative renvoie la même facture
  res.redirect(invoice.checkoutUrl);
});

// PHP - /sdk/php/InstaPay.php
require 'InstaPay.php';
$pay = new InstantPay('https://pay.instantnode.eu', getenv('INSTAPAY_KEY'));
$invoice = $pay->createInvoice([
  'amount' => '19.99', 'currency' => 'EUR', 'orderId' => (string) $orderId,
  'redirectUrl' => 'https://shop.example/merci?order=' . $orderId,
], (string) $orderId);
header('Location: ' . $invoice['checkoutUrl']);

Liens de paiement

Aucun code. Sous Payment links, créez un lien à montant fixe ou à montant libre (le client le saisit, dans les bornes que vous fixez), réutilisable ou à usage unique, avec une expiration et une URL de succès optionnelles. Le lien est une page sur https://pay.instantnode.eu/l/<slug> qui crée une facture pour quiconque l'ouvre ; vous obtenez l'URL, un QR code et un extrait à intégrer. Chaque facture issue d'un lien porte paymentLinkId et l'identifiant de commande link:<slug>:<n>, donc le webhook et le crédit fonctionnent exactement pareil. La page du lien compte les utilisations et le chiffre d'affaires et liste ses paiements.

Widget en overlay

Le client reste sur votre page ; le checkout s'ouvre dans un overlay. Chargez instapay.js, puis ouvrez-le avec le token, c'est-à-dire la dernière partie de checkoutUrl, fournie par votre serveur. Si vous préférez ne pas faire transiter le token par votre page, le navigateur peut l'obtenir avec votre clé publique : POST /v1/public/checkout-sessions avec { "invoiceId" } répond { token, checkoutUrl } pour une facture créée par votre serveur ; une clé publique ne peut rien faire d'autre.

<script src="https://pay.instantnode.eu/instapay.js"></script>
<script>
  InstantPay.open({
    token: token,                         // dernier segment de checkoutUrl
    lang: 'en',                           // ou 'de'
    onStatus:  (s) => console.log(s.status),
    onPaid:    (s) => location.href = '/merci',
    onExpired: (s) => alert('Le délai de paiement a expiré'),
    onClose:   ()  => console.log('fermé'),
    closeOnPaid: true,
  });
</script>

Le widget interroge l'état toutes les quatre secondes et appelle onPaid dès que le paiement est confirmé. Considérez cela comme une simple commodité pour le client : seul le webhook décide si une commande est payée.

Votre propre page de paiement

Créez la facture, appelez POST /v1/invoices/:id/select avec la monnaie choisie par le client et affichez vous-même depositAddress et amountExpected. Interrogez GET /v1/invoices/:id ou attendez le webhook.

Créer une facture

POST /v1/invoices avec votre clé dans l'en-tête X-API-Key. Les montants circulent sous forme de chaînes ; ne faites jamais de calculs monétaires en virgule flottante.

curl -X POST https://pay.instantnode.eu/v1/invoices \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "amount": "19.99",
    "currency": "EUR",
    "orderId": "ORD-1001",
    "description": "T-shirt, bleu, M",
    "redirectUrl": "https://shop.example/merci?order=1001",
    "cancelUrl": "https://shop.example/panier",
    "metadata": {"sku": "shirt-blue-m"},
    "ttlSeconds": 1200
  }'

La réponse est la facture (201) :

{
  "id": "f987fead-cbc0-47e1-b9c1-02423c18ec97",
  "orderId": "ORD-1001",
  "status": "created",
  "paid": false,
  "amount": "19.99",
  "currency": "EUR",
  "checkoutUrl": "https://pay.instantnode.eu/pay/Tx7CVPbpJk7IcTkdKMCKCCKt",
  "expiresAt": "2026-09-19T21:20:13.527Z",
  "asset": null, "amountExpected": null, "amountReceived": null, "depositAddress": null
}

Limites : 60 appels par minute et par clé (429), au plus 1000 factures ouvertes à la fois (429 too_many_open_invoices). Le même Idempotency-Key avec un corps différent répond 409. Les champs que vous omettez viennent de vos réglages Checkout : délai de paiement (ttlSeconds), tolérance, URL de succès et d'annulation, et les monnaies proposées sur le checkout.

Webhooks

Le webhook est la partie qui compte. La redirection après le paiement n'est que cosmétique : le client peut fermer le navigateur et envoyer quand même les monnaies, donc ne livrez la marchandise qu'après l'arrivée de l'événement avec paid: true.

Sous Webhooks, vous ajoutez jusqu'à dix endpoints par mode (les listes production et test sont distinctes). Chaque endpoint a son propre secret de signature (whsec_…), une liste des types d'événements auxquels il est abonné (* pour tous) et une ligne d'état. InstantPay envoie un POST avec un corps JSON à chaque endpoint abonné. L'URL doit être en https:// avec un nom d'hôte public ; les redirections ne sont pas suivies et votre serveur a 10 secondes pour répondre.

X-InstantPay-Signature: t=1758315600,v1=<hex hmac-sha256>
X-InstantPay-Event: invoice.confirmed
X-InstantPay-Livemode: true
X-InstantPay-Delivery: 42
Idempotency-Key: evt_01K5N3Y7Z2Q8XW6M3R9V4T1B5C

Les mêmes en-têtes sont aussi envoyés avec l'ancienne graphie X-InstaPay-, pour qu'un récepteur existant continue de fonctionner.

Vérifier la signature

La signature est un HMAC-SHA256 de "<t>.<corps brut>" avec le secret de l'endpoint (affiché sur la page de l'endpoint après une connexion récente). Vérifiez les octets bruts reçus, pas un objet resérialisé, et rejetez les horodatages de plus de cinq minutes.

// Node (Express) - verifyWebhook vient du SDK
import { verifyWebhook } from './instapay.mjs';

app.post('/webhooks/instantpay', express.raw({ type: '*/*' }), (req, res) => {
  const raw = req.body.toString('utf8');
  if (!verifyWebhook(process.env.INSTANTPAY_WEBHOOK_SECRET, req.get('x-instantpay-signature'), raw)) {
    return res.status(400).send('bad signature');
  }
  const event = JSON.parse(raw);
  if (event.livemode === false) return res.json({ ok: true });      // un événement de test : ne jamais livrer
  const invoice = event.data.object;
  if (event.type === 'invoice.confirmed' && invoice.paid) markOrderPaid(invoice.orderId);
  res.json({ ok: true });                                            // répondre vite, travailler ensuite
});

// PHP
$raw = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_INSTANTPAY_SIGNATURE'] ?? '';
$event = InstantPay::parseWebhook(getenv('INSTANTPAY_WEBHOOK_SECRET'), $signature, $raw);
if ($event === null) { http_response_code(400); exit('bad signature'); }
if (($event['livemode'] ?? true) === false) { echo 'ok'; exit; }
$invoice = $event['data']['object'];
if ($event['type'] === 'invoice.confirmed' && $invoice['paid']) markOrderPaid($invoice['orderId']);
echo 'ok';

Le corps de l'événement

data.object est l'objet exactement tel que GET /v1/invoices/:id (ou /v1/payouts/:id) le renvoie ; un webhook et une lecture ne se contredisent jamais.

{
  "id": "evt_01K5N3Y7Z2Q8XW6M3R9V4T1B5C",
  "object": "event",
  "type": "invoice.confirmed",
  "livemode": true,
  "created": "2026-09-19T21:05:00.000Z",
  "data": {
    "object": {
      "object": "invoice",
      "id": "f987fead-cbc0-47e1-b9c1-02423c18ec97",
      "orderId": "ORD-1001",
      "status": "confirmed",
      "paid": true,
      "livemode": true,
      "amount": "19.99",
      "currency": "EUR",
      "asset": "SOL",
      "amountExpected": "0.206789123",
      "amountReceived": "0.206789123",
      "metadata": {"sku": "shirt-blue-m"},
      "createdAt": "2026-09-19T21:00:13.527Z",
      "expiresAt": "2026-09-19T21:20:13.527Z",
      "confirmedAt": "2026-09-19T21:05:00.000Z"
    }
  }
}

Un endpoint peut aussi être réglé sur le corps legacy (event, livemode et invoice / deposit / payout au premier niveau, priceAmount au lieu de amount), celui que reçoivent les intégrations antérieures aux endpoints ; invoice.overpaid y arrive comme invoice.confirmed avec overpaid: true. Les nouvelles intégrations doivent utiliser le format par défaut.

Règles pour un récepteur robuste

• Répondez 2xx en 10 secondes et faites le vrai travail ensuite. Tout le reste est réessayé à intervalles croissants (5 s, 20 s, 1 min, 3 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h), dix tentatives au total, puis la livraison est marquée dead. Un endpoint qui échoue 20 livraisons d'affilée sur trois jours ou plus est désactivé et vous recevez un e-mail ; réactivez-le sur sa page une fois réparé.
• Soyez idempotent. Il y a exactement un événement par chose qui s'est produite, mais une livraison peut se répéter (nouvelles tentatives, bouton Renvoyer). Utilisez l'en-tête Idempotency-Key ou event.id pour ignorer ce qui est déjà traité.
• Vérifiez livemode. Les événements des factures de test et du bouton Send test event portent livemode: false. Ils servent à tester votre code, jamais à expédier de la marchandise.
• En cas de doute, réconciliez. GET /v1/events liste chaque événement de votre compte, le plus récent en premier, et GET /v1/invoices/:id répond avec paid. L'onglet Events du tableau de bord montre la même liste avec chaque livraison et un bouton Renvoyer à l'endpoint.

Mode test

Une clé de test se comporte exactement comme une vraie, sauf que ses factures ne sont jamais payées avec des monnaies. Sur le checkout, le client (c'est-à-dire vous) voit un bandeau « Test mode » avec un bouton Simulate payment ; votre serveur peut faire de même via l'API. Les factures de test sont créditées sur un solde de test séparé, visible seulement avec l'interrupteur Live/Test du tableau de bord sur Test ; il n'est jamais versable ni de l'argent réel. Leurs webhooks portent livemode: false.

# payer une facture de test depuis votre serveur - "case" peut valoir exact, under ou over
curl -X POST https://pay.instantnode.eu/v1/invoices/<id>/simulate \
  -H "X-API-Key: sk_test_..." -H "Content-Type: application/json" \
  -d '{"case": "exact"}'

Liste de contrôle avant la mise en production :

• Votre webhook rejette une signature incorrecte (400) et accepte l'événement de test du tableau de bord.
• Une commande n'est marquée payée qu'après invoice.confirmed avec paid: true et livemode: true.
• Une livraison répétée ne crée pas de seconde expédition.
• invoice.underpaid et invoice.expired affichent quelque chose de sensé au client.
• La clé de test est remplacée par une clé réelle dans votre configuration, et la clé de test est révoquée.

État d'une facture

paid est le champ à regarder : il vaut true pour confirmed et overpaid, et false pour tout le reste.

Un client qui envoie légèrement trop peu (jusqu'à 0,5 %) compte quand même comme payé. En dessous, la facture passe en underpaid.

Commissions, solde et versements

• Commission. Chaque paiement confirmé est crédité sur votre solde dans la monnaie de la facture, moins la commission de la plateforme, 1,66 % par défaut. Facture 100.00 € → crédit 98.34 €. La commission est figée à la création de la facture ; un changement ultérieur ne concerne que les nouvelles factures.
• Payée en trop. Vous êtes crédité de tout ce qui est arrivé, au taux figé pour la facture, moins la commission. L'argent du client est le vôtre.
• Payée en retard. Jusqu'à 60 minutes après l'échéance, le paiement est crédité automatiquement au taux figé. Au-delà, il vous attend : Accepter le paiement tardif sur la facture crédite ce qui est arrivé au taux actuel ; la variation du cours depuis la facture est pour vous.
• Payée en partie. Rien n'est crédité de lui-même. Accepter le paiement partiel sur la facture crédite ce qui est arrivé au taux figé, moins la commission ; possible jusqu'à 7 jours après l'expiration de la facture, ensuite via le support.
• Solde. Balance dans le tableau de bord affiche trois chiffres par monnaie : disponible (ce que vous pouvez verser), en attente (paiements détectés sur la chaîne mais pas encore confirmés) et réservé (versements et remboursements ouverts, déjà déduits). En dessous, chaque écriture : sale, fee, payout, payout_reversal, refund, refund_reversal et adjustment, avec un solde courant et un export CSV pour votre comptabilité.
• Remboursements. Depuis une facture payée, Refund renvoie une partie du montant crédité à une adresse indiquée par le client, dans la monnaie de son paiement ou dans votre monnaie de versement. Le montant en fiat quitte votre solde immédiatement ; les frais de réseau en sont déduits et vous voyez les chiffres exacts avant de confirmer. Les remboursements jusqu'à 200 € des comptes approuvés depuis 30 jours ou plus partent d'eux-mêmes ; les plus importants sont contrôlés par InstantNode. refund.paid / refund.failed arrivent en webhooks ; GET /v1/refunds les liste. Les factures de test ne peuvent pas être remboursées.
• Versements. Sous Payouts, choisissez la monnaie dans laquelle vous voulez être payé (SOL par défaut ; aussi USDC et USDT sur Solana, ETH, USDT et USDC sur Ethereum, BNB, USDT sur BSC, POL, TRX, USDT sur TRON, BTC et LTC), enregistrez votre adresse de portefeuille pour cette monnaie et demandez un versement. Votre solde reste en EUR/USD ; la monnaie n'est que ce dans quoi le versement est envoyé. Minimum 10 € (ou $), au plus 2 000 par jour, un seul versement ouvert à la fois. Chaque monnaie garde sa propre adresse, et une nouvelle adresse doit avoir 24 heures avant de pouvoir recevoir un versement. Les demandes jusqu'à 500 € sont approuvées automatiquement en une minute ; les plus importantes sont contrôlées par InstantNode. Avant de confirmer, le tableau de bord affiche un devis (taux, montant en monnaie, frais de réseau estimés, ce qui arrive), valable 60 secondes ; les frais de réseau sont déduits du versement. Le montant en crypto est fixé à nouveau à l'approbation et envoyé vers votre portefeuille. Vous recevez payout.paid ou payout.failed en webhook ; le champ payout.asset vous indique quelle monnaie a été envoyée, networkFeeCrypto ce que le transfert a coûté.
• Versements automatiques. Sous Payouts, fixez un seuil, un rythme (dès qu'il est atteint, au plus une fois par jour, au plus une fois par semaine) et un montant à garder sur le solde ; la règle demande les versements d'elle-même, marqués Automatique. Depuis votre propre système, POST /v1/payouts avec { "currency": "EUR", "amount": "250.00" } (ou "amount": "all") fait exactement ce que fait le formulaire du tableau de bord, avec les mêmes contrôles ; il répond 201 avec l'objet de versement, 409 payout_open tant qu'un versement est ouvert, et 400 test_mode pour une clé de test.

Votre compte

• Candidature. Sous Compte, vous remplissez le profil de l'entreprise : nom affiché aux clients, raison sociale, site web, secteur d'activité, pays, numéro de TVA (optionnel), volume mensuel attendu et ce que vous vendez, puis vous acceptez les conditions marchands. InstantNode l'examine, en général sous un jour ; vous recevez un e-mail dans tous les cas. Les clés de test fonctionnent pendant l'attente.
• Conditions. Quand les conditions marchands changent, vous recevez un e-mail et la prochaine visite du tableau de bord affiche la nouvelle version avec une case à cocher avant tout le reste ; les clés API et les webhooks continuent de fonctionner entre-temps. La version en vigueur est toujours sur /terms.
• Notifications. Sous Notifications, vous choisissez les e-mails voulus (paiement reçu, versement ou remboursement envoyé ou échoué, endpoint de webhook désactivé, statut du compte, nouvelle connexion depuis un nouvel appareil), ajoutez jusqu'à 5 destinataires supplémentaires et, en option, un webhook Discord ou Slack qui reçoit les mêmes événements en message court.
• Sessions. Compte liste chaque navigateur connecté avec appareil, IP et dernière activité ; déconnectez-en un ou tous les autres. Une connexion depuis un appareil jamais vu sur votre compte vous est signalée par e-mail.
• Export des données. Créer un export produit un zip avec votre profil, factures, grand livre, versements, remboursements, endpoints, événements et liens de paiement en JSON. Le lien fonctionne 60 minutes et n'est affiché qu'une fois ; une connexion récente est demandée.
• Fermer le compte. Possible dès que le solde réel est à zéro et qu'aucun versement ni remboursement n'est ouvert. Les clés et les endpoints sont révoqués aussitôt, toutes les sessions prennent fin, les enregistrements restent pendant la durée de conservation.

Référence de l'API

URL de base https://pay.instantnode.eu. Chaque appel sous /v1 nécessite X-API-Key: sk_live_… (ou Authorization: Bearer …) ; une clé antérieure aux paires (ik_<id>.<secret>) continue de fonctionner. Les clés se trouvent sous API keys : une clé secrète par mode pour votre serveur (accès complet, affichée une fois, renouvellement avec 24 h de chevauchement, liste d'IP optionnelle) et une clé publique par mode pour le navigateur, acceptée seulement sur GET /v1/public/config, POST /v1/public/checkout-sessions et l'état du checkout. Tout le reste répond 403 public_key_not_allowed à une clé publique.

Les appels en écriture nécessitent un compte active (403 merchant_not_approved tant qu'il est en attente, 403 merchant_suspended s'il est suspendu). Une clé de test peut écrire alors que le compte est encore en attente. La lecture fonctionne toujours.

Chaque endpoint avec ses paramètres, corps et réponses figure dans la référence interactive ci-dessous. Vous pouvez y tester des requêtes avec votre propre clé.

Les erreurs arrivent en JSON avec un code error stable :

{"error": "invalid_request", "message": "amount: Required", "requestId": "…"}

SDK et exemples

Tout tient en un seul fichier à copier dans votre projet ; il n'y a rien à installer.

• Node : /sdk/node/instapay.mjs - createInvoice, getInvoice, listInvoices, selectAsset, getMerchant, listLedger, listPayouts, getPayout, createPayout, listRefunds, getRefund, simulatePayment, listEvents, getEvent, verifyWebhook, parseWebhook. Le constructeur prend la clé secrète ; parseWebhook comprend le corps par défaut et le corps legacy.
• PHP : /sdk/php/InstaPay.php - les mêmes méthodes pour PHP 8 (classe InstantPay).
• Boutique complète : /examples/demo-shop/server.mjs est le code source de la boutique démo : produits, checkout hébergé, overlay, récepteur de webhooks et liste des commandes dans un seul fichier.
• Overlay en HTML pur : /examples/plain-html.html.
• WooCommerce : /examples/woocommerce-instapay.php avec le SDK PHP dans wp-content/plugins/instapay/ ; saisissez l'URL de base, la clé et le secret de webhook sous WooCommerce → Réglages → Paiements.

Des questions ou une intégration qui bloque : [email protected].