Failure Reasons

A 4xx means the request was refused. This page is about the other kind of failure: a request that succeeded, created a resource, and then failed later at the operator. The object and its webhook carry two fields that explain it.

Where it appears

The same pair is delivered in the payment.failed, transfer.failed and refund.failed webhooks, since those payloads are the resource itself.

Codes Wajub issues itself

These are stable and exhaustive. They are decided before, or instead of, any call to an operator, which is why Wajub controls their spelling.

Transfers

The last two come on a cancelled payout from API version 2026-10-12, and on a failed one before.

Refunds

A failed refund always carries one of these, live and sandbox alike. When the provider reports the failure, Wajub maps it to one of these codes; failure_message keeps the provider's sentence when it sent one.

A refund that cannot be completed automatically is not dropped: Wajub completes it, and it stays pending (or processing) in the meantime. failed is the end of that road, not the start. A retry is a new refund.

Failed payments

A failed payment carries the reason of its last failed attempt, on the payment and in the payment.failed webhook:

Older failed payments may carry neither field.

The status still separates the three cases that change what you do next:

For every attempt, not only the last, open the payment in Konsole: its timeline shows each attempt, the provider involved, and the raw gateway response. That is also where the dashboard reads from when it prints a plain-language explanation next to a failed payment.

Codes the operator issues

Anything not in the tables above is the provider's own error code, passed through unchanged. There is no shared vocabulary between operators: MTN, Orange, Wave and a card acquirer each name the same customer mistake differently, and a new provider can introduce a new code without a release on our side.

const RETRY_NEVER = new Set([
'team_restricted',
'admin_rejected',
'merchant_rejected',
'invalid_recipient',
]);

function onTransferFailed(transfer) {
const reason = transfer.failure_reason;

if (RETRY_NEVER.has(reason)) {
  return escalateToSupport(transfer);
}

if (reason === 'no_provider') {
  return scheduleRetry(transfer, { in: '15m' });
}

return notifyMerchant(transfer.failure_message);
}

Sandbox is deterministic

The sandbox calls no operator: the test number, account or address you use decides the outcome, so every branch of your handler can be exercised on purpose before you go live. The tables of test numbers are in Test scenarios.

Transfers. The last six digits of a Mobile Money test number (and the suffix of a bank test account or a crypto test address) pick the result. A transfer that fails carries one of three reasons:

A number that is not a test number is refused with a 422 that lists the ones to use.

Refunds. The payment method of the refunded payment decides: a Mobile Money payment paid with a number ending in 000000 is refunded, one ending in 000001 to 000004 or 000009 fails; the card 4000 0000 0000 5423 is paid but its refunds always fail; bank and crypto payments are always refunded. Only a payment with no payment method attached is left to chance, 70 % success. The failure_reason of a failed sandbox refund is drawn from the same list as live, in Refunds.

Payments. The last six digits of the test number decide the status: 000002 ends failed, 000003 ends expired, 000004 ends cancelled. 000001 is refused at once with a 402 and error_code: insufficient_funds, as a live decline is, and the payment stays pending. A sandbox payment that fails says why with a fixed pair, chosen by the test number or card you paid with: