Versements
Page générée depuis la spécification OpenAPI que la passerelle sert (
GET /v1/openapi.json). Ne la modifiez pas à la main : elle est réécrite à chaque build.
| Méthode | Chemin | Description |
|---|---|---|
GET |
/v1/payouts |
Lister les versements |
POST |
/v1/payouts |
Effectuer un versement |
GET |
/v1/payouts/{id} |
Consulter un versement |
GET /v1/payouts
Lister les versements
Même pagination que les encaissements.
Paramètres
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
page |
query | non | Page, à partir de 1. |
per_page |
query | non | Taille de page, 100 au maximum. |
Réponses
200— OK (OperationList)401— Clé API manquante ou rejetée (Error)403— La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)429— Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)
POST /v1/payouts
Effectuer un versement
Envoi vers un porte-monnaie mobile ou un compte bancaire. Scope can_payout requis, et le compte doit être activé pour le mode réel.
⚠️ Un versement RÉSERVE les fonds à la création : un solde insuffisant est refusé sur le champ, il n'existe aucun découvert.
Nommer le corridor : platform_id ou platform_code. Les deux sont acceptés et aucun n'est obsolète. ⚠️ platform_code — orange, wave, yas — est le seul des deux qui désigne la même plateforme partout : les identifiants numériques sont attribués par ordre d'insertion en base, si bien qu'un platform_id relevé en bac à sable peut nommer un autre rail en production. Préférez le code. Envoyer les deux n'est accepté que s'ils concordent ; sinon la route répond 422 platform_conflict plutôt que d'en choisir un.
Paramètres
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
Idempotency-Key |
header | non | Clé d'idempotence propre à CETTE opération. Rejouer la même clé avec la même charge utile retourne l'originale ; la rejouer avec une charge utile différente est refusé (409). |
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
asset_id |
integer | oui | |
amount_minor |
string | oui | Montant en UNITÉS MINEURES, en chaîne de caractères. Jamais un nombre à virgule flottante : les deux perdent des centimes. Le nombre de décimales de l'actif est donné par GET /v1/assets. |
country |
string | oui | ISO 3166-1 alpha-2 |
platform_id |
integer | non | L'identifiant numérique du corridor. ⚠️ NON PORTABLE ENTRE ENVIRONNEMENTS : les identifiants de plateforme sont attribués par ordre d'insertion en base, si bien qu'un identifiant relevé en bac à sable peut nommer un autre rail en production. Préférez platform_code. Envoyez l'un ou l'autre ; envoyer les deux n'est accepté que s'ils concordent, et refusé par un 422 platform_conflict sinon. |
platform_code |
string | non | Le code STABLE du corridor — 'orange', 'wave', 'yas'. Insensible à la casse. Désigne la même plateforme dans tous les environnements, ce que platform_id ne fait pas. Envoyez celui-ci ou platform_id. |
platform_account_handle |
string | non | Le sous-compte débité. Vide = le primaire du corridor. |
rail |
string | non | |
recipient |
object | oui | Destinataire TYPÉ : identifier_type dit quelle sorte d'adresse vous détenez (msisdn, iban, alias…) et identifier la porte. phone seul reste accepté et s'interprète comme (msisdn, phone). Fournir les deux formes, ou un type sans valeur, est refusé. |
recipient.name |
string | non | |
recipient.phone |
string | non | |
recipient.identifier |
string | non | |
recipient.identifier_type |
string | non | |
recipient.country |
string | non | ISO 3166-1 alpha-2 |
rtp_ref |
string | non | Rails PI uniquement : l'identifiant de bout en bout de la demande de paiement que ce versement accepte. |
client_ref |
string | non | |
description |
string | non |
Réponses
201— Versement créé (Operation)401— Clé API manquante ou rejetée (Error)403— La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)409— Clé d'idempotence rejouée avec une charge utile différente (Error)422— Requête recevable mais refusée : champ manquant, corridor fermé, solde insuffisant (Error)429— Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)503—platform_codemomentanément irrésoluble : le catalogue des plateformes est illisible (temporarily_unavailable). Ce n'est pas un refus — renvoyer la même requête après Retry-After (Error)
GET /v1/payouts/{id}
Consulter un versement
La même vue masquée que GET /v1/payments/{id}, avec le même contrôle de propriété.
Paramètres
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
id |
path | oui | Identifiant interne, référence de l'opération, ou votre propre client_ref. |
Réponses
200— OK (Operation)401— Clé API manquante ou rejetée (Error)403— La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)429— Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)
Schémas
Les formes renvoyées par les opérations ci-dessus.
OperationList
| Champ | Type | Description |
|---|---|---|
data |
Operation[] | |
data[].id |
string | L'identifiant public de l'opération. C'est celui des chemins /v1/payments/{id}. |
data[].ref |
string | Notre référence interne, lisible. Distincte de l'identifiant : citez-la au support. |
data[].client_ref |
string | La référence que vous avez fournie à la création, rendue telle quelle. |
data[].kind |
string | payin | payout | withdrawal | refund | chargeback | adjustment | transfer | rebalance. Le même objet sert les cinq familles ; ce champ dit laquelle. |
data[].status |
string | L'état détaillé du rail. ⚠️ Pour décider si l'argent est arrivé, lisez outcome : status porte le détail du parcours et son vocabulaire dépend du rail. |
data[].outcome |
string | pending | succeeded | failed | cancelled | expired | reversed. Le seul champ sur lequel fonder une décision métier. |
data[].asset_id |
integer | L'actif de l'opération, par son identifiant (GET /v1/assets). |
data[].amount_minor |
string | Le montant BRUT en unités mineures, en chaîne de caractères. |
data[].fee_minor |
string | Les frais prélevés, en unités mineures. |
data[].net_minor |
string | Le net en unités mineures : amount_minor moins fee_minor. |
data[].platform_id |
integer | La plateforme qui a porté l'opération. Absent tant qu'un encaissement hébergé attend que le payeur choisisse. |
data[].is_test |
boolean | Vrai pour une opération créée avec une clé de test. Aucun argent réel ne bouge. |
data[].payment_url |
string | La page de paiement hébergée, quand le rail en fournit une. Absent tant que la soumission n'a pas abouti. |
data[].deeplink |
string | Le lien profond vers l'application du rail, quand il en fournit un. |
data[].qrcode_url |
string | Le QR à présenter au payeur, quand le rail en fournit un. |
data[].risk |
Risk | État du contrôle des risques (FRAML). Absent si l’opération n’a pas été évaluée — ce qui n’est pas la même chose que « clear ». Le webhook sortant et cette lecture rendent le même bloc. |
data[].risk.status |
string | held : les fonds ne sont pas partis. review : le paiement a suivi son cours, quelque chose est examiné. clear : rien à signaler. |
data[].risk.case_ref |
string | Référence du dossier opérationnel, à citer auprès du support. Null lorsque la retenue relève d’un examen de conformité. |
data[].risk.case_kind |
string | Accompagne case_ref ou rien du tout. |
data[].risk.reason |
string | Le seul texte que ce bloc porte, et il est identique pour toute retenue. |
data[].risk.signals |
object[] | Signaux produit, consultatifs. Absent s’il n’y en a aucun. |
data[].risk.signals[].code |
string | |
data[].risk.signals[].detail_fr |
string | |
data[].amount_refunded_minor |
string | Encaissements seulement : la somme des remboursements ABOUTIS, en unités mineures. |
data[].amount_refund_pending_minor |
string | Encaissements seulement : la somme des remboursements EN COURS, en unités mineures. |
data[].amount_refundable_minor |
string | Encaissements seulement : ce qui peut être remboursé MAINTENANT, en unités mineures — le montant d'origine moins les remboursements aboutis et en cours, ou "0" quand la règle de remboursement n'en permet plus aucun (encaissement non abouti, délai Wave dépassé après un remboursement partiel…). |
data[].refund_count |
integer | Encaissements seulement : le nombre de remboursements non échoués. |
data[].partial_refund_deadline |
string | Encaissements Wave seulement : jusqu'à quand un remboursement partiel est possible (RFC 3339). Absent pour les autres rails, ou quand les remboursements partiels Wave sont désactivés. |
page |
integer | |
per_page |
integer |
Error
| Champ | Type | Description |
|---|---|---|
error |
object | |
error.code |
string | |
error.message |
string |
Operation
Une opération monétaire — encaissement, versement, remboursement, virement ou rééquilibrage. Le même objet dans les cinq familles.
| Champ | Type | Description |
|---|---|---|
id |
string | L'identifiant public de l'opération. C'est celui des chemins /v1/payments/{id}. |
ref |
string | Notre référence interne, lisible. Distincte de l'identifiant : citez-la au support. |
client_ref |
string | La référence que vous avez fournie à la création, rendue telle quelle. |
kind |
string | payin | payout | withdrawal | refund | chargeback | adjustment | transfer | rebalance. Le même objet sert les cinq familles ; ce champ dit laquelle. |
status |
string | L'état détaillé du rail. ⚠️ Pour décider si l'argent est arrivé, lisez outcome : status porte le détail du parcours et son vocabulaire dépend du rail. |
outcome |
string | pending | succeeded | failed | cancelled | expired | reversed. Le seul champ sur lequel fonder une décision métier. |
asset_id |
integer | L'actif de l'opération, par son identifiant (GET /v1/assets). |
amount_minor |
string | Le montant BRUT en unités mineures, en chaîne de caractères. |
fee_minor |
string | Les frais prélevés, en unités mineures. |
net_minor |
string | Le net en unités mineures : amount_minor moins fee_minor. |
platform_id |
integer | La plateforme qui a porté l'opération. Absent tant qu'un encaissement hébergé attend que le payeur choisisse. |
is_test |
boolean | Vrai pour une opération créée avec une clé de test. Aucun argent réel ne bouge. |
payment_url |
string | La page de paiement hébergée, quand le rail en fournit une. Absent tant que la soumission n'a pas abouti. |
deeplink |
string | Le lien profond vers l'application du rail, quand il en fournit un. |
qrcode_url |
string | Le QR à présenter au payeur, quand le rail en fournit un. |
risk |
Risk | État du contrôle des risques (FRAML). Absent si l’opération n’a pas été évaluée — ce qui n’est pas la même chose que « clear ». Le webhook sortant et cette lecture rendent le même bloc. |
risk.status |
string | held : les fonds ne sont pas partis. review : le paiement a suivi son cours, quelque chose est examiné. clear : rien à signaler. |
risk.case_ref |
string | Référence du dossier opérationnel, à citer auprès du support. Null lorsque la retenue relève d’un examen de conformité. |
risk.case_kind |
string | Accompagne case_ref ou rien du tout. |
risk.reason |
string | Le seul texte que ce bloc porte, et il est identique pour toute retenue. |
risk.signals |
object[] | Signaux produit, consultatifs. Absent s’il n’y en a aucun. |
risk.signals[].code |
string | |
risk.signals[].detail_fr |
string | |
amount_refunded_minor |
string | Encaissements seulement : la somme des remboursements ABOUTIS, en unités mineures. |
amount_refund_pending_minor |
string | Encaissements seulement : la somme des remboursements EN COURS, en unités mineures. |
amount_refundable_minor |
string | Encaissements seulement : ce qui peut être remboursé MAINTENANT, en unités mineures — le montant d'origine moins les remboursements aboutis et en cours, ou "0" quand la règle de remboursement n'en permet plus aucun (encaissement non abouti, délai Wave dépassé après un remboursement partiel…). |
refund_count |
integer | Encaissements seulement : le nombre de remboursements non échoués. |
partial_refund_deadline |
string | Encaissements Wave seulement : jusqu'à quand un remboursement partiel est possible (RFC 3339). Absent pour les autres rails, ou quand les remboursements partiels Wave sont désactivés. |