The payout object

A payout is one movement of money out to a recipient. It carries what left the account, what arrived, the identifiers each rail hands back for tracing it, and the trail of states it passed through. Amounts are decimal strings, not numbers. Most of the tracing identifiers are null until the rail assigns them, and some never apply — a bank payout has no transaction hash, and a crypto payout has no wire reference.

Example

{
  "payout_id": "99999999-aaaa-bbbb-cccc-dddddddddddd",
  "user_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "recipient_id": "cccccccc-dddd-eeee-ffff-000000000000",
  "quote_id": null,
  "reference": "INV-2026-0042",
  "memo": "September invoice",
  "origin": "payout",
  "from_amount": "1000.00",
  "from_currency": "USD",
  "to_amount": "986.50",
  "to_currency": "USD",
  "payment_method": "wire",
  "txn_hash": null,
  "uetr": "20260901MMQFMP3K000123",
  "reference_number": "20260901MMQFMP3K000123",
  "provider_reference": "act-7781",
  "status": "COMPLETED",
  "metadata": {},
  "sender": { "name": "Alice Smith", "company_name": "Northwind Trading LLC", "country": "USA" },
  "recipient": { "name": null, "company_name": "Acme Supplies LLC", "country": "US" },
  "events": [
    { "event_id": "11111111-1111-1111-1111-111111111111", "status": "CREATED", "created_at": "2026-09-01T12:00:00.000Z" }
  ],
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:10.000Z"
}

What the payout is

Field	Type	Description
`payout_id`	string, uuid	The payout’s identifier.
`user_id`	string, uuid	The user the payout belongs to.
`recipient_id`	string, uuid	Who was paid.
`origin`	string	What started it. Values
`status`	string	Where the payout has got to. Values
`payment_method`	string or `null`	Which rail it went out on, in lower case. Values
`created_at`	string, date-time	When the payout was created, ISO 8601.
`updated_at`	string, date-time	When it last changed, ISO 8601.
`metadata`	object	Key-value pairs you attached. `{}` when you attached none — see Metadata.

The money

Field	Type	Description
`from_amount`	string	What left the account, as a decimal string.
`from_currency`	string	The currency of `from_amount`.
`to_amount`	string	What the recipient got, as a decimal string.
`to_currency`	string or `null`	The currency of `to_amount`.
`quote_id`	string or `null`	The quote redeemed on this payout, when one was.
`quotation`	object	The quote this payout settled at. Only when a `quote_id` was redeemed.

from_amount and to_amount are strings — "1000.00", not 1000.00. Parse them as decimals rather than floats, and expect them to differ: the gap is the fees and the conversion.

Tracing it with the rail

Which of these arrive depends on the rail, and each is null until the rail hands it back.

Field	Type	Description
`txn_hash`	string or `null`	The on-chain transaction that settled it. `null` on a bank payout.
`uetr`	string or `null`	The wire’s end-to-end reference, when the rail assigns one.
`reference_number`	string or `null`	The rail’s own reference for the transfer. Falls back to `uetr` when there is no other.
`provider_reference`	string or `null`	The bank’s own id for the transfer, for when you have to ask them about it.

What you attached

Field	Type	Description
`reference`	string or `null`	The reference you set.
`memo`	string or `null`	The memo you set.
`extra_info`	object or `null`	The notes you sent on the payout, echoed back.

Who was on each end

Field	Type	Description
`sender`	object	Who sent it.
`recipient`	object	Who received it.

Both carry a name joined from the names on record — null on a party with no personal name on file, as the example above shows — a company_name, the country on the address as an ISO 3166-1 code, the bank_name, and a bank_account the bank has already masked.

What happened

Field	Type	Description
`events`	array	One entry per state the payout reached, oldest first.

Each entry carries an event_id, the status it moved to, a created_at, and a message when there is anything to add — absent otherwise. The statuses are the same set status takes.

Across the API

Authentication

Versioning

Users

Virtual Accounts

Recipients

Quotations

Payouts

Catalogs

RFIs

The payout object

Example

What the payout is

The money

Tracing it with the rail

What you attached

Who was on each end

What happened

​Example

​What the payout is

​The money

​Tracing it with the rail

​What you attached

​Who was on each end

​What happened

Example

What the payout is

The money

Tracing it with the rail

What you attached

Who was on each end

What happened