The Payout Object

Represents a disbursement of funds from a merchant to a recipient.

The Payout object represents a disbursement of funds from a merchant’s account to a recipient, such as a seller, freelancer, or partner. Payouts are used for marketplace disbursements, refund alternatives, and any merchant-to-individual fund transfers.

Recipients required. Before creating a payout, you must register the recipient via the Recipients API. The recipient record holds banking details and identity information needed to route the funds.

Object Fields

id · string

The unique identifier of the payout (UUID).

Example: po_3f4a5b6c-7d8e-9f01-2345-6789abcdef01

status · string

Current payout status. Transitions depend on provider processing times and fund availability.

Values: PENDING, PROCESSING, SUCCEEDED, FAILED, CANCELLED

• PENDING. Payout created but not yet submitted to the provider.
• PROCESSING. Submitted to the provider; awaiting confirmation.
• SUCCEEDED. Funds successfully disbursed to the recipient.
• FAILED. Provider rejected the payout (invalid account, insufficient funds, etc.).
• CANCELLED. Cancelled by the merchant before processing began.

Example: SUCCEEDED

amount · object

The payout amount details.

Show amount

value · number

The disbursement amount.

Example: 250.00

currency · string

ISO 4217 currency code.

Example: USD

country · string

The country where the payout is executed. ISO 3166-1 alpha-2 code. Determines which providers and banking rails are available.

Example: US

recipient_id · string

ID of the recipient receiving the funds. Links to the Recipient Object.

Example: rcp_a1b2c3d4-e5f6-7890-abcd-ef1234567890

merchant_reference · string

The merchant’s own reference identifier for this payout, used for reconciliation between your system and Yuno. Must be unique per merchant account.

Example: payout-seller-20260310-001

provider · object

Information about the provider that processed the payout.

Show provider

name · string

Provider name that handled the disbursement.

Example: MERCADOPAGO

transaction_id · string

The provider’s own transaction reference for tracking on their platform.

Example: mp_txn_9876543210

description · string

A human-readable description of the payout purpose (MAX 255).

Example: Marketplace seller payout - March 2026

created_at · string

ISO 8601 timestamp of when the payout was created.

Example: 2026-03-10T16:00:00.000Z

updated_at · string

ISO 8601 timestamp of the last payout update.

Example: 2026-03-10T16:05:30.000Z

Example

{
  "id": "po_3f4a5b6c-7d8e-9f01-2345-6789abcdef01",
  "status": "SUCCEEDED",
  "amount": {
    "value": 250.00,
    "currency": "USD"
  },
  "country": "US",
  "recipient_id": "rcp_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchant_reference": "payout-seller-20260310-001",
  "provider": {
    "name": "MERCADOPAGO",
    "transaction_id": "mp_txn_9876543210"
  },
  "description": "Marketplace seller payout - March 2026",
  "created_at": "2026-03-10T16:00:00.000Z",
  "updated_at": "2026-03-10T16:05:30.000Z"
}

Related Endpoints

• Create Payout. POST /v1/payouts
• Get Payout. GET /v1/payouts/{payout_id}
• Get Payout by Merchant Reference. GET /v1/payouts?merchant_reference={reference}

Related Concepts

• Payouts. How disbursements work in Yuno