Intégrer un PSP de A à Z. 6 chapitres et un QCM final.

Chapitre 1. Cadrer le projet et choisir son PSP.

Intégrer un prestataire de services de paiement (PSP) est un chantier qui engage la trésorerie, la conformité et l'expérience client de l'entreprise pour plusieurs années, bien au-delà du branchement d'une API. Le cadrage du besoin précède le code. Il porte sur les pays servis, les méthodes de paiement attendues, le volume prévu et le modèle de vente (vente directe, abonnement, marketplace). Ce cadrage conditionne le choix du prestataire bien plus que la beauté de sa documentation.

Ce que fait (vraiment) un PSP

• Collecte les données de paiement dans un environnement conforme PCI DSS, pour que le marchand n'ait pas à le faire
• Route les transactions vers un ou plusieurs acquéreurs et les réseaux (CB, Visa, Mastercard…)
• Orchestre l'authentification 3-D Secure imposée par la DSP2 en Europe
• Agrège les méthodes de paiement locales : wallets, virement, BNPL, iDEAL, Pix, Wero…
• Restitue : dashboard, rapports de règlement, exports de réconciliation, gestion des litiges
• Reverse les fonds (payouts) sur le compte du marchand, nets de commissions

Les critères qui comptent

Chapitre 2. Sandbox, clés API et sécurité des secrets.

Tout PSP sérieux fournit une sandbox, environnement de test isolé, sans argent réel, qui reproduit l'API de production et où votre équipe vivra les premières semaines. On commence par créer le compte de test et générer les clés API. Puis on provoque volontairement tous les scénarios (succès, refus, 3-D Secure, expiration) avant même de penser au parcours nominal.

• Cartes de test : 4242 4242 4242 4242 (succès chez Stripe) et ses variantes qui simulent refus, fonds insuffisants, carte volée, échec 3DS
• 3-D Secure simulé : pages de challenge factices pour tester frictionless et challenge sans vraie banque
• Webhooks de test : rejouables à la demande depuis le dashboard, indispensables pour le chapitre 4
• Données factices : IBAN de test, montants magiques déclenchant des comportements précis (ex. un montant qui force un refus)
• Dashboard sandbox : mêmes écrans qu'en production, pour former le support et la comptabilité avant le go-live

curl https://api.psp.example/v1/payments \
  -u "sk_test_51Hxxxxxxxxxxxx:" \
  -d amount=4990 \
  -d currency=eur \
  -d "payment_method_types[]=card" \
  -d "metadata[order_id]=CMD-2026-1042"

Dernier point de méthode, la sandbox se traite comme un environnement à part entière, avec sa propre configuration versionnée. Les équipes qui réussissent leur go-live maintiennent une parité stricte entre test et production : mêmes versions d'API, mêmes webhooks abonnés, mêmes devises, à une seule différence près, le préfixe des clés (sk_test_ contre sk_live_).

Chapitre 3. Créer un paiement : de l'intention à l'autorisation.

Les API modernes de paiement reposent sur le patron de l'intention de paiement (payment intent). Le serveur marchand annonce d'abord le montant qu'il veut encaisser, et le PSP renvoie un identifiant et un secret client. Le navigateur confirme ensuite le paiement avec les données de carte, qui ne transitent jamais par le serveur du marchand. Ce découpage en deux temps absorbe l'authentification 3-D Secure et les méthodes asynchrones.

{
  "id": "pay_9f2b7c4e",
  "object": "payment",
  "amount": 4990,
  "currency": "eur",
  "status": "requires_action",
  "next_action": { "type": "redirect_to_3ds" },
  "client_secret": "pay_9f2b7c4e_secret_Ab12Cd34",
  "metadata": { "order_id": "CMD-2026-1042" }
}

• Clé d'idempotence à la création : envoyez un en-tête Idempotency-Key unique par commande ; en cas de timeout réseau, rejouer la requête avec la même clé ne créera pas de second paiement
• Montant recalculé côté serveur : jamais de montant venu du navigateur, qu'un client outillé peut modifier
• Devise en ISO 4217 (eur, usd, jpy) et cohérente avec le compte de règlement
• `metadata.order_id` systématique : c'est le fil qui reliera paiement, commande et réconciliation comptable
• `return_url` propre : la page de retour affiche « paiement en cours de confirmation », elle ne valide rien elle-même

Chapitre 4. Webhooks : l'asynchrone fiable et l'idempotence obligatoire.

Un paiement moderne est asynchrone par nature : 3-D Secure peut prendre deux minutes, un virement deux jours, un litige deux mois. Le PSP vous notifie chaque changement d'état par webhook, une requête HTTP POST vers votre serveur. Ce canal, qui porte toute l'intégration, voit aussi naître la plupart des incidents de production : webhooks perdus, traités deux fois, ou arrivés dans le désordre.

Les cinq règles d'or du consommateur de webhooks

• Vérifier la signature sur le corps brut de la requête (avant tout parsing JSON) : sans cela, n'importe qui peut vous envoyer un faux payment.captured
• Répondre 2xx vite (< 5 s) : les PSP considèrent tout autre code ou timeout comme un échec et re-livrent la notification
• Traiter en file asynchrone : accuser réception d'abord, travailler ensuite, jamais d'envoi d'e-mail ou d'appel ERP dans le handler HTTP
• Dédupliquer par identifiant d'événement : la livraison est garantie au moins une fois, donc les doublons sont normaux, pas exceptionnels
• Tolérer le désordre et réconcilier : un payment.captured peut arriver avant le payment.authorized ; en cas de doute, interroger l'API (GET /payments/{id}) qui reste la source de vérité

app.post("/webhooks/psp", async (req, res) => {
  // 1. Signature sur le corps brut : rejeter sans traiter si invalide
  const signature = req.headers["psp-signature"];
  if (!verifyHmacSha256(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(400).send("invalid signature");
  }

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

  // 2. Idempotence : event.id est UNIQUE en base.
  //    Si l'insertion echoue, l'evenement a deja ete recu.
  const inserted = await db.webhookEvents.insertIfAbsent({
    id: event.id,
    type: event.type,
    receivedAt: new Date(),
  });
  if (!inserted) {
    return res.status(200).send("duplicate ignored"); // deja traite : 200 quand meme
  }

  // 3. Accuser reception vite, traiter en asynchrone
  await queue.enqueue(event);
  return res.status(200).send("ok");
});

Chapitre 5. Machine à états, capture et remboursement.

Un paiement traverse une machine à états, alors qu'un simple booléen « payé / pas payé » n'en distinguerait que deux positions. La modéliser explicitement dans votre code, avec la liste des transitions autorisées, reste le meilleur antidote contre les bugs d'intégration. Impossible alors de rembourser un paiement jamais capturé, ou d'expédier une commande encore en attente de 3DS.

type PaymentStatus =
  | "created"          // intention creee, en attente du client
  | "requires_action"  // 3-D Secure ou redirection en cours
  | "authorized"       // fonds reserves chez l'emetteur, rien n'est encaisse
  | "captured"         // capture demandee : l'encaissement est enclenche
  | "settled"          // fonds regles au marchand (J+1 a J+3)
  | "failed"           // refus emetteur, echec 3DS, expiration
  | "canceled"         // annulation (void) avant capture
  | "refunded";        // rembourse, totalement ou partiellement

const transitions: Record<PaymentStatus, PaymentStatus[]> = {
  created: ["requires_action", "authorized", "failed"],
  requires_action: ["authorized", "failed", "canceled"],
  authorized: ["captured", "canceled"],
  captured: ["settled", "refunded"],
  settled: ["refunded"],
  failed: [],
  canceled: [],
  refunded: [],
};

function assertTransition(from: PaymentStatus, to: PaymentStatus): void {
  if (!transitions[from].includes(to)) {
    throw new Error("Transition interdite : " + from + " -> " + to);
  }
}

Capturer : tout de suite ou plus tard ?

Annuler n'est pas rembourser

Tant que le paiement n'est qu'autorisé, on peut l'annuler (void), opération gratuite et quasi instantanée qui lève la réservation de fonds chez l'émetteur sans que rien ait bougé. Une fois capturé, il faut rembourser (refund). Un flux financier inverse part vers la carte du client, met 3 à 10 jours à apparaître sur son relevé, et les commissions initiales ne sont généralement pas restituées par le PSP.

• Remboursement partiel : plusieurs refunds successifs possibles, dans la limite du montant capturé, jamais au-delà
• Litige après remboursement : un client peut ouvrir un chargeback malgré un refund déjà émis ; conservez les preuves du remboursement pour la représentation
• Traçabilité : chaque refund a son propre identifiant, à raccrocher à l'order_id pour la réconciliation comptable

Chapitre 6. Go-live et checklist de recette.

Le passage en production d'une intégration de paiement se prépare comme un déménagement, où tout ce qui n'a pas été testé se cassera pendant le transport. Le go-live n'est pas un événement, c'est un processus. Il se déroule par bascule progressive, sous surveillance renforcée, avec une capacité de retour arrière à chaque étape.

La checklist de recette

• ✅ Paiement nominal carte : autorisation, capture, webhook, e-mail de confirmation, écriture comptable
• ✅ 3-D Secure : parcours frictionless ET challenge, plus un abandon en plein challenge
• ✅ Refus émetteur : message client compréhensible, pas de commande créée, possibilité de réessayer
• ✅ Timeout réseau à la création : rejeu avec la même clé d'idempotence → un seul paiement
• ✅ Webhooks : signature invalide rejetée, doublon ignoré proprement, événements dans le désordre absorbés
• ✅ Remboursement total et partiel, y compris l'échec de remboursement
• ✅ Montants : centimes vérifiés, devise sans décimales (JPY) si concernée, montant serveur ≠ montant client refusé
• ✅ Machine à états : chaque transition interdite lève bien une erreur
• ✅ Monitoring : alertes sur chute du taux d'autorisation, sur échecs de webhooks, sur file de traitement qui s'allonge
• ✅ Réconciliation : le rapport de règlement du PSP se rapproche automatiquement des commandes