Response structure

The common JSON envelope, statuses, error format and reference conventions used across the entire API.

10 min read

All API responses share a consistent envelope. You can therefore write a single response handler, regardless of the endpoint.

Success envelope

200 OK

{
"status": "OK",
"message": "The transaction has been fetched",
"code": 200,
"transaction": {
  "id": "trx_01JXXXXXXXXXXXXX",
  "status": "succeeded",
  "amount": 5000,
  "currency": "XAF",
  "created_at": "2026-05-24T10:21:08.000Z"
}
}

statusstringoptional

Human-readable HTTP reason phrase: OK, Created, Accepted, Unprocessable Content, Not Found, Too Many Requests…

messagestringoptional

Short description of the operation.

codeintegeroptional

HTTP code, duplicated in the body for clients that don't read headers.

<resource>object | arrayoptional

The resource concerned, named by its type (transaction, transfer, customer…).

Error envelope

Errors return a 4xx/5xx HTTP code, a human-readable status matching the HTTP reason phrase (never the literal string "error"), and — for validation failures — a detailed errors field.

422 Unprocessable Content

{
"status": "Unprocessable Content",
"message": "Some fields are invalid",
"code": 422,
"errors": {
  "amount": ["The amount must be at least 100."],
  "currency": ["The selected currency is invalid."]
}
}

The complete detail of error codes is documented in the API Reference → Errors.

Transaction statuses

Status	Meaning
`pending`	Initialized, awaiting customer action.
`processing`	Confirmed with the provider, settlement in progress.
`partial`	Some but not all of the amount was captured (split payments).
`succeeded`	Funds received. You can fulfill.
`failed`	Declined or expired.
`cancelled`	Cancelled by the customer or merchant.
`expired`	Not completed before the payment window closed.
`refunded`	Fully refunded after succeeding.
`partially_refunded`	Partially refunded after succeeding.

References

Resource identifiers are prefixed by their type, making them readable in your logs:

trx.xxxxxxxx — payment transaction
trf.xxxxxxxx — outgoing transfer
cus.xxxxxxxx — customer
evt.xxxxxxxx — webhook event

Dates

All timestamps are in ISO 8601 UTC format (2026-05-24T10:21:08.000Z).

Amounts in the smallest unit?

Unlike many PSPs, Wajub amounts are expressed in the major unit of the currency (e.g. 5000 = 5 000 XAF), because the CFA franc has no common subunit. Check the currency before any calculation.

Edit this page on GitHub

Need help?

Contact support GitHub Discussions Service Status