WasaaPay API (1.0.0)

Creates a new collection (payment) via mobile money, card, or bank rail. Requires an Idempotency-Key header; retrying the same key returns the original result rather than creating a duplicate transaction.

If the collection is settled through a split rule that has an escrow recipient, a releasable escrow hold is minted ASYNCHRONOUSLY after the collection succeeds — so there is no escrow hold ID on this response. Retrieve it with GET /escrow?transaction_id={id} or from the escrow.held webhook (which carries your reference). The hold_in_escrow flag on its own is only a ledger-bucket hint and creates no releasable hold.

Creates a refund transaction against a successful collection. Omit amount (or the request body) to refund the full remaining amount; supply amount in minor currency units for a partial refund. The refund is returned as a transaction with type=refund and parent_transaction_id set to the original collection's ID. Requires an Idempotency-Key header; retrying the same key returns the original result rather than creating a duplicate refund.

Creates a payer-facing checkout session for a fixed amount/currency and returns a one-time client_token capability secret. Unlike createCollection (where the merchant picks the rail at creation), the PAYER later chooses a rail from allowed_rails and pays via payCheckoutSession — authorized ONLY by the client_token, never the merchant API key. Requires an Idempotency-Key header; retrying the same key returns the original session (and its token) rather than minting a duplicate.

Returns the non-sensitive fields the hosted checkout renders. Authorized by the session's client_token (the X-Checkout-Token header or a client_token query parameter), NOT the merchant API key; the client_token is never echoed back. A session past its expires_at is reported as expired.

The payer picks a rail from the session's allowed_rails and supplies the matching payer reference; this creates the underlying collection through the same path as createCollection and marks the session completed. Authorized by the session's client_token (the X-Checkout-Token header or a client_token query parameter). Requires an Idempotency-Key header; a same-key replay returns the original result, and a completed or expired session rejects new pays. Returns the resulting transaction (action_url / ussd_code are populated when a payer challenge is required).

Cursor-paginated list of transactions, filterable by status, rail, and date range.

Programmatically onboard a seller, vendor, rider, or individual earner. Triggers a KYC case per the assigned kyc_tier.

Returns every dashboard user under the authenticated merchant. The listing is always scoped to the caller's merchant, so one merchant can never enumerate another merchant's users. Requires the team:read permission (admin, finance, read_only, or compliance roles).

Returns every wallet owned by the authenticated merchant (one per currency) or its sub-merchants.

Defines how a transaction's value is divided among recipients, with optional escrow per recipient.

Returns this merchant's escrow holds, newest first. A releasable hold is created ASYNCHRONOUSLY after a collection whose split rule has an escrow recipient succeeds, so the hold ID is not present on the collection response — this endpoint (filtered by transaction_id) and the escrow.held webhook are how you retrieve it. Filter by transaction_id, status, and/or sub_merchant_id (the escrowed recipient).

Returns one escrow hold owned by this merchant. A hold that belongs to a different merchant (or does not exist) returns 404 RESOURCE_NOT_FOUND — the API never reveals the existence of another merchant's hold.

Releases escrowed funds to the hold's recipient (the escrowed sub-merchant). Omit amount (or the whole body) to release the full remaining amount; supply amount in minor currency units for a partial, per-milestone release. A partial release moves the hold to partially_released and leaves remaining_amount held; a release that clears the remainder moves it to released. This endpoint is also the programmatic trigger for a delivery_confirmation hold. Requires an Idempotency-Key header (a missing key is rejected 422 VALIDATION_ERROR); retrying the same key returns the original result rather than releasing again.

Returns escrowed funds to the MERCHANT's available balance (NOT to the original card / mobile-money payer). The merchant then issues any refund to the payer out of band (for example via POST /collections/{id}/refunds). Omit amount (or the whole body) to return the full remaining amount; supply amount in minor currency units for a partial return. Requires an Idempotency-Key header (a missing key is rejected 422 VALIDATION_ERROR); retrying the same key returns the original result rather than returning again.

Creates a payout_batch and its individual payouts in a single call, for paying many sub-merchants at once.

Returns the batch, its aggregate status, and its individual payouts.