POST
/api/v1/refundsIssue a refund
Issues a refund against an order. Calls Paystack /refund under the hood. Supports the `Idempotency-Key` header — retrying with the same key inside 24h returns the cached response.
Authorization
Requires the refunds:write scope. See the auth guide for how to mint a token with the right scopes.
Parameters
Body parameters
| Field | Type | Description |
|---|---|---|
orderId required | string | Order CUID to refund against. e.g. cl9j4k2l3000001jx8h2zfb1m |
amountKobo required | number | Amount to refund, in kobo. Cannot exceed remaining refundable. e.g. 4500000 |
reason required | string | Refund reason — one of "wrong_item", "damaged", "size_issue", "late", "customer_request", "fraud", "duplicate", "other". e.g. damaged |
reasonNote optional | string | Free-form note shown on the refund detail. e.g. Item arrived torn |
restockItems optional | boolean | Whether to return stock to variants. Default true. e.g. true |
Headers
| Field | Type | Description |
|---|---|---|
Idempotency-Key optional | string | Client-supplied retry key. Same value in 24h = same response. e.g. refund_idem_2025_11_20_001 |
Response
A successful call returns 200 OK with the body shown to the right. Errors follow the standard envelope.