Statuts de transaction

Branchez-vous sur la partition, pas sur la liste

La seule chose qui compte dans un statut est la case dans laquelle il tombe. Écrivez votre logique sur cette partition ; ne l'écrivez pas sur une énumération exhaustive, qui peut s'enrichir.

Terminaux — l'issue est acquise

cancelled est un échec financier, au même titre que failed. Si votre code teste status === "failed" pour conclure à un échec, il laissera passer les transactions annulées.

Ces deux statuts portent aussi une cause normalisée — voir Causes d'échec.

Non terminaux — ne concluez rien

created, initiated, pending, processing.

Ces quatre statuts ne signifient rien d'autre que « en cours ». Ils ne sont ni un succès partiel, ni un échec imminent. N'expédiez pas de marchandise dessus, et n'annulez pas de commande dessus.

Les transitions sont monotones

Un statut terminal ne bouge plus. Une transaction completed ne redeviendra jamais pending ; une transaction failed ne deviendra jamais completed.

Vous pouvez donc traiter la première notification terminale comme définitive, et ignorer sans risque une notification ultérieure qui porterait le même statut.

pending_approval

Un pay-out part en brouillon pending_approval quand l'appelant a le droit de l'initier mais pas de l'exécuter : un utilisateur du tableau de bord sans le droit d'approuver, ou une clé d'API qui porte PAYOUT_INITIATE sans PAYOUT_APPROVE. Il attend alors l'approbation d'un membre de l'organisation depuis le tableau de bord ; aucun fonds ne bouge avant.

Pour une clé, la réponse de POST /v1/pay-out est un 201 avec status: "pending_approval", et non le 200 d'un pay-out exécuté. Traitez le 201 comme « déposé, pas parti ». Aucun webhook n'est émis pour pending_approval vers une intégration par clé : relisez la transaction (GET /v1/transactions/by-id/{transactionId}) pour savoir si le brouillon a été approuvé. Un brouillon que personne n'approuve passe en cancelled au-delà de 7 jours.

Seule une clé qui porte aussi PAYOUT_APPROVE contourne ce circuit. La portée se choisit à la création de la clé : voir Authentification.

Où lire le statut

Le statut vous parvient par le webhook sortant, à chaque transition. C'est le canal prévu pour ça.

Le statut se relit aussi à la demande, avec la même clé d'API : GET /v1/transactions/by-id/{transactionId} ou GET /v1/transactions?orderId=…. C'est le rattrapage d'une notification manquée — voir Réconciliation.

Le reçu public porte bien un status, mais ses plafonds de requêtes en font un point d'affichage pour le payeur, pas une source de polling serveur.