Handle refunds

Issuing a refund is one API call, and Refunds documents it field by field. What that page cannot tell you is when your support agent is allowed to press the button, what the customer should see in the meantime, and what to do when the money does not come back.

That is this guide. Refunds are the operation where a mistake costs you real money, so the order of the steps matters more than usual.

A refund is a separate object with its own fate

The mental model people arrive with is wrong in a way that causes bugs. A refund is not a state the payment moves into. It is its own record, with its own id, its own status and its own webhooks, and it can fail while the payment it refunds stays succeeded forever.

So there are two things to track, not one. The payment answers "did they pay". The refund answers "did we give it back", and the second question can be answered no long after you told the customer yes.

1. Work out what is still refundable

You may refund the full amount, or part of it, or several parts of it until the original amount is exhausted. The number you are allowed to send is the payment amount minus everything already refunded.

The subtlety is that pending refunds count. A refund that has been recorded but not yet settled already reserves its share, which is what stops two support agents refunding the same money twice.

Do not compute that total from your own tables alone. Ask Wajub, which knows about refunds issued from the Dashboard too.

curl https://api.wajub.com/payments/trx_test_CSUGajfv9xh0XQ5wu2lx/refunds \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…"

Show that figure to your agent before they type anything. Most refund incidents are not API errors, they are someone refunding 5 000 on an order that had already been refunded 3 000.

2. Create the refund

The refund names the payment by its Wajub id. Your own order reference is not accepted here, because the lookup runs against the payment id and nothing else.

reason is required and comes from a closed list. It is not free text, and picking the honest value matters later when you are reading a month of refunds and trying to understand them.

curl https://api.wajub.com/refunds \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Idempotency-Key: refund-order-4172-1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment": "trx_test_CSUGajfv9xh0XQ5wu2lx",
    "amount": 2000,
    "reason": "product_not_received",
    "reference": "order-4172-partial"
  }'

Omit amount entirely for a full refund of whatever is left. Wajub computes the remainder itself, which is safer than sending a figure you calculated a moment earlier.

The idempotency key is what protects you from an agent double-clicking. Derive it from the refund attempt, not from the order, since one order can legitimately have several refunds. The same key always returns the original refund, a year later as well, and the same key with another amount is refused. It never comes free again, so number the refunds of an order: refund-4172-1, refund-4172-2.

3. Tell the customer the truth, which is "on its way"

The response comes back 201 Created. A live refund is born pending; a sandbox refund, like the one below, is born processing. Nothing has moved yet.

Note the field name: the payment is under transaction, not payment. The reference is the one you sent, so use it to find your own record again.

Crediting a Mobile Money wallet takes anywhere from a few minutes to a few hours depending on the operator. Say that. A support message promising an instant refund generates a second contact from the same customer twenty minutes later.

4. Follow it to its outcome

Three webhooks close the story, and they are the only reliable way to know. They arrive on the same endpoint you already built in Accept a payment, so there is nothing new to verify: only a branch to add.

The data of each is the refund itself. That means data.id is the refund, data.transaction is the payment it belongs to, and data.reference is the value you set.

5. When a refund fails

A failed refund is not a retry loop. The money is still with you, the customer is still owed it, and something in the path refused. Automating another attempt usually just fails again at the same place.

Put it in front of a person, with the reason attached. A failed refund always carries one, from the same list in production and in sandbox.

invalid_number, limit_exceeded and ops_failed only happen in production. Sandbox draws its failures from the others.

A retry is a new refund with a new idempotency key, exactly like a retried payment. Reusing the key of the failed attempt returns that failed refund and nothing happens.

6. Reconcile at the end of the month

Two things make refunds match your books without a spreadsheet archaeology session.

The first is reference. Set it on every refund, with a value that points back at your own record, exactly as you do on payments. It is returned on every read and it is the only field of yours that survives the round trip.

The second is the ledger snapshot on each refund. Once a succeeded refund has taken its amount from your balance, it carries the balance before and after, in the balance's own currency: the difference is what the refund took, the payment fee's share included when it moved with it. refund.succeeded is sent once that is done, so the webhook carries the snapshot as a read does. When the balance write is retried, the webhook can come a few minutes after the refund's status turned succeeded. In sandbox it is your sandbox balance's.

Those two figures let you reconstruct the order of operations on your balance without guessing from timestamps, which is what you actually need when two refunds settle in the same second.

7. Prove your failure handling works

Sandbox has a number built for exactly this. A payment made from a number ending in 000009 succeeds normally, and every refund against it fails.

So pay with +237670000009, refund it, and watch your refund.failed branch run for real. It is the only reliable way to test the path that matters most, and it is the path nobody ever exercises before production.