Skip to main content

​
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 need transaction.completed and transaction.failed).

​
Transaction events

Each event maps 1:1 to a transaction status.

​
Payout tracking events

A UETR (Unique End-to-end Transaction Reference) is the SWIFT-network reference for a payment. It is the reference a beneficiary’s bank recognises, so it’s what you quote when a recipient asks where their money is or when you need a payment traced. The UETR is not known when the payout is sent. It is assigned by the correspondent network and we retrieve it afterwards — typically within minutes, sometimes hours later, during the destination market’s banking day. So it can’t be part of a status event, and it arrives as its own event:
1

transaction.sent

The payout has been dispatched. No UETR yet.
2

transaction.uetr.assigned

The reference is now available. It may arrive after transaction.completed — treat the two as independent.
This event is how you learn the UETR as soon as it exists — subscribe to it if you display or store payment references for your users. You can also read it back at any time from the transaction endpoints, which return uetr and tracking_codes on the payout once it has one. Use the event to be told, and the endpoints to look up a payout you already know about.
Two things to expect:
  • Not every payout gets one. The UETR exists for cross-border payouts on the SWIFT network. Local-rail payouts and stablecoin transfers have no UETR, and a corridor that never returns one emits no event. Never block your own flow waiting for it.
  • It is sent once per payout. The reference doesn’t change once assigned, so the event carries a stable event_id and a redelivery is recognisable as the same event.

​
Fee events

A fee your account bears for an account you manage moves through three stages, and each is announced separately. Subscribe to all three, or only to the one you act on.
If you subscribe to fee.charged alone, your balance will move without an event to explain it — sometimes for a long time, since a fee is held for as long as the transaction that incurred it stays unsettled. Take fee.pending and fee.released too if you reconcile on available balance.
All three carry the same shape; event and effect say which stage it is. amount is in minor units — 25000 means 250.00, the same scale the transaction endpoints report. fee_type is what the fee was charged for — withdrawal, payin or card_funding. related_transaction_id is the movement that incurred it and incurred_by_account the account that made it, so the charge can be attributed without matching on amount or timing. Each stage carries its own event_id, so a redelivery of the same stage is recognisable while the three stages never suppress one another.
A fee borne by the account that incurred it does not produce these events — there is no separate charge to announce, and the fee is reported as fee_amount on that account’s own transaction. To list fees rather than be pushed them, filter List Transactions Across Accounts on transactionType=fee.

​
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.

​
Payer name events

These cover Named Payouts — the affiliated payer names you register so a beneficiary sees a related entity of yours, or your end-customer, on a payout instead of your own business name.
payer_name.approved does not mean the name can be used. Registration with our payout partners happens after approval and can take hours. payer_name.active is the event to gate your payouts on.
There is no processing event: payer_name.approved already says the name is being worked on, so the next thing you hear is an outcome. A name that is later archived emits nothing — you archived it, so you already know.

​
Payer name lifecycle

1

payer_name.changes_requested (optional detour)

Something needs correcting. Update the name to answer the note and resubmit; it can happen more than once.
2

payer_name.approved

Rolla approved the name and registration with our payout partners has started. Nothing is required from you.
3

payer_name.active

The name is registered. Pass its payer_name_id as payerNameId on a payout, or make it your default.
4

payer_name.rejected / payer_name.action_required (dead ends)

Rolla declined the name, or every partner refused it. Neither resolves on its own: submit a different name, or contact support.
A payout may be created against a name that is not active yet — it is accepted and simply waits. For anything time-sensitive, hold the payout until payer_name.active arrives.

​
Account lifecycle

An account onboarded through the API typically moves through:
1

account.onboarded

The account has been created and onboarding has begun. Complete its application data and upload the required documents.
2

account.submitted

The application has been submitted for review.
3

account.approved / account.rejected / account.changes_requested (review outcome)

Review resolves one of three ways: approved (the account can now transact, and deposit accounts can be issued for it), rejected (the application was declined), or changes_requested (the account must update its details and resubmit — after which it emits account.submitted again).
4

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.

​
Deposit account requests

A USD deposit account request is reviewed before the account is provisioned, so it resolves one of three ways:
1

account.virtual_account.created

The request was approved and the deposit account exists.
2

account.virtual_account.changes_requested

Something on the request needs correcting. data.bank_account_request.reason explains what. Re-issue the account with the corrections and the same request reopens — no duplicate is created.
3

account.virtual_account.declined

The request was declined, with the reason in data.bank_account_request.reason. Further requests for the same currency are blocked until the decision is lifted.
These three events are scoped to the deposit account request, not the account’s KYB. account.rejected and account.changes_requested refer to the account’s application and are unrelated.

​
Transaction lifecycle

A typical transaction emits transaction.pending and then one or more later events as it progresses to a terminal state:
1

transaction.pending

The transaction has been created and is awaiting processing.
2

transaction.processing / transaction.sent (in flight)

The transaction is being processed and dispatched to the bank or network.
3

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.
4

transaction.failed / rejected (failure paths)

The transaction did not complete. Funds for a failed/rejected payout are returned to your wallet. A transaction.refunded event may follow a completed transaction that is later reversed.
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.
transaction.uetr.assigned sits outside this sequence. It reports a reference becoming available rather than a change to the payment, carries no status of its own, and may arrive at any point after the payout is sent — including after it has completed.

​
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’s data.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.