> For the complete documentation index, see [llms.txt](https://qosic.gitbook.io/qospay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qosic.gitbook.io/qospay/merchant-api/integration-rules/idempotency-and-retries.md).

# 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 :

{% stepper %}
{% step %}

## Enregistrez la requête

Enregistrez la requête et `transRef` avant l’envoi.
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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**.
{% endstep %}

{% step %}

## Interrogez le statut de la transaction

Interrogez `GET /api/v1/transactions/status/{transRef}`.
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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`.
{% endstep %}

{% step %}

## 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.
{% endstep %}
{% endstepper %}

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é.