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

idstringoptional

Unique transaction identifier (internal UUID format).

referencestringoptional

Public transaction reference in `trx.XXXXXXXXXXX` format.

statusenumoptional

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

amountnumberoptional

Amount in the major unit of the currency (e.g. 25000.00 = 25 000 XAF).

amount_paidnumber?optional

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

currencystringoptional

ISO 4217 code (XAF, XOF, NGN, GHS, KES…).

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

Payment lifecycle

pendingprocessingsucceededwebhook payment.succeeded

Terminal statesfailedwebhook payment.failedcancelledcustomer or expiryrefundedvia POST /refunds

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.