Transactions

Every movement of money on Rolla — a deposit, payout, swap, or fee — is recorded as a transaction. This page explains the object’s lifecycle, the references that identify it, and which of the listing endpoints answers which question.

Types

`transaction_type`	Meaning
`deposit`	Money in — a virtual account or issued bank account was funded
`withdrawal`	Money out — a payout in the wallet’s own currency
`fx_withdrawal`	Money out with conversion — paid out in a different currency
`swap`	Conversion between two of your own wallets
`transfer`	A Rolla-to-Rolla movement between two Rolla accounts
`fee`	A fee booked as its own transaction (appears as a filterable type on listings)
`reversal`	A movement booked to unwind an earlier one

Lifecycle

pending ──▶ processing ──▶ sent ──▶ completed
   │             │           │
   └─────────────┴───────────┴────▶ failed / rejected

completed ────────────────────────▶ refunded (rare, on reversal)

Status	Meaning
`pending`	Created and awaiting processing. For a payout, funds are already debited from your wallet.
`processing`	Actively being processed — submitted to the bank or network.
`sent`	Dispatched to the provider/network and in flight, not yet confirmed final.
`completed`	Final. Deposit: funds available in your wallet. Payout: beneficiary paid.
`failed`	Could not complete. Payout funds are returned to your wallet.
`rejected`	Declined during approval or compliance review. Funds returned.
`refunded`	A previously completed transaction was reversed.
`exception`	Stuck in a state that needs manual intervention — neither in flight nor terminal.

Three more statuses exist but are not part of the ordinary payout or deposit path, and none of them emits a webhook: draft (created but awaiting an approval that hasn’t been given), and negotiating / cancelled, which belong to broker rate negotiation. Not every transaction passes through every state — fast rails can jump from pending straight to completed. Treat the status you receive as the source of truth and don’t assume ordering. Each change between the statuses in the table above emits a webhook event of the same name; the three statuses called out below it are the exception and emit nothing.

References

A transaction carries up to three identifiers:

Field	Assigned by	Use it for
`id`	Rolla	API lookups — Get Transaction
`external_reference`	You on most rails, Rolla on the rest	Reconciliation against your own system — Get Transaction accepts it in place of the `id`
`uetr`	SWIFT network	Tracing cross-border USD payouts — see the SWIFT guide

external_reference is the externalReference you sent at creation, with one exception worth planning around: NGN and mobile money payouts always get a Rolla-generated reference instead (NG-XXXXXXXX / MM-XXXXXXXX), because the provider imposes its own format. Webhook payloads call this same field reference. You can also attach up to 20 keys of your own metadata to a payout; it is echoed verbatim on every response and webhook for that transaction.

What’s always on the object

Twelve fields are present on every transaction, whatever its type: id, transaction_type, status, description, external_reference, fee_amount, source_amount, destination_amount, source_currency, destination_currency, created_at and updated_at. Everything else is conditional and is omitted entirely rather than returned as null when it doesn’t apply — exchange_rate on swaps only, virtual_account / payer / payment_rail on deposits only, beneficiary on payouts that carried one, uetr / tracking_codes once a cross-border payout has been assigned them, and metadata when you supplied some. Branch on a field’s presence, not on its value. All amounts are integers in minor units — kobo for NGN, cents for USD.

Finding your transactions

There’s more than one listing endpoint because they answer different questions — pick the one that matches what you’re trying to do:

Endpoint	Scope	Use when
List Wallet Transactions	Your account	Day-to-day history with currency, type, status, date, and search filters
Get Transactions	Your account	Simple paginated feed filtered by status and date
List Transactions Across Accounts	You plus every account you manage	Platform reconciliation — each row names its account; supports CSV
Export Transactions	Your account	CSV download of your history
Get Statement	Your account	Balance-carrying statement over a period

For anything real-time, prefer webhooks over polling these endpoints.

Welcome

Core Concepts

Types

Lifecycle

References

What’s always on the object

Finding your transactions

​Types

​Lifecycle

​References

​What’s always on the object

​Finding your transactions

Types

Lifecycle

References

What’s always on the object

Finding your transactions