Transaction & Payout Statuses

The status values used across both APIs, and how to act on them
View as Markdown

Both APIs represent the lifecycle of a transaction with a status field. Knowing these values up front is essential for building reliable polling logic and webhook handlers.

Payments API Statuses

Used for transactions created via Generate Transaction and retrieved via Get Transactions:

StatusMeaning
completedThe payment was successfully received.
pendingThe payment is still awaiting completion.
cancelledThe transaction was canceled by the payment gateway, failed, or expired.

A transaction is only marked cancelled for one of three reasons: the payment gateway canceled it, it failed outright, or it expired before the customer completed payment.

The Disbursement API’s Wallet endpoints (Get Wallets filter, Get Wallet Transactions filter) also reference this same three-value set (completed, pending, cancelled) when filtering wallet-level activity.

Disbursement API Statuses

Used for payouts created via Process Disbursement and retrieved via Get Transactions (Disbursement):

StatusMeaning
pendingThe payout has been submitted and is processing.
cancelledThe payout was either failed or cancelled. No funds were transferred.
completedThe payout was successfully processed and confirmed. Funds have been transferred.

The Disbursement API uses the same three status values as the Payments API (pending, cancelled, completed) — there is no separate failed or success value. See Webhooks & Redirects for how these appear in webhook payloads.

Why This Matters

  • Generate Transaction and Process Disbursement both return a pending status immediately upon submission — neither call is synchronous with the actual payment/payout completing. You must check the final status afterward.
  • The two ways to learn the final status, in order of preference:
    1. Listen for a webhook on the callback_webhook_url you supplied, which fires once the final status is known (see Webhooks & Redirects). This should be your primary mechanism.
    2. Look up the single transaction via Get Transactions filtered by your reference_no, as a fallback — not for routine polling or listing (see Looking Up Transactions).
  • For the Payments API, a successful payment also triggers a browser redirect to success_redirect_url (or failure_redirect_url on failure/cancellation).

Looking Up a Transaction’s Status

Listing/pagination via Get Transactions is discouraged and being phased out — see Looking Up Transactions for details. Avoid unfiltered or broad-range polling, especially as your transaction volume grows; it’s expensive to serve and is exactly the pattern the platform is moving away from.

The recommended approach is:

  1. Rely on webhooks first — your callback_webhook_url fires once the final status is known, so you shouldn’t need to poll for routine tracking (see Webhooks & Redirects).
  2. When you do need to check a status directly, filter by reference_no only — look up the one transaction you care about rather than listing/paging through many:
GET /v1/biller/transactions?reference_no=YOUR_REFERENCE_NO
GET /v1/api/disbursement/transactions?reference_no=YOUR_REFERENCE_NO

A dedicated single-transaction inquiry endpoint keyed only on reference_no is planned to replace Get Transactions for this use case — see Looking Up Transactions for the full migration guidance.