# Rembourser

`POST https://api.payiz.app/v1/refunds`

Demande une clé secrète qui porte le geste « Paiements · rembourser ».

Rend tout ou partie d’un paiement.

Sans « amount », Payiz rend tout ce qui reste. Le motif est obligatoire et doit être un de ceux que la plateforme accepte : GET /v1/refund_reasons les donne.

## Les en-têtes

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `Idempotency-Key` | texte | — | Conseillée : rejouée, la même clé rend la première réponse au lieu de refaire le geste. |

## Ce qu'on envoie

Un corps JSON.

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `payment` | texte | oui | Le paiement à rendre. |
| `amount` | entier | — | Sans montant, Payiz rend tout ce qui reste sur le paiement. |
| `reason` | texte | oui | Pris parmi GET /v1/refund_reasons. Ne les écrivez pas en dur. |

## Ce qu'on reçoit

`201` · un objet `refund`

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `object` | « refund » | — | Le genre de l’objet rendu : il ne change jamais. |
| `id` | texte | — | Un identifiant préfixé « rem_ », par exemple rem_01j9x3kq7m4tzv8qhw2n. |
| `payment` | texte | — | Un identifiant préfixé « pay_ », par exemple pay_01j9x3kq7m4tzv8qhw2n. |
| `amount` | entier | — | Ce qui repart chez le payeur. |
| `currency` | texte | — | Le code ISO 4217, en majuscules. |
| `status` | « pending » · « processing » · « succeeded » · « failed » | — | Où en est le remboursement. |
| `reason` | texte | — | Le motif, choisi parmi ceux que Payiz accepte. |
| `fee` | entier | — | Les frais du remboursement. |
| `fee_returned` | entier | — | La commission d’encaissement rendue au marchand. |
| `amount_debited` | entier | — | Ce que l’opération coûte en tout au marchand. |
| `failure_message` | texte ou null | — | Ce que l’opérateur a répondu, quand ça a échoué. |
| `created` | entier ou null | — | Des secondes depuis 1970, ou null. |
| `livemode` | vrai ou faux | — | Faux en mode test : aucun argent ne circule. |

## La demande

```bash
curl https://api.payiz.app/v1/refunds \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: remboursements-creer-01" \
  -H "Content-Type: application/json" \
  -d '{
    "payment": "pay_01j9x3kq7m4tzv8qhw2n",
    "amount": 10000,
    "reason": "requested_by_customer"
  }'
```

## La réponse

```json
{
  "object": "refund",
  "id": "rem_01j9xb2te8r5mzq4kd7n",
  "payment": "pay_01j9x3kq7m4tzv8qhw2n",
  "amount": 10000,
  "currency": "XOF",
  "status": "processing",
  "reason": "requested_by_customer",
  "fee": 100,
  "fee_returned": 250,
  "amount_debited": 9850,
  "failure_message": null,
  "created": 1790006292,
  "livemode": false
}
```