Key Concepts

Before writing code, take a few minutes to understand the core concepts. They'll make every API call and webhook event immediately clear.

Payment lifecycle

A payment goes through a well-defined state machine:

pending → processing → succeeded
                    → failed
                    → expired
                    → cancelled

How payments move through states

1. You call POST /payments — creates a transaction in pending.
2. The customer completes the payment on the hosted page (pay.wajub.com).
3. Wajub processes the charge with the best available provider (see Orchestration).
4. Wajub sends a payment.succeeded webhook to your server.
5. You verify the status via GET /payments/{id} and fulfill.

Sandbox vs Live

Wajub provides two completely isolated environments. A single base URL serves both — the environment is determined by the API key you use.

API keys

Three key types, each with a specific purpose:

Session tokens

The hosted checkout page (pay.wajub.com) uses a session token — not an API key:

• Returned by POST /payments as authorization_token.
• Scoped to a single transaction.
• Browser-safe — can be exposed in the frontend.
• Expires when the transaction reaches a terminal state.
• Used by @wajub/js SDK as sessionId.

// Backend creates the session
const { authorization_token } = await wajub.payments.create({...});

// Frontend uses the token
wajub.mount("#checkout", { sessionId: authorization_token });

Orchestration model

When you process a payment, Wajub doesn't just forward it — it orchestrates:

1. Routing — Selects the best provider for the channel, country and amount.
2. Execution — Calls the provider's API.
3. Fallback — If the primary provider fails, retries with the next one.
4. Reconciliation — Matches provider callbacks with the original transaction.

All of this is transparent to you — you just create a payment and listen for the webhook.

References

Resource identifiers use a prefix_ format, making them immediately readable in logs and code:

Amounts

Unlike many payment providers, Wajub expresses amounts in the major unit of the currency (e.g. 5000 = 5 000 XAF, not 500 000 centimes). CFA franc currencies have no common subunit, so this avoids confusion.

"Payment" vs "transaction"

Wajub uses both terms, and they refer to the same object:

• Payment — the business concept. You create a payment, a customer pays, you fulfill.
• Transaction — the internal representation. The API response uses "transaction": {...} as the root key, and the id field is prefixed trx_.

In practice: you call POST /payments, receive transaction.id = "trx_xxx", and listen for payment.succeeded webhooks. The terms are interchangeable in this documentation.

Next steps

• Quickstart — code your first payment.
• Orchestration — how routing and fallback work.
• Webhooks — receive payment.succeeded reliably.