Intro
Khaime supports full and partial refunds against a completed transaction, executed through whichever gateway originally processed the payment.Context
Refunds act on atransaction_id — the same identifier a successful charge produces (echoed as data.id in the payment.succeeded webhook, and returned as transaction_id in the Create Charge response). If your business operates a marketplace, you can also refund a transaction that belongs to one of your active sub-merchants, not just your own charges.
Hows
Response
status reflects where the refund is in its lifecycle: pending_approval, processing, completed, failed, rejected, or needs_attention. Most gateway refunds land in processing immediately and move to completed once the gateway confirms.
Webhook
When the refund finishes, Khaime sends apayment.refunded webhook.
Refund timelines
Refunds are processed in the currency the customer originally paid in. If the customer paid in NGN, the refund is issued in NGN regardless of your baseline currency.
Error codes
Whys
Refunds are scoped to the calling API key’s business — and, for marketplace operators, to their active sub-merchants — because a refund reverses money movement, and the same ownership boundary that governs who can charge a transaction has to govern who can reverse it. Routing the reversal through the original gateway (rather than a generic reversal ledger entry) keeps the money flow symmetric: however the customer paid is how they get refunded.Why nots
- Refunds do not change currency — a refund is always issued in the currency the customer originally paid in, even if that differs from your baseline currency.
- There’s no bulk or scheduled refund endpoint — each refund is a single request against a single transaction.
- A suspended or pending sub-merchant’s transactions can’t be refunded through this endpoint by the marketplace operator until the sub-merchant is active again.