API de paiement : préparer une intégration fiable

Écrire un contrat de données métier

Décrivez les données que votre application connaît avant de demander un paiement. La commande doit porter une référence stable, une devise et un montant validé côté serveur. Précisez aussi le contexte du marchand et l’environnement utilisé. Deux boutiques appartenant au même groupe peuvent avoir des connexions différentes ; leur sélection ne doit pas reposer sur une valeur librement modifiable par le client. Le contrat de données sert de point commun aux développeurs, aux personnes qui suivent les commandes et à celles qui traitent les incidents.

Intégration et API

Représenter le montant sans ambiguïté

Suivez exactement le format décrit par l’API que vous intégrez. La documentation OrsunPay utilise des chaînes décimales pour les montants ; n’importez pas mécaniquement une convention rencontrée chez un autre fournisseur. Définissez la devise avec le montant et vérifiez leur cohérence avant l’appel. Prenez un exemple réel de votre panier, incluant les ajustements convenus, puis suivez cette valeur jusqu’au résultat. Une interface visuellement correcte peut masquer une erreur de conversion si les systèmes n’emploient pas la même représentation.

Page de paiement hébergée

Préparer les répétitions de requête

Imaginez qu’une création de paiement arrive au serveur mais que sa réponse se perde. Le client technique ne sait pas encore si l’opération existe. Une nouvelle requête aveugle peut produire un doublon. Utilisez l’idempotence selon le contrat documenté et conservez la relation entre la demande métier et sa clé. Une même commande n’autorise pas automatiquement la réutilisation éternelle d’une clé : les règles de nouvelle tentative et de nouvelle opération doivent être explicites dans votre application et dans la documentation de l’API.

Vérifier les notifications à leur réception

Le webhook est une entrée publique de votre système : son contenu doit être authentifié avant de modifier une commande. OrsunPay documente une signature HMAC-SHA256 calculée sur les octets bruts du corps. Modifier ou reconstituer ce corps avant vérification peut changer le résultat. Conservez les secrets hors du code exposé au navigateur et limitez les informations sensibles dans les journaux. Les guides officiels de Stripe et Mollie montrent également pourquoi les événements serveur font partie du cycle normal d’un paiement.

Séparer réception et action métier

Une notification valide ne doit pas déclencher immédiatement toutes les actions de façon irréversible et répétable. Enregistrez l’événement, retrouvez la commande et appliquez une transition autorisée. L’expédition ou l’activation doit rester idempotente lorsque le même résultat revient. Testez aussi une notification tardive après que votre écran a déjà affiché une attente. Le navigateur sert à informer le client ; la décision finale doit suivre le résultat serveur vérifié et les règles de votre commande.

Prévoir une exploitation possible dès le départ

Donnez à l’équipe une façon de retrouver une opération avec une référence métier, sans lui demander d’explorer des logs contenant des données inutiles. Documentez qui peut relancer un traitement interne et quand contacter le PSP. OrsunPay unifie l’intégration de vos propres comptes fournisseurs, mais ne remplace ni leurs accords ni leurs décisions d’acceptation. Les SDK ou packages publics doivent être confirmés avant d’être intégrés au plan de livraison ; l’existence de code ne suffit pas à établir une publication utilisable.

• Tester une création dont la réponse est perdue.
• Tester une signature invalide et un événement reçu deux fois.
• Vérifier montant, devise et contexte marchand.
• Définir une procédure pour les statuts inconnus.
• Faire relire le parcours d’incident par le support.

Sources

• Documentation Stripe sur les webhooks
• Documentation Mollie sur les paiements