> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```json theme={null}
{
  "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](/reference/payouts/values#payout-origin)                                  |
| `status`         | string            | Where the payout has got to. [Values](/reference/payouts/values#payout-status)                      |
| `payment_method` | string or `null`  | Which rail it went out on, in lower case. [Values](/reference/payouts/values#payout-payment_method) |
| `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](/reference/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. |

<Note>
  `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.
</Note>

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