idempotency and retries

Génération de la référence

transRef est la clé d’idempotence et de rapprochement du marchand. Générez-la avant d’effectuer une requête financière et conservez-la avec la commande métier.

Format recommandé :

<operation>-<UTC-date>-<unique-sequence>

Exemples :

COL-20260810-000001
FT-20260810-000001
BILL-20260810-000001

Les références doivent être uniques par marchand pour les requêtes de collecte, de transfert et de paiement de facture. Une réutilisation produit Payment reference already exists ou Transaction exist with the specified transaction reference.

Algorithme sûr de nouvelle tentative

Pour les requêtes de découverte, de validation et de reporting, réessayez les erreurs réseau transitoires avec un backoff exponentiel et du jitter.

Pour les requêtes financières POST :

1

Enregistrez la requête

Enregistrez la requête et transRef avant l’envoi.

2

Traitez une réponse HTTP complète

Si une réponse HTTP complète est reçue, suivez les indications de statut et de gestion des erreurs correspondantes.

3

Considérez les résultats inconnus

Si la connexion expire, est réinitialisée ou renvoie HTTP 500, considérez le résultat comme inconnu.

4

Interrogez le statut de la transaction

Interrogez GET /api/v1/transactions/status/{transRef}.

5

Ne renvoyez pas la requête si la référence existe

Si la référence existe, ne renvoyez pas la requête POST financière. Continuez à interroger le statut.

6

Vérifiez une seconde fois avant de renvoyer la requête

Si le statut indique que la référence n’existe pas, attendez brièvement puis vérifiez une seconde fois avant de décider s’il faut renvoyer exactement la même requête avec le même transRef.

7

Ne générez jamais une nouvelle référence

Ne créez jamais un nouveau transRef simplement pour contourner un résultat incertain. Cela peut créer un paiement en double.

Le rythme de polling recommandé est : 5 secondes, 15 secondes, 30 secondes, puis toutes les 60 secondes jusqu’au timeout métier. Ajoutez du jitter et arrêtez dès qu’un statut final est retourné.