Paiements
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/payments |
Lister les encaissements |
POST |
/v1/payments |
Créer un encaissement |
GET |
/v1/payments/{id} |
Consulter une opération |
GET /v1/payments
Lister les encaissements
Lecture servie par le modèle de lecture, sur un réplica : aucun rapport ne peut ralentir un paiement.
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/payments
Créer un encaissement
Crée une opération d'encaissement et retourne de quoi faire payer le client — une URL de paiement, un lien profond ou un QR selon le rail. asset_id est un identifiant, pas un symbole : GET /v1/assets donne ceux que le compte peut utiliser. La plateforme se nomme par identifiant OU par code — voir ci-dessous. Omettre rail laisse le routage choisir ; le nommer force un rail et échoue plutôt que de basculer.
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 | L'actif, par son identifiant (GET /v1/assets). |
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 | Pays de l'opération, 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 à créditer. Vide = le compte primaire du corridor. |
rail |
string | non | Force un rail précis au lieu de laisser le routage choisir. |
payer |
object | non | Le payeur. Sur les lectures, les coordonnées sont masquées. |
payer.name |
string | non | |
payer.phone |
string | non | |
payer.email |
string | non | |
payer.country |
string | non | ISO 3166-1 alpha-2 |
client_ref |
string | non | Votre propre référence. Ressort sur les lectures et les webhooks. |
description |
string | non | |
channel |
string | non | |
expires_in_seconds |
integer | non | Durée de validité de l'intention de paiement. |
success_url |
string | non | Où le payeur revient après une page de paiement hébergée (Wave, Orange). Succès. return_url est accepté comme synonyme — c'est le contrat de la plateforme historique, et un marchand intégré contre elle envoie cette orthographe. ⚠️ Les rails hébergés REFUSENT sans les deux : le pilote s'arrête avant tout appel réseau. |
return_url |
string | non | Où le payeur revient après une page de paiement hébergée (Wave, Orange). Succès. success_url est accepté comme synonyme — c'est le contrat de la plateforme historique, et un marchand intégré contre elle envoie cette orthographe. ⚠️ Les rails hébergés REFUSENT sans les deux : le pilote s'arrête avant tout appel réseau. |
failed_url |
string | non | Où le payeur revient après une page de paiement hébergée (Wave, Orange). Annulation ou échec. cancel_url est accepté comme synonyme — c'est le contrat de la plateforme historique, et un marchand intégré contre elle envoie cette orthographe. ⚠️ Les rails hébergés REFUSENT sans les deux : le pilote s'arrête avant tout appel réseau. |
cancel_url |
string | non | Où le payeur revient après une page de paiement hébergée (Wave, Orange). Annulation ou échec. failed_url est accepté comme synonyme — c'est le contrat de la plateforme historique, et un marchand intégré contre elle envoie cette orthographe. ⚠️ Les rails hébergés REFUSENT sans les deux : le pilote s'arrête avant tout appel réseau. |
Réponses
201— Opération créée (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/payments/{id}
Consulter une opération
Lecture locale : rien n'est demandé au rail. Les coordonnées du payeur sont masquées, parce que le modèle de lecture ne détient jamais les brutes.
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)404— Inconnue, ou appartenant à un autre compte (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. |