SILVERCLOUD / Article technique
Une confirmation de paiement fiable : la checklist côté serveur pour applications et sites web
Un client touche « Payer », voit une coche verte et ferme l'application. La commande est-elle payée ? Probablement. Mais quand il s'agit d'argent, « probablement » ne suffit pas. La coche indique seulement qu'un appareil est arrivé au bout d'un parcours. Si l'argent a réellement circulé, c'est le prestataire de paiement qui le sait, et votre serveur doit l'apprendre directement auprès de lui, par un canal que personne d'autre ne peut falsifier.
Cette checklist couvre les états d'un paiement, la confirmation côté serveur, les nouvelles tentatives sans risque, les remboursements, le rapprochement et les tests, pour les cartes, les e-wallets comme pour les virements par QR code.
Un écran de succès n'est pas une confirmation
Après le paiement, le client est renvoyé vers une URL de retour de votre site ou de votre application, souvent avec des paramètres comme ?status=success&order=1042. La prendre pour une preuve pose trois problèmes :
- N'importe qui peut la modifier. Remplacer
failedparsuccessdans un navigateur prend quelques secondes. - Elle peut ne jamais se charger. L'onglet est fermé, le réseau coupe ou l'application bancaire ne revient pas, et votre serveur n'apprend jamais qu'un paiement a réussi.
- Elle peut arriver avant l'argent. Certains moyens de paiement, en particulier les virements bancaires, restent en attente après que le client a terminé.
La page de retour doit afficher « Confirmation du paiement en cours » et interroger votre propre serveur, qui ne fait confiance qu'à des sources vérifiées. Le client ne décide jamais qu'une commande est payée.
Les états d'un paiement
Modélisez le paiement explicitement plutôt qu'avec un simple indicateur paid :
- Créé : enregistré auprès du prestataire, pas encore payé.
- En attente : le client a agi ou un virement est en cours ; le résultat n'est pas définitif.
- Réussi : le prestataire confirme les fonds.
- Échoué : refusé, annulé ou bloqué.
- Expiré : le délai de paiement s'est écoulé sans résultat.
- Partiellement remboursé et remboursé : argent rendu après le succès, en partie ou en totalité.
Les cartes peuvent ajouter un état « autorisé mais pas encore capturé » et, plus tard, des contestations (chargebacks). Écrivez les transitions autorisées dans le code : créé peut devenir en attente ; créé ou en attente peut devenir réussi, échoué ou expiré ; réussi peut devenir partiellement remboursé ou remboursé, et un paiement partiellement remboursé peut encore être remboursé ; rien ne revient à « créé » ni à « en attente ». Tout autre changement est un bug ou un cas à examiner.
Confirmer côté serveur, à partir d'une source vérifiable
Deux sources sont fiables, et les intégrations solides utilisent les deux.
Webhooks signés. Le prestataire appelle votre endpoint quand un événement se produit, et la plupart des prestataires signent chaque requête avec un secret partagé : en général un HMAC-SHA256 du corps brut de la requête, souvent accompagné d'un horodatage. Votre handler doit :
- Lire le corps brut exactement tel qu'il est reçu. Parser le JSON puis le resérialiser peut modifier les espaces, l'échappement ou l'ordre des clés, et la signature ne correspond plus.
- Calculer le HMAC et le comparer à l'en-tête en temps constant. Une comparaison de chaînes ordinaire s'arrête au premier caractère différent, et cet écart de temps peut révéler des informations sur la signature attendue.
- Rejeter les horodatages hors d'une courte fenêtre, souvent cinq minutes, pour qu'une requête interceptée ne puisse pas être rejouée plus tard ; un rejeu dans la fenêtre est bloqué par la déduplication sur l'identifiant d'événement.
- Vérifier le montant, la devise et la référence de commande par rapport à la commande créée. Une signature valide prouve qui a envoyé le message, pas que le bon montant a été payé pour la bonne commande. Stockez les montants en entiers dans la plus petite unité de la devise, jamais en virgule flottante.
L'API du prestataire. Votre serveur interroge le paiement par son identifiant avec votre clé secrète. Cela couvre les webhooks en retard ou perdus ; certaines équipes traitent chaque webhook comme un simple signal pour aller chercher l'état courant.
Les clés d'API et les secrets de webhook restent sur le serveur, hors de l'application et du dépôt de code, et doivent pouvoir être renouvelés sans interruption de service.
Idempotence : le même événement deux fois ne change rien
La plupart des prestataires livrent les webhooks « au moins une fois » : si votre endpoint dépasse le délai ou renvoie une erreur, l'événement revient, parfois plusieurs fois. Les doublons sont normaux, donc le traitement doit être idempotent.
- Dédupliquer par identifiant d'événement. Stockez les identifiants traités avec une contrainte d'unicité ; une livraison répétée ne change alors rien.
- Une transaction, une mise à jour. Enregistrez l'identifiant d'événement et modifiez la commande dans la même transaction de base de données ; en cas d'échec, les deux sont annulés et la nouvelle tentative repart proprement. Rendez la mise à jour conditionnelle (
WHERE status = 'pending'), pour qu'un webhook et une vérification par API arrivant en même temps ne traitent pas tous deux la commande. - Clés d'idempotence pour les nouveaux paiements et remboursements. Si le prestataire les prend en charge, dérivez la clé de votre propre identifiant de tentative : une nouvelle tentative après un délai dépassé renvoie alors le résultat initial au lieu de débiter deux fois. Sinon, enregistrez d'abord votre propre ligne avec une référence unique et recherchez-la avant toute nouvelle tentative.
- Événements dans le désordre. L'ordre de livraison n'est en général pas garanti ; un événement de succès peut arriver après un événement de remboursement. Fiez-vous à vos règles de transition plutôt qu'au dernier événement reçu, et récupérez l'état courant en cas de doute.
- Backoff. Relancez en cas de délai dépassé, d'erreur de connexion et de réponses 429 et 5xx, avec un backoff exponentiel, du jitter et un nombre maximal de tentatives. Ne relancez pas les erreurs de validation.
- Un délai dépassé signifie « inconnu », pas « échoué ». Le débit a peut-être eu lieu ; tranchez par une requête.
- Expiration planifiée. Une tâche repère les paiements encore en attente après leur délai, vérifie auprès du prestataire, et seulement ensuite les marque comme expirés. Un succès arrivé après l'expiration, ce qui se produit avec les virements, part en revue ou en remboursement selon une règle convenue à l'avance.
Répondez vite aux webhooks : enregistrez, validez la transaction, renvoyez 2xx, et mettez en file d'attente le travail lent comme les e-mails et l'expédition. Les handlers lents provoquent des délais dépassés, et les délais dépassés provoquent des doublons.
À quoi cela ressemble dans le code
Un handler minimal en TypeScript pour Node.js et PostgreSQL. Les noms d'en-têtes, l'encodage de la signature et la chaîne signée varient selon le prestataire ; la structure, elle, ne change pas.
import { createHmac, timingSafeEqual } from "node:crypto";
import { Pool } from "pg";
const pool = new Pool(); // reads the PG* environment variables
const SECRET = process.env.PAYMENT_WEBHOOK_SECRET!; // server-side only, never in the app
export async function handlePaymentWebhook(req: Request): Promise<Response> {
const raw = Buffer.from(await req.arrayBuffer()); // the exact bytes, before any JSON parsing
const timestamp = req.headers.get("x-signature-timestamp") ?? "";
const received = Buffer.from(req.headers.get("x-signature") ?? "", "hex");
const expected = createHmac("sha256", SECRET).update(`${timestamp}.`).update(raw).digest();
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300; // Unix seconds, 5 minutes
if (!fresh || received.length !== expected.length || !timingSafeEqual(received, expected)) {
return new Response("invalid signature", { status: 400 });
}
const event = JSON.parse(raw.toString("utf8"));
const db = await pool.connect();
try {
await db.query("BEGIN");
// event_id is the primary key: a repeated delivery inserts nothing.
const inserted = await db.query(
"INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT DO NOTHING", [event.id]);
if (inserted.rowCount === 1 && event.type === "payment.succeeded") {
// Only pending -> paid, and only if amount and currency match the order.
const paid = await db.query(
`UPDATE orders SET status = 'paid', paid_at = now()
WHERE id = $1 AND status = 'pending' AND amount = $2 AND currency = $3`,
[event.data.order_id, event.data.amount, event.data.currency]);
if (paid.rowCount === 0) await db.query("INSERT INTO payment_review (event_id) VALUES ($1)", [event.id]);
}
await db.query("COMMIT");
return new Response("ok");
} catch {
await db.query("ROLLBACK");
return new Response("retry later", { status: 500 }); // the provider retries
} finally {
db.release();
}
}Si aucune commande en attente ne correspond (déjà payée, expirée ou montant différent), l'événement va dans une table de revue au lieu de disparaître.
Remboursements, rapprochement et piste d'audit
Les remboursements sont des enregistrements distincts, liés au paiement, avec leurs propres états : un remboursement peut lui aussi être en attente ou échouer. La somme des remboursements partiels ne doit jamais dépasser le montant capturé. Envoyez les demandes de remboursement avec une clé d'idempotence, et ne changez le statut de la commande qu'après confirmation du prestataire.
Le rapprochement quotidien rattrape ce que tout le reste a laissé passer. Chargez le rapport de transactions ou de règlement du prestataire pour la veille, associez chaque ligne à vos enregistrements par l'identifiant de transaction du prestataire, puis comparez montant, devise et statut. Écarts typiques :
- Payé chez le prestataire, en attente chez vous : un webhook perdu, et un client qui a payé et attend toujours.
- Payé chez vous, inconnu du prestataire : un bug ou un abus, le cas le plus urgent.
- Montant ou statut différent : un remboursement partiel non enregistré, ou une confusion entre montants bruts, frais et règlement net.
Chaque écart part dans une file d'écarts avec un responsable et une note de résolution ; rien n'est corrigé en silence. Attention à l'heure de clôture du rapport : un paiement effectué vers minuit peut tomber sur des jours différents de chaque côté.
Piste d'audit. Conservez chaque webhook brut tel que reçu, avec ses en-têtes et le résultat de la vérification, pour pouvoir le rejouer, ainsi qu'un historique des changements de statut en ajout seul (append-only) : de quel état, vers quel état, quand, et à cause de quel événement, quelle tâche ou quelle personne. Ne journalisez jamais de secrets ni de numéros de carte complets ; avec une page de paiement hébergée ou des champs de paiement intégrés fournis par le prestataire, les numéros de carte n'atteignent jamais vos serveurs.
Les alertes doivent se déclencher sur des pics d'échecs de signature, des erreurs de traitement, des paiements bloqués en attente, des remboursements échoués, des écarts de rapprochement et des chutes du taux de réussite.
Testez les échecs, pas seulement le scénario idéal
Utilisez le sandbox ou le mode test du prestataire avec des clés de test, puis :
- Rejouez des webhooks. Enregistrez de vrais événements du sandbox comme fixtures ; envoyez-en un deux fois, inversez l'ordre, modifiez un octet du corps, utilisez un horodatage ancien.
- Injectez des pannes. Arrêtez le processus après le commit mais avant la réponse 2xx : le prestataire renvoie l'événement, et rien ne doit se produire deux fois. Coupez la base de données pendant une minute. Ajoutez de la latence aux appels vers le prestataire jusqu'à déclencher vos délais d'attente.
- Malmenez le client. Touchez deux fois « Payer », fermez le navigateur avant la redirection, ouvrez l'URL de retour avec des paramètres falsifiés.
Checklist avant la mise en ligne
- Une commande ne passe à « payée » que par un webhook vérifié ou une requête API côté serveur.
- Les signatures sont vérifiées sur le corps brut en temps constant ; les horodatages périmés sont rejetés.
- Montant, devise et référence de commande sont contrôlés par rapport à la commande.
- Les identifiants d'événement sont uniques ; les doublons renvoient 2xx sans effet de bord.
- L'enregistrement de l'événement et le changement de statut sont validés dans une seule transaction, avec une mise à jour conditionnelle.
- La création de paiements et de remboursements utilise des clés d'idempotence ou une recherche par votre propre référence.
- Les transitions sont définies dans le code ; un événement tardif ne peut pas faire reculer une commande.
- Le webhook répond dans le délai du prestataire ; le travail lent passe par une file d'attente.
- Les appels sortants ont des délais d'attente et des relances plafonnées avec backoff et jitter.
- Les paiements en attente expirent selon un calendrier, après vérification du statut ; les succès tardifs suivent un circuit défini.
- Les remboursements partiels ne peuvent pas dépasser le montant capturé.
- Le rapprochement tourne chaque jour, et chaque écart a un responsable.
- Les webhooks bruts et l'historique des statuts sont conservés ; les journaux ne contiennent ni secrets ni numéros de carte complets.
- Les alertes couvrent les échecs de signature, les erreurs de traitement, les paiements bloqués et les écarts de rapprochement.
silvercloud est une équipe de développement externalisée. Pour des entreprises partenaires, nous intégrons cette couche dans leurs applications et sites web, du checkout et des webhooks jusqu'aux remboursements et au rapprochement, et nous développons des systèmes de passerelle de paiement selon leurs exigences, puis nous livrons le travail pour que leurs équipes l'exploitent. Si vous préparez une intégration de paiement, envoyez-nous votre brief via silvercloud.city.