The Payout Object

This object represents the payout created after generating a transaction to transfer funds from your account to another account or recipient.

id string
The unique identifier of the payout (MAX 64 ; MIN 36).
Example: 5404911d-5df9-429e-8488-ad41abea1a4b

account_id string
The unique identifier of the account (MAX 64 ; MIN 36).
Example: 2404911d-5df9-429e-8488-ad41abea1a4b

status enum
The status of the Payout (MAX 255; MIN 3).
Example: RECEIVED

merchant_reference string
The unique identifier of the customer's order (MAX 255; MIN 3).
Example: 4234

description string
The description of the payout (MAX 255; MIN 3).
Example: marketplace payment

purpose enum
Indicates the purpose for the payout.
Possible enum values: Check the Purpose list.

country enum
Country where the transaction must be processed (MAX 2; MIN 2; ISO 3166-1).
Possible enum values: Check the Country reference.

amount object

Specifies the payout amount object, with the value and currency.

value number
The payout amount (multiple of 0.0001).
Example: 10000

currency enum
The currency used to make the payout (MAX 3; MIN 3; ISO 4217).
Possible enum values: Check the Country reference.

beneficiary object

Specifies the beneficiary object with their identification.

external_id string
Unique identifier of the beneficiary defined by the merchant.
Example: AAAA01

national_entity enum
Beneficiary's national entity type.
Possible enum values: INDIVIDUAL or ENTITY

first_name string
The beneficiary's first name (MAX 80; MIN 1).
Example: John

last_name string
The beneficiary's last name (MAX 80; MIN 1).
Example: Doe

legal_name string
The beneficiary's name (Max: 80). Only necessary when national_entity is ENTITY.
Example: Arcos dorados S.A.

email string
The beneficiary's email (MAX 255; MIN 3).
Example: [email protected]

country enum
The beneficiary's country (MAX 2; MIN 2; ISO 3166-1).
Possible enum values: Check the Country reference.

date_of_birth date
The beneficiary's date of birth in the YYYY-MM-DD format (MAX 10; MIN 10).
Example: 1990-02-28

document object

Specifies the beneficiary's document object, including its number and type.

document_number string
The beneficiary's document number (MAX 40; MIN 3).
Example: 1093333333

document_type enum
The beneficiary's document type (MAX 6, MIN 2).
Possible enum values: Check the Country reference.

phone object

Specifies the beneficiary's phone number object.

country_code string
The country calling code of the beneficiary's phone (MAX 3; MIN 1). Possible values: Check the Country reference.
Example: 57

number string
The beneficiary's phone number, without the country calling code (MAX 32; MIN 1).
Example: 3132450765

address object

Specifies the beneficiary's address object.

address_line_1 string
The beneficiary's primary address line (MAX 255; MIN 3).
Example: Calle 34 # 56 - 78

address_line_2 string
The beneficiary's secondary address line (MAX 255; MIN 3).
Example: Apartamento 502, Torre I

city string
The city considered for the beneficiary address (MAX 255; MIN 3).
Example: Bogotá

country enum
The country of the beneficiary address (MAX 2; MIN 2; ISO 3166-1).
Possible enum values: Check the Country reference.

state string
The beneficiary's state or province address (MAX 255; MIN 3).
Example: Cundinamarca

zip_code string
The zipcode considered for the beneficiary address (MAX 11; MIN 4).
Example: 111111

financial_institution object

Specifies the beneficiary's financial institution object.

code string
The beneficiary's financial institution code (MAX 3; MIN 3).
Example: 246

branch string
The beneficiary's specific financial institution branch (MAX 3; MIN 3).
Example: XXX

branch_digit string
The beneficiary's specific financial institution branch digit (MAX 3; MIN 3).
Example: 123

account string
Beneficiary's financial institution account number or financial institution account alias, such as Clabe for MX (MAX 255; MIN 3).
Example: 1093333333

account_digit string
Beneficiary's financial institution account digit (MAX 3; MIN 1).
Example: 123

account_type enum
Beneficiary's account type (MAX 255; MIN 3).
Possible enum values: CHECKINGS, SAVINGS, VISTA, PIX_EMAIL, PIX_PHONE, PIX_DOCUMENT_ID, PIX_BANK_ACCOUNT

transactions array of objects

Specifies a list of payouts objects.

id string
The unique identifier for the payout intent (MAX 64 ; MIN 36).
Example: 9104911d-5df9-429e-8488-ad41abea1a4b

type enum
The payout intent type (MAX 255; MIN 3).

status enum
The payout intent status (MAX 255; MIN 3).

response_code enum
The response code indicates the status of the payout intent request (MAX 255; MIN 3).

merchant_reference string
The payout transaction identification defined by the merchant (MAX 255; MIN 3).
Example: AAB01-432245

amount number
Specifies the payout amount (multiple of 0.0001).
Example: 40.5

reason enum
Specifies the refund reason that originated the payout.
Possible values: DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER, NULL.

description string
Describes the refund and its reason (MAX 255; MIN 3).
Example: Product Received in Poor Condition

provider_data object

Specifies the data provider.

id enum
The data provider identification.
Possible values: ADDI, MERCADO_PAGO, SPINPAY, WOMPI

transaction_id string
The unique identifier of the payment from the provider.
Example: 12345678

account_id string
The merchant's payment provider account id.
Example: 9990128

status string
Provider's status of the transaction (MAX 255; MIN 3).
Example: accredited

status_detail string
The data provider's detailed status of the transaction (MAX 255; MIN 3).
Example: approved

raw_response string
The data provider raw response. The format depends on the provider's response.
The response will vary for each data provider.

created_at timestamp
Transactions creation date (MAX 27; MIN 27, ISO 8601).
Example: 2022-05-09T20:46:54.786342Z

updated_at timestamp
The last transactions update date (MAX 27; MIN 27, ISO 8601).
Example: 2022-05-09T20:46:54.786342Z

metadata array of objects

Specifies a list of metadata objects. You can add up to 50 metadata objects.

metadata object object

Specifies a metadata key and the respective value.

key string
The metadata key (MAX 48 ; MIN 1).
Example: order_id

value string
The metadata key value (MAX 512 ; MIN 1).
Example: AA001

created_at timestamp
Transactions creation date (MAX 27; MIN 27, ISO 8601).
Example: 2022-05-09T20:46:54.786342Z

updated_at timestamp
The last transactions update date (MAX 27; MIN 27, ISO 8601).
Example: 2022-05-09T20:46:54.786342Z