Event types
You choose which events to subscribe to per endpoint, so you can listen only for the ones you care about (most integrations just needtransaction.completed and transaction.failed).
Transaction events
Each event maps 1:1 to a transaction status.| Event | Status | When it’s sent |
|---|---|---|
transaction.pending | pending | The transaction has been created and is awaiting processing. For a payout, funds have been debited; for a deposit, incoming funds have been detected. |
transaction.processing | processing | The transaction is actively being processed (submitted to the bank/network). |
transaction.sent | sent | Funds have been dispatched to the provider/network and are in flight (not yet confirmed final). |
transaction.completed | completed | The transaction finalized successfully. For a deposit, funds are available in your wallet; for a payout, the beneficiary has been paid. |
transaction.failed | failed | The transaction could not be completed. Funds for a failed payout are returned to your wallet. |
transaction.rejected | rejected | The transaction was rejected (e.g. declined during approval or compliance review). |
transaction.refunded | refunded | A previously completed transaction was reversed/refunded. |
Account events
These cover the onboarding lifecycle of the accounts you manage via the API (the additional business/individual accounts you create under your profile), plus the deposit accounts provisioned for them.| Event | When it’s sent |
|---|---|
account.onboarded | An account was created (onboarding started). |
account.submitted | The account’s KYB/KYC application was submitted for review. |
account.approved | The account’s application was approved and it’s ready to transact. |
account.virtual_account.created | A deposit (virtual) account — bank transfer or crypto — was provisioned for the account. |
Account lifecycle
An account onboarded through the API typically moves through:account.onboarded
The account has been created and onboarding has begun. Complete its application data and upload the required documents.
account.approved
The application was approved. The account can now transact, and deposit accounts can be issued for it.
account.virtual_account.created
A deposit account (NGN/USD bank transfer details, or a crypto address) is now available for funding. The
data.virtual_account object carries the details — the same shape you’d get from the funding instructions endpoint.Transaction lifecycle
A typical transaction emitstransaction.pending and then one or more later events as it progresses to a terminal state:
transaction.processing / transaction.sent (in flight)
The transaction is being processed and dispatched to the bank or network.
transaction.completed (success path)
The transaction finalized. For a deposit, funds are now available in your wallet; for a payout, the beneficiary has been paid.
Not every transaction emits every event, and intermediate events (
processing, sent) may be skipped depending on the rail and how fast the transaction settles. A deposit that is auto-confirmed may jump from pending to completed; a payout that fails will emit transaction.pending then transaction.failed. Always treat the event’s status as the source of truth and don’t assume ordering.The event_id field
Each logical event has a stable event_id. The same logical event (for example, “transaction X completed”) always carries the same event_id, even if it is delivered more than once. Use it to make your handler idempotent.
Distinguishing deposits from payouts
The payload’sdata.type field is either deposit or payout. The data.rail field tells you whether it’s fiat or stablecoin. See Payloads for the full schema and samples.