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.
idstringfacultatiftrx_ prefix followed by a ULID. This is the canonical identifier to use in all API calls (GET /payments/{id}, POST /refunds body, etc.).authorization_urlstringfacultatifPOST /payments only.** The hosted payment page URL to redirect your customer to. An opaque session URL, do not parse or construct it manually.authorization_tokenstringfacultatifPOST /payments only.** Browser-safe single-use session token scoped to this payment. Pass as sessionId to Wajub Components for embedded checkout.referencestringfacultatifid (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.statusenumfacultatifpending, processing, succeeded, failed, cancelled, expired, partial, refunded, partially_refunded.amountintegerfacultatifamount_paidinteger?facultatifamount in partial payment scenarios).currencystringfacultatifXAF (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?facultatifcm.mtn, cm.orange, sn.wave).payment_methodobject?facultatif{ channel, account }.settledbooleanfacultatiftrue if funds have been credited to the available balance (credited_at is set).descriptionstring?facultatifitemsarray?facultatiftaxobject?facultatif{ amount, taxable_amount, rate, name, country, inclusive }.failure_reasonstring?facultatifstatus=failed.customerobject?facultatifmetadataobject?facultatifcallbackstring?facultatifsandboxbooleanfacultatiftrue for test-mode transactions.credited_atdatetime?facultatifcreated_atdatetimefacultatifLifecycle
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.