Refunds

Prepare a refund

POST/v1/refunds

Creates a refund pending_approval against a succeeded payment for at most its unrefunded balance; approval follows the payout rules (PO-6).

Parameters

Idempotency-Keystringin headerrequired: Unique per logical request, kept 24 hours. A retry with the same key and body replays the first response.

Body

payment_intent_idstringrequired
amountintegerrequired
reasonstringrequired

Responses

200Replay of an identical request within 24 h
201Refund prepared
400Invalid request
401Missing, invalid or revoked API key
403business_initiation_disabled
409idempotency_conflict
422no_healthy_connection, capability_unsupported or insufficient_refundable_balance
429More than 100 requests in this minute for this keyRetry-After
500Internal error

Error bodies and every code are listed under Errors; limits under Rate limits and Idempotency.

curl -X POST http://localhost:3000/api/v1/refunds \ -H "Authorization: Bearer $DCP_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"payment_intent_id":"pay_01JB8Q4Z2N5V7K3M9P6R0T1W8X","amount":125000,"reason":"reason"}'

{ "id": "mo_01JB8Q4Z2N5V7K3M9P6R0T1W8X", "object": "refund", "livemode": false, "status": "pending_approval", "amount": 125000, "currency": "KES", "payment_intent_id": "pay_01JB8Q4Z2N5V7K3M9P6R0T1W8X", "reason": "reason", "provider_ref": "provider ref", "failure_code": "failure code", "failure_message": "failure message", "attempts": [ { "attempt": 1, "channel": "api", "status": "pending", "provider_ref": "provider ref", "provider_code": "provider code", "provider_message": "provider message", "started_at": "2026-10-22T09:30:00.000Z", "finished_at": "2026-10-22T09:30:00.000Z" } ], "created_at": "2026-10-22T09:30:00.000Z", "completed_at": "2026-10-22T09:30:00.000Z" }