Remboursements
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/{id}/refunds |
Les remboursements d'un encaissement |
GET |
/v1/refunds |
Lister les remboursements |
POST |
/v1/refunds |
Rembourser |
GET |
/v1/refunds/{id} |
Consulter un remboursement |
GET /v1/payments/{id}/refunds
Les remboursements d'un encaissement
Les remboursements de cet encaissement, du plus récent au plus ancien — le même objet que les éléments de GET /v1/refunds, la même pagination. L'encaissement est désigné par son identifiant ou sa référence interne ; celui d'un autre compte répond 404, comme un identifiant inconnu.
Paramètres
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
id |
path | oui | |
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)404— Aucun encaissement de cet identifiant (Error)429— Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)
GET /v1/refunds
Lister les remboursements
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. |
payment_id |
query | non | Ne lister que les remboursements de CE paiement : son identifiant ou sa référence interne. Un paiement inconnu, ou celui d'un autre compte, donne une liste vide. |
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/refunds
Rembourser
Remboursement total ou partiel d'un encaissement réussi ; les fonds sont prélevés sur le solde disponible au moment de l'appel. Omettre amount_minor rembourse le solde restant.
⚠️ L'en-tête Idempotency-Key doit être propre à CE remboursement, jamais l'identifiant du paiement d'origine : un paiement peut être remboursé en plusieurs fois, et une clé portant l'identifiant du parent ferait passer le second remboursement partiel pour un rejeu du premier — succès côté marchand, client non remboursé.
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 |
|---|---|---|---|
payment_id |
string | oui | L'encaissement parent : son identifiant ou sa référence interne. |
amount_minor |
string | non | 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. |
description |
string | non | |
reason |
string | non | Le motif du remboursement. Vocabulaire fermé, imposé par une contrainte de la base. |
Réponses
201— Remboursement 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— Remboursement refusé — le code d'erreur dit pourquoi :refund_exceeds_refundable(le montant dépasse ce qui reste remboursable ; l'erreur porteamount_refundable_minor),wave_partial_refund_window_closed(délai de remboursement partiel Wave dépassé : seul le remboursement total reste possible),wave_partial_refunds_disabled,wave_refund_window_closed(encaissement Wave déjà remboursé en partie et délai dépassé : plus aucun remboursement),payer_not_found(Wave ne nomme pas le payeur : un remboursement partiel ne peut pas lui être versé),insufficient_funds. (Error)429— Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)
GET /v1/refunds/{id}
Consulter un remboursement
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. |