Cycle de vie payin / payout / refund

Tous les types suivent la même logique. La transaction est PENDING pendant tout le traitement, puis atteint un statut terminal. Votre intégration fait deux choses : déclencher l'opération, puis réagir au résultat (webhook ou lecture du statut).

Payin

PENDING ──► SUCCESS
   │           │
   │           └─► REFUNDED / PARTIALLY_REFUNDED (si remboursé plus tard)
   └────────► FAILED

• Création (POST /v1/payins) : la transaction est créée en PENDING. Le montant est validé contre les limites de l'opérateur. Le téléphone est validé contre son format.
• Action du client : selon l'opérateur, le payeur peut avoir une étape à faire. Le champ nextAction de la réponse vous dit quoi afficher. Voir Traiter nextAction.
• Succès : la transaction passe à SUCCESS. Les frais sont déduits. Le montant net est crédité sur votre wallet. Il est disponible tout de suite, ou d'abord en attente si un délai s'applique (voir Settlement différé). L'événement payment.payin.succeeded est émis.
• Échec : la transaction passe à FAILED. L'événement payment.payin.failed est émis.

Payout

PENDING ──► SUCCESS
   └──────► FAILED

• Création (POST /v1/payouts) : le montant (frais compris) est réservé tout de suite sur votre solde disponible. Le payout part en traitement. Si le solde ne suffit pas, la requête échoue avec INSUFFICIENT_FUNDS (409) et rien n'est débité.
• Réponse API : uniquement les détails serveur (transactionId, status, amount, currency). Pas de checkoutUrl ni de nextAction — un payout n'a pas d'écran payeur (contrairement au payin).
• Résultat : soit le bénéficiaire reçoit les fonds et la transaction passe à SUCCESS, soit l'opération échoue en FAILED et le montant réservé revient sur votre solde. Suivez l'état via webhook (payment.payout.*) ou GET /v1/transactions/{id}.
• Une réservation n'est jamais « bloquée ». Quel que soit le scénario, les fonds finissent chez le bénéficiaire ou de retour sur votre solde.

Refund

Un refund est une transaction de type REFUND. Elle est rattachée au payin d'origine via originalTransactionId.

Refund :         PENDING ──► REFUNDED  |  FAILED
Payin d'origine : SUCCESS ──► PARTIALLY_REFUNDED ──► REFUNDED

• Demande (POST /v1/refunds) : crée le remboursement en PENDING. Le montant peut être total ou partiel, dans la limite du montant remboursable.
• Résultat : en cas de succès, le refund passe à REFUNDED et payment.refund.succeeded est émis. En cas d'échec, il passe à FAILED avec payment.refund.failed, et le payin d'origine ne change pas. Certains opérateurs traitent le remboursement de façon asynchrone : le refund reste alors PENDING jusqu'à la confirmation.