Payments

Initialize, retrieve, list and cancel payments via the Payments API.

The Payment (transaction) object represents a payment collection attempt. Its lifecycle goes from pending to succeeded (or failed). All routes share the base https://api.wajub.com.

Before you begin

To initialize a payment, you need a public key (pk_...) found in the Wajub dashboard.

Marketplaces: acting on behalf of a subaccount

Platforms can attribute a payment to a connected subaccount by sending an X-Sync header alongside their own key — see Subaccounts for the full contract and error cases.

Endpoints

Method	Path	Description
`POST`	`/payments`	Initialize a payment
`GET`	`/payments/{id}`	Retrieve a payment
`GET`	`/payments`	List payments
`DELETE`	`/payments/{id}`	Cancel a payment
`GET`	`/payments/{id}/refunds`	List refunds for a payment

The Payment object

Create response vs. retrieval response

The POST /payments (create) response includes two additional fields — authorization_url and authorization_token — that are not present on subsequent retrieval responses. These are the two most important fields in the create response.

idstringoptional

Unique transaction identifier — `trx_` prefix followed by a ULID. This is the canonical identifier to use in all API calls (`GET /payments/{id}`, `POST /refunds` body, etc.).

authorization_urlstringoptional

**Returned by `POST /payments` only.** The hosted payment page URL to redirect your customer to. An opaque session URL — do not parse or construct it manually.

authorization_tokenstringoptional

**Returned by `POST /payments` only.** Browser-safe single-use session token scoped to this payment. Pass as `sessionId` to Wajub Components for embedded checkout.

referencestringoptional

Public transaction reference — always equal to `id` (same `trx_xxx` value). Both fields exist for historical compatibility; use `id` in code. Note: the merchant-supplied `reference` field on `POST /payments` is a separate concept — it is your own internal order reference, stored on the object but not used as an API identifier.

statusenumoptional

Current state: `pending`, `processing`, `succeeded`, `failed`, `cancelled`, `expired`, `partial`, `refunded`, `partially_refunded`.

amountintegeroptional

Amount in the major unit of the currency (e.g. 25000 = 25 000 XAF). Always an integer — no decimal values.

amount_paidinteger?optional

Actual amount collected (may differ from `amount` in partial payment scenarios).

currencystringoptional

ISO 4217 currency code. Accepted values: `XAF` (Cameroon, Chad, CAR, Congo, Gabon, Equatorial Guinea), `XOF` (Côte d'Ivoire, Senegal, Benin, Mali, Burkina Faso, Togo, Niger, Guinea-Bissau), `NGN` (Nigeria), `GHS` (Ghana), `KES` (Kenya), `UGX` (Uganda), `TZS` (Tanzania), `RWF` (Rwanda). Contact support for additional currencies.

channelstring?optional

Payment channel used (e.g. `cm.mtn`, `cm.orange`, `sn.wave`).

payment_methodobject?optional

Resolved payment method: `{ channel, account }`.

settledbooleanoptional

`true` if funds have been credited to the available balance (`credited_at` is set).

descriptionstring?optional

Label visible to the customer on the payment page.

itemsarray?optional

Line items passed at initialization. Displayed on the payment page.

taxobject?optional

Tax details if Tax is active: `{ amount, taxable_amount, rate, name, country, inclusive }`.

failure_reasonstring?optional

Machine-readable failure code (see [Failure Reasons](/api/failure-reasons)). Present only when `status=failed`.

customerobject?optional

Customer profile used for this payment.

metadataobject?optional

Free-form data you passed at creation.

callbackstring?optional

Redirect URL after payment.

sandboxbooleanoptional

`true` for test-mode transactions.

credited_atdatetime?optional

ISO 8601 timestamp of settlement.

created_atdatetimeoptional

ISO 8601 creation timestamp (UTC).

Lifecycle

Events

Event	Trigger
`payment.created`	Payment initialized
`payment.processing`	Payment submitted to the provider
`payment.succeeded`	Payment successfully validated
`payment.failed`	Payment failed (see `failure_reason`)
`payment.cancelled`	Payment cancelled by the customer or expired

See the full event catalog for refund-specific events — a refund on a payment does not re-emit a payment.* event, it emits refund.* events instead.

RefundsRefund a completed payment.WebhooksReceive events in real time.Failure ReasonsThe full reason code catalog.