Transactions
Transaction Statuses
Every transaction status, its meaning, the webhook it fires, and what to do about it.
Status reference
| Status | Meaning | Webhook event | Your action |
|---|---|---|---|
pending | Recorded, not yet submitted to a provider | N/A | Wait for processing |
processing | In flight with a provider or internal ledger leg | N/A | Wait for webhook |
completed | Settled: funds posted, immutable | *.completed | Fulfill the order |
failed | Stopped at a known stage with a failure.code | *.failed | Read failure.code, act |
unknown | Provider outcome ambiguous (timeout); being reconciled | transaction.updated | Do not retry. Wait. |
unknown is terminal for your integration
A transaction in unknown must not be retried. The provider may have processed
it. Reconciliation resolves it to completed or failed and fires the
webhook.
Re-submitting an unknown outcome risks a double charge. Use
Idempotency to make retries safe instead.
Failure codes by stage
When a transaction fails, the response and webhook include failure.code and
failure.stage:
failure.stage | failure.code examples | Meaning |
|---|---|---|
method_selection | METHOD_NOT_SELECTABLE | Payment method not enabled |
pin_stepup | PIN_REQUIRED | Customer PIN verification needed |
compliance | COMPLIANCE_DENIED | Screening blocked the operation |
limits | LIMIT_EXCEEDED | Above the customer's tier limit |
settlement | INSUFFICIENT_FUNDS | Wallet cannot cover amount + fee |
provider_call | PROVIDER_ERROR | Upstream provider failed |
Mapping events to your state
| Webhook event | Your action |
|---|---|
payment.completed | Mark the order paid, deliver the service |
payment.failed | Read failure.code, surface the reason to the user |
transfer.completed | Mark the payout done |
transfer.failed | Release any reserved resource, notify the user |
exchange.completed | Confirm the currency conversion |
wallet.funded | Credit the customer's balance in your system |