Virements internes
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/transfers |
Lister les virements internes |
POST |
/v1/transfers |
Virement interne |
GET |
/v1/transfers/{id} |
Consulter un virement interne |
GET /v1/transfers
Lister les virements internes
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/transfers
Virement interne
Déplace des fonds vers un autre compte de la plateforme, sans rail externe : aucun frais de rail, aucun appel sortant, une écriture au grand livre. Scope can_payout et l'option internal_transfers activée sur le compte.
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 |
|---|---|---|---|
recipient_id |
string | oui | Le compte destinataire, par son identifiant public. |
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. |
client_ref |
string | non | |
description |
string | non |
Réponses
201— Virement 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/transfers/{id}
Consulter un virement interne
La même vue masquée que GET /v1/payments/{id}.
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. |