API reference

Payouts

A payout sends funds from a merchant wallet to a saved address: kind: "payout" to someone else, kind: "withdrawal" to one of the merchant's own addresses. Like a refund, a payout can only be requested by the API and is approved in the dashboard with a passkey (Money out).

The destination must be a saved address with status: "active" (approved and past its 24-hour wait).
If destination is on another network or in another asset than source, the payout is delivered through Relay (delivery.rail: "relay"): one send from the merchant's wallet to a Relay deposit address, Relay's fee taken from the amount moved, so the merchant needs fee money only on the network it sends from.
Network fee: on Bitcoin, Litecoin and Dogecoin it comes out of the amount. On the EVM networks, Solana and TRON the merchant's fee account pays; if it is too low the request fails with fee_account_low, which says exactly how much of which coin is missing.
A wallet that has never sent (status: "address_ready") is deployed as part of the first approved payout; the same approval covers both.
Tier limits: Unverified, US$1,000 a day to others, single payouts only; Verified, US$100,000 a day and batches of up to 200 rows. A tier never limits a withdrawal to the merchant's own saved address.
The amount is reserved (balance.reserved) from request until the payout is confirmed, failed or cancelled. unknown keeps the reserve until evidence settles it (no timer ends it); never re-request a payout that is unknown.
A request nobody approves within 7 days lapses back to draft with pending_reason: "approval_lapsed" and its reserve is released. Send it for approval again with POST /v1/payouts/{id}/submit, or cancel it.

The `payout` object

JSON

{
  "id": "po_351ggq5kz6kxwpfrhp5qh3b0",
  "object": "payout",
  "livemode": true,
  "created": "2026-10-12T09:30:00.000Z",
  "updated": "2026-10-12T09:30:00.000Z",
  "kind": "payout",
  "status": "awaiting_approval",
  "pending_reason": null,
  "batch": null,
  "source": {
    "wallet": "wal_bsfw07hymawmda7gg8jsyy3g",
    "asset": "base:usdc",
    "amount": "250.000000"
  },
  "destination": {
    "saved_address": "dst_92jw0br3z1bzkk45ddjqcm6q",
    "address": "0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb",
    "network": "base",
    "asset": "base:usdc"
  },
  "delivery": {
    "rail": "direct",
    "amount_estimated": "250.000000",
    "route_fee": null,
    "fee_bearer": null
  },
  "value": {
    "amount": "250.00",
    "currency": "USD"
  },
  "description": "October green beans",
  "reference": "PO-2210",
  "network_fee": null,
  "requested_by": {
    "type": "api_key",
    "id": "key_6e3gg2c6ea176xxdek2nar6v"
  },
  "approved_by": null,
  "approval_url": "https://merchant.orrerie.com/approve/po_351ggq5kz6kxwpfrhp5qh3b0",
  "approval_expires_at": "2026-10-19T09:30:00.000Z",
  "transaction_hash": null,
  "failure_code": null,
  "cancellation_reason": null,
  "approved_at": null,
  "sent_at": null,
  "confirmed_at": null,
  "metadata": {
    "supplier_id": "s_19"
  }
}

Table: The payout object
Field	Meaning
`pending_reason`	For a draft: approval_lapsed. Otherwise `null`.
`kind`	payout: to someone else. withdrawal: to one of the merchant's own saved addresses. Values: `payout`, `withdrawal`.
`approval_url`	Dashboard page where an Owner or Finance member approves with a passkey. The API can never approve.
`status`	One of `draft`, `awaiting_approval`, `signed`, `sent`, `confirmed`, `failed`, `unknown`, `cancelled`.

The `payout_batch` object

JSON

{
  "id": "pob_b1xkj45rqwdaf7j2bc94pef3",
  "object": "payout_batch",
  "livemode": true,
  "created": "2026-10-12T09:40:00.000Z",
  "status": "awaiting_approval",
  "description": "October contractor payments",
  "row_count": 2,
  "total_value": {
    "amount": "1700.00",
    "currency": "USD"
  },
  "counts": {
    "draft": 0,
    "awaiting_approval": 2,
    "signed": 0,
    "sent": 0,
    "confirmed": 0,
    "failed": 0,
    "unknown": 0,
    "cancelled": 0
  },
  "payouts": [
    "po_crs9tp390f2yjremph9m0npb",
    "po_kyrcy0h8t43wvedbxe5v40bp"
  ],
  "requested_by": {
    "type": "api_key",
    "id": "key_6e3gg2c6ea176xxdek2nar6v"
  },
  "approved_by": null,
  "approval_url": "https://merchant.orrerie.com/approve/pob_b1xkj45rqwdaf7j2bc94pef3",
  "approval_expires_at": "2026-10-19T09:40:00.000Z",
  "approved_at": null,
  "completed_at": null,
  "cancellation_reason": null,
  "metadata": {}
}

Table: The payout_batch object
Field	Meaning
`status`	One of `draft`, `awaiting_approval`, `processing`, `completed`, `completed_with_failures`, `needs_attention`, `cancelled`.

Every field

Fields of the `payout` object

Fields of the payout object
Field	Type	Meaning
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`updated`	string (date-time)	When the object last changed.
`kind`	string	`payout`: to someone else. `withdrawal`: to one of the merchant's own saved addresses. `split_leg`: a share of a paid order under a split rule (the API referencea). One of `payout`, `withdrawal`, `split_leg`.
`status`	string	One of `draft`, `awaiting_approval`, `signed`, `sent`, `confirmed`, `failed`, `unknown`, `cancelled`.
`pending_reason`	string or null	For a draft: approval_lapsed. Otherwise `null`.
`batch`	object	The `pob_` id of the batch the payout belongs to, or the batch object when expanded; `null` for a single payout.
`split_rule`	string or null	The split rule a split_leg pays a share for; `null` for any other payout.
`order`	string or null	The paid order a split_leg shares; `null` for any other payout.
`source`	object	The merchant wallet the money leaves from.
`source.wallet`	string	The `wal_` id of that wallet.
`source.asset`	string	The asset that leaves it.
`source.amount`	string	What leaves it, in the asset's own units.
`destination`	object	Where the money goes: always a saved address.
`destination.saved_address`	object	The `dst_` id of the saved address, or the object when expanded.
`destination.address`	string	The address the money is sent to.
`destination.network`	string	The network of the address.
`destination.asset`	string	The asset the destination receives.
`delivery`	object	How the money reaches the destination.
`delivery.rail`	string	`direct`: one send to the address. `relay`: through Relay, into another asset or network.
`delivery.amount_estimated`	string	About what the destination receives, in the destination asset.
`delivery.route_fee`	object or null	Relay's fee for the delivery, in US dollars; `null` on the direct rail.
`delivery.fee_bearer`	string or null	Who pays the routing fee: `recipient` (taken from the amount) or `merchant`; `null` on the direct rail.
`value`	object	The payout's value in US dollars when it was requested.
`value.amount`	string	The value, a decimal string.
`value.currency`	string	Always `USD`.
`description`	string or null	The merchant's description of the payout; `null` for none.
`reference`	string or null	The merchant's own reference, for example an invoice number; `null` for none.
`network_fee`	object or null	The network fee of the send and who pays it; `null` until it is known.
`requested_by`	object	Who asked for it: an API key or a dashboard member.
`requested_by.type`	string	`api_key` or `member`.
`requested_by.id`	string	The id of the key (`key_…`) or the member (`mem_…`) that asked.
`approved_by`	string or null	The member who approved it with a passkey; `null` until approved.
`approval_url`	string or null	Dashboard page where an Owner or Finance member approves with a passkey. The API can never approve.
`approval_expires_at`	string (date-time)	When an unapproved request lapses to `draft`.
`transaction_hash`	string or null	The hash of the transaction that sent it; `null` until it is sent.
`failure_code`	string or null	Why it failed (Money out lists the codes); `null` unless `status` is `failed` or `unknown`.
`cancellation_reason`	string or null	Why it was cancelled (for example `cancelled_by_api` or `rejected_by_approver`); `null` unless cancelled.
`approved_at`	string or null	When it was approved; `null` until then.
`sent_at`	string or null	When the transaction was broadcast; `null` until then.
`confirmed_at`	string or null	When the network's confirmation count was reached; `null` until then.
`metadata`	object	Up to 50 keys of your own data. Key up to 40 characters, value a string up to 500 characters. Never used by Orrerie; never put secrets or personal data here.

Fields of the `payout_batch` object

Fields of the payout_batch object
Field	Type	Meaning
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`status`	string	One of `draft`, `awaiting_approval`, `processing`, `completed`, `completed_with_failures`, `needs_attention`, `cancelled`.
`description`	string or null	The merchant's description of the batch; `null` for none.
`row_count`	integer	How many payouts the batch holds.
`total_value`	object	The batch's total value in US dollars when it was requested.
`total_value.amount`	string	The total, a decimal string.
`total_value.currency`	string	Always `USD`.
`counts`	object	How many of the batch's payouts are in each state.
`counts.draft`	integer	Payouts in `draft`.
`counts.awaiting_approval`	integer	Payouts waiting for approval.
`counts.signed`	integer	Payouts signed and not yet sent.
`counts.sent`	integer	Payouts sent and not yet confirmed.
`counts.confirmed`	integer	Payouts confirmed.
`counts.failed`	integer	Payouts that failed.
`counts.unknown`	integer	Payouts whose outcome is not known yet.
`counts.cancelled`	integer	Payouts cancelled.
`payouts`	array of strings	The `po_` ids of the batch's payouts, in row order.
`requested_by`	object	Who asked for it: an API key or a dashboard member.
`requested_by.type`	string	`api_key` or `member`.
`requested_by.id`	string	The id of the key (`key_…`) or the member (`mem_…`) that asked.
`approved_by`	string or null	The member who approved the batch with a passkey; `null` until approved.
`approval_url`	string or null	The dashboard page where the batch is approved with one passkey; `null` once it is approved, cancelled or lapsed.
`approval_expires_at`	string (date-time)	When an unapproved batch lapses to `draft`.
`approved_at`	string or null	When the batch was approved; `null` until then.
`completed_at`	string or null	When every payout of the batch ended; `null` until then.
`cancellation_reason`	string or null	Why the batch was cancelled; `null` unless it was.
`metadata`	object	Up to 50 keys of your own data. Key up to 40 characters, value a string up to 500 characters. Never used by Orrerie; never put secrets or personal data here.

Endpoints

Events

Webhook events whose data.object is an object of this page.

Payouts

The payout object

The payout_batch object