MobileWalletPartner Gateway Docs

Errors

Every GW-xxx code, what triggers it, and the HTTP status it comes back with.

Every error response shares one envelope:

{
  "success": false,
  "code": "GW-403-FORBIDDEN",
  "message": "This service is not enabled for your account.",
  "errors": null,
  "requestId": "0HNA1B2C3D4E5:00000001"
}
  • errors is present (a list of field-level messages) only on GW-400-BAD-REQUEST validation failures. It's null otherwise.
  • requestId correlates the error with the gateway's own server-side logs — useful when asking support to look into something. The gateway never returns a stack trace or other internal detail in an error body, by design, even for a GW-500.
  • An upstream provider/backend failure is never echoed back verbatim — you'll see a generic GW-500-SERVER-ERROR with a requestId, not the provider's own error text.

Transaction lifecycle codes

A status field on a transaction or a webhook delivery is always one of these — never a raw internal status string:

CodeMeaning
GW-00-PENDINGStill in progress. Also the default when an upstream status can't be confidently mapped — the gateway never guesses Success/Failed when unsure.
GW-01-SUCCESSCompleted successfully.
GW-02-FAILEDFailed. See failureCode for why.
GW-03-EXPIREDExpired before it could complete.
GW-04-CANCELLEDCancelled.

Why a payment failed: failure codes

Every failed, expired or cancelled transaction carries a failureCode and a failureMessage - in the create response, in GET /api/v1/transactions/{orderId}, in webhooks and in the dashboards. Branch on failureCode; failureMessage is a short sentence you can show your customer. statusMessage still carries the operator's own raw reason, for your logs only: it differs per operator and can change without notice. Both are null for a pending or successful transaction.

failureCodeWhat happenedWhat to do
ACCOUNT_NOT_FOUNDThe number has no mobile money account (or not with this operator).Ask the customer to check the number.
ACCOUNT_NOT_ALLOWEDThe account can't take part in this payment (blocked, not allowed to receive).The customer must contact their operator.
INSUFFICIENT_FUNDSThe customer's mobile money balance was too low for a deposit.Ask the customer to top up, then retry with a new partnerOrderId.
CUSTOMER_DECLINEDThe customer refused the payment prompt, or cancelled it.Retry only if the customer asks.
CUSTOMER_TIMEOUTThe customer didn't approve the prompt in time.Retry with a new partnerOrderId.
LIMIT_EXCEEDEDThe operator's own limit for this customer was reached.Try a smaller amount, or later.
PROVIDER_ERRORThe operator had a technical problem. Nothing moved.Retry later with a new partnerOrderId.
NOT_CREATEDThe operator never received the request, so nothing moved.Safe to retry with a new partnerOrderId.
UNKNOWNThe operator gave a reason the gateway doesn't recognise.Contact support with the transactionId.

New codes may be added over time; treat an unrecognised code like UNKNOWN. Existing codes are never renamed or removed.

When is a payment Failed?

A payment becomes GW-02-FAILED only when the operator says it failed, or confirms it has no record of it at all (NOT_CREATED). A timeout, a network error or an operator outage while the gateway sends your request never fails a payment on its own: the operator may have received it, and for a withdrawal the money may already be on its way. In that case the transaction stays GW-00-PENDING with the message "Awaiting confirmation from the operator", and the gateway keeps checking with the operator in the background until it knows - you get a webhook either way.

So never treat a pending payment as failed, and never retry a pending withdrawal with a new partnerOrderId: wait for the final status (webhook or GET /api/v1/transactions/{orderId}).

Request/response error codes

CodeHTTP statusWhen you'll see it
GW-400-BAD-REQUEST400A field failed validation (see errors[]); a money-out request exceeds your configured amount/daily limit; a money-out request would take your ledger balance below zero; a Sandbox credential used a number that is not a test number.
GW-401-UNAUTHORIZED401Wrong AppId/AppKey (both fail identically); a missing/invalid/stale request signature on a signed action; too many failed login attempts (dashboard accounts).
GW-403-FORBIDDEN403Your partner is suspended; your IP isn't on the whitelist; the service isn't enabled for your account; a Sandbox-only action was called with a Live credential; a dashboard session tried to read/act on another partner's data.
GW-404-NOT-FOUND404The transaction/resource you asked for doesn't exist (or doesn't belong to you — see below).
GW-409-CONFLICT409You tried to create something that already exists (e.g. a duplicate service code).
GW-429-RATE-LIMIT429You've exceeded your per-service rate limit. Back off and retry.
GW-503-SERVICE-UNAVAILABLE503The service is currently in maintenance mode.
GW-500-SERVER-ERROR500An unexpected internal error, or an upstream provider failure. Check requestId against the gateway's logs if this persists.

A note on 403 vs. 404 for "does this exist": when you ask for a resource that genuinely belongs to a different partner (a transaction id, a whitelist entry id, a callback delivery id), the gateway returns 403, not 404. A 404 would confirm the id exists but isn't yours — a 403 reveals nothing about whether it exists at all. Don't treat a 403 on a "not found"-shaped request as proof the resource exists; it may not.

On this page