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

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# El objeto payout

> Describe los atributos del objeto payout, incluidos el beneficiario, el método de retiro y las transacciones

Este objeto representa el payout creado después de generar una transacción para transferir fondos desde tu cuenta a otra cuenta o destinatario.

**id** `string`

El identificador único del payout (MAX 64 ; MIN 36).

Ejemplo: 5404911d-5df9-429e-8488-ad41abea1a4b

**account\_id** `string`

El identificador único de la cuenta (MAX 64 ; MIN 36).

Ejemplo: 2404911d-5df9-429e-8488-ad41abea1a4b

**status** `enum`

El estado del payout (MAX 255; MIN 3).

Ejemplo: SUCCEEDED

Valores posibles del enum: consulta la página [Estado del payout](https://docs.y.uno/es/reference/payouts/payout-workflow.md).

**merchant\_reference** `string`

El identificador único del pedido del cliente (MAX 255; MIN 3).

Ejemplo: 4234

**description** `string`

La descripción del payout (MAX 255; MIN 3).

Ejemplo: marketplace payment

**purpose** `enum`

Indica el propósito del payout.

Valores posibles del enum: consulta la [lista de propósitos](https://docs.y.uno/es/reference/purposes-list.md).

**country** `enum`

País donde se debe procesar la transacción (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**amount** `object`

Especifica el objeto de monto del payout, con el valor y la moneda.

**properties**

**value** `number`

El monto del payout (múltiplo de 0.0001).

Ejemplo: 10000

**currency** `enum`

La moneda utilizada para realizar el payout (MAX 3; MIN 3; [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**beneficiary** `object`

Especifica el objeto beneficiario con su identificación.

**properties**

**merchant\_beneficiary\_id** `string`

Identificador único del beneficiario definido por el comercio.

Ejemplo: AAAA01

**national\_entity** `enum`

Tipo de entidad nacional del beneficiario.

Valores posibles del enum: `INDIVIDUAL` o `ENTITY`

**first\_name** `string`

El nombre del beneficiario (MAX 80; MIN 1).

Ejemplo: John

**last\_name** `string`

El apellido del beneficiario (MAX 80; MIN 1).

Ejemplo: Doe

**legal\_name** `string`

El nombre del beneficiario (Max: 80). Solo es necesario cuando `national_entity` es `ENTITY` .

Ejemplo: Arcos dorados S.A.

**email** `string`

El email del beneficiario (MAX 255; MIN 3).

Ejemplo: [john.doe@email.com](mailto:john.doe@email.com)

**country** `enum`

El país del beneficiario (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**date\_of\_birth** `date`

La fecha de nacimiento del beneficiario en formato YYYY-MM-DD (MAX 10; MIN 10).

Ejemplo: 1990-02-28

**document** `object`

Especifica el objeto de documento del beneficiario, incluidos su número y tipo.

**properties**

**document\_number** `string`

El número de documento del beneficiario (MAX 40; MIN 3).

Ejemplo: 1093333333

**document\_type** `enum`

El tipo de documento del beneficiario (MAX 6, MIN 2).

Valores posibles del enum: consulta la [referencia de países.](https://docs.y.uno/es/reference/country-reference.md)

**phone** `object`

Especifica el objeto de número de teléfono del beneficiario.

**properties**

**country\_code** `string`

El código de llamada del país del teléfono del beneficiario (MAX 3; MIN 1). Valores posibles: consulta la [
referencia de países](https://docs.y.uno/es/reference/country-reference.md) .

Ejemplo: 57

**number** `string`

El número de teléfono del beneficiario, sin el código de llamada del país (MAX 32; MIN 1).

Ejemplo: 3132450765

**address** `object`

Especifica el objeto de dirección del beneficiario.

**properties**

**address\_line\_1** `string`

La línea de dirección principal del beneficiario (MAX 255; MIN 3).

Ejemplo: Calle 34 # 56 - 78

**address\_line\_2** `string`

La línea de dirección secundaria del beneficiario (MAX 255; MIN 3).

Ejemplo: Apartamento 502, Torre I

**city** `string`

La ciudad considerada para la dirección del beneficiario (MAX 255; MIN 3).

Ejemplo: Bogotá

**country** `enum`

El país de la dirección del beneficiario (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**state** `string`

El estado o la provincia de la dirección del beneficiario (MAX 255; MIN 3).

Ejemplo: Cundinamarca

**zip\_code** `string`

El código postal considerado para la dirección del beneficiario (MAX 11; MIN 4).

Ejemplo: 111111

**withdrawal\_method** `object`

Especifica el objeto withdrawal\_method del beneficiario.

**properties**

**type** `enum`

El tipo de withdrawal\_method.

Ejemplo: ASTROPAY\_WALLET

**provider\_id** `enum`

El proveedor con el que se procesa el payout.

Ejemplo: ASTROPAY

**vaulted\_token** `string`

El vaulted\_token representa un payment\_method almacenado de forma segura. Principalmente para tarjetas de crédito/débito en Payouts.

Ejemplo: 41032411-5df9-429e-1238-ad41abea1cf6

**original\_transaction\_id** `string`

ID de la transacción de pago referenciada. Solo para payouts a CARD. (MAX 64 ; MIN 36).

Ejemplo: 9104911d-5df9-429e-8488-ad41abea1a4b

**on\_hold** `bool`

Define si el comercio quiere retener el payout y programarlo para procesarse más tarde mediante el endpoint Release payout. False por defecto.

Ejemplo: false

**detail** `object`

Especifica los detalles de withdrawal\_method.

**properties**

**bank\_transfer** `object`

Especifica el objeto withdrawal\_method del beneficiario.

**properties**

**code** `string`

El código de la institución financiera del beneficiario (MAX 3; MIN 3).

Ejemplo: 246

**branch** `string`

La sucursal específica de la institución financiera del beneficiario (MAX 3; MIN 3).

Ejemplo: XXX

**branch\_digit** `string`

El dígito de la sucursal específica de la institución financiera del beneficiario (MAX 3; MIN 3).

Ejemplo: 123

**account** `object`

Especifica el objeto de cuenta bank\_transfer del beneficiario.

**properties**

**number** `string`

Número de cuenta de la institución financiera del beneficiario o alias de la cuenta, como la Clabe
para MX (MAX 255; MIN 3).

Ejemplo: 1093333333

**digit** `string`

Dígito de la cuenta de la institución financiera del beneficiario (MAX 3; MIN 1).

Ejemplo: 123

**type** `enum`

Tipo de cuenta del beneficiario (MAX 255; MIN 3).

Valores posibles del enum: `CHECKINGS`, `SAVINGS`, `VISTA`,
`PIX_EMAIL`, `PIX_PHONE`, `PIX_DOCUMENT_ID`,
`PIX_BANK_ACCOUNT`

**address** `object`

Especifica el objeto de dirección del beneficiario.

**properties**

**address\_line\_1** `string`

La línea de dirección principal del beneficiario (MAX 255; MIN 3).

Ejemplo: Calle 34 # 56 - 78

**address\_line\_2** `string`

La línea de dirección secundaria del beneficiario (MAX 255; MIN 3).

Ejemplo: Apartamento 502, Torre I

**city** `string`

La ciudad considerada para la dirección del beneficiario (MAX 255; MIN 3).

Ejemplo: Bogotá

**country** `enum`

El país de la dirección del beneficiario (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**state** `string`

El estado o la provincia de la dirección del beneficiario (MAX 255; MIN 3).

Ejemplo: Cundinamarca

**zip\_code** `string`

El código postal considerado para la dirección del beneficiario (MAX 11; MIN 4).

Ejemplo: 111111

**wallet** `object`

Especifica el objeto withdrawal\_method del beneficiario.

**properties**

**code** `string`

El código de wallet del beneficiario (MAX 3; MIN 3).

Ejemplo: 246

**email** `string`

El email específico de la wallet del beneficiario (MAX 3; MIN 3).

Ejemplo: [john.doe@gmail.com](mailto:john.doe@gmail.com)

**country** `enum`

El país de la wallet del beneficiario (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**document** `object`

Especifica el objeto de documento del beneficiario, incluidos su número y tipo.

**properties**

**document\_number** `string`

El número de documento del beneficiario (MAX 40; MIN 3).

Ejemplo: 1093333333

**document\_type** `enum`

El tipo de documento del beneficiario (MAX 6, MIN 2).

Valores posibles del enum: consulta la [referencia de países.](https://docs.y.uno/es/reference/country-reference.md)

**phone** `object`

Especifica el objeto de número de teléfono del beneficiario.

**properties**

**country\_code** `string`

El código de llamada del país del teléfono del beneficiario (MAX 3; MIN 1). Valores posibles: consulta la [
referencia de países](https://docs.y.uno/es/reference/country-reference.md) .

Ejemplo: 57

**number** `string`

El número de teléfono del beneficiario, sin el código de llamada del país (MAX 32; MIN 1).

Ejemplo: 3132450765

**transactions** `array of objects`

Especifica una lista de objetos payout.

**properties**

**id** `string`

El identificador único de la intención de payout (MAX 64 ; MIN 36).

Ejemplo: 9104911d-5df9-429e-8488-ad41abea1a4b

**type** `enum`

El tipo de intención de payout (MAX 255; MIN 3).

**status** `enum`

El estado de la intención de payout (MAX 255; MIN 3).

**response\_code** `enum`

El código de respuesta indica el estado de la solicitud de intención de payout (MAX 255; MIN 3).

**merchant\_reference** `string`

La identificación de la transacción de payout definida por el comercio (MAX 255; MIN 3).

Ejemplo: AAB01-432245

**amount** `object`

Especifica el objeto de monto del payout, con el valor y la moneda.

**properties**

**value** `number`

El monto del payout (múltiplo de 0.0001).

Ejemplo: 10000

**currency** `enum`

La moneda utilizada para realizar el payout (MAX 3; MIN 3; [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**purpose** `enum`

Especifica el propósito del payout.

**description** `string`

Descripción del payout (MAX 255; MIN 3).

Ejemplo: Salary

**provider\_data** `object`

Especifica el proveedor de datos.

**properties**

**id** `enum`

La identificación del proveedor de datos.

Valores posibles: `ADDI`, `MERCADO_PAGO`, `SPINPAY`,
`WOMPI`

**transaction\_id** `string`

El identificador único del pago en el proveedor.

Ejemplo: 12345678

**account\_id** `string`

El ID de la cuenta del comercio en el proveedor de pago.

Ejemplo: 9990128

**status** `string`

El estado de la transacción en el proveedor (MAX 255; MIN 3).

Ejemplo: accredited

**status\_detail** `string`

El estado detallado de la transacción según el proveedor de datos (MAX 255; MIN 3).

Ejemplo: approved

**raw\_response** `string`

La respuesta sin procesar del proveedor de datos. El formato depende de la respuesta del proveedor.

La respuesta varía según cada proveedor de datos.

**created\_at** `timestamp`

Fecha de creación de la transacción (MAX 27; MIN 27, [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) ).

Ejemplo: 2022-05-09T20:46:54.786342Z

**updated\_at** `timestamp`

Fecha de la última actualización de la transacción (MAX 27; MIN 27, [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) ).

Ejemplo: 2022-05-09T20:46:54.786342Z

**metadata** `array of objects`

Especifica una lista de pares clave-valor personalizados asociados al payout (para referencias internas, conciliación o etiquetas de flujo de trabajo). Puedes agregar hasta 50 objetos de metadata.

**properties**

**metadata object** `object`

Especifica una clave de metadatos y su valor correspondiente.

Úsalo para adjuntar contexto definido por el comercio (por ejemplo: `batch_id`, `payout_reason`). Evita enviar datos sensibles o personales.

**properties**

**key** `string`

La clave de metadata (MAX 48 ; MIN 1).

Ejemplo: order\_id

**value** `string`

El valor de la clave de metadata (MAX 512 ; MIN 1).

Ejemplo: AA001

**created\_at** `timestamp`

Fecha de creación de la transacción (MAX 27; MIN 27, [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) ).

Ejemplo: 2022-05-09T20:46:54.786342Z

**updated\_at** `timestamp`

Fecha de la última actualización de la transacción (MAX 27; MIN 27, [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) ).

Ejemplo: 2022-05-09T20:46:54.786342Z


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.