Create Payout

POST 
/v1/payout

Tag: api-payments-gateway-post-payoutDescription: Create a new payout.

Request

Header Parameters

x-include-replay-protection-schema string

The replay-protection-schema allows the user to choose between 3 options:

• If there's no value: The default protection checks that the values in this request are equal: { method, params, path, query, body, userId }. This means that if a request repeats the same values, it will be blocked.
• 'nonce': The nonce and { method, params, path, query, body, userId } value are checked. When the protection schema is this, requests will be OK if this nonce value is different in each request.
• 'x-transaction-uuid': The transactionId and { method, params, path, query, body, userId } value are checked. Requests will be OK if this x-transaction-uuid value is different in each request.
• 'x-transaction-uuid&nonce' or 'nonce&x-transaction-uuid': The nonce, transactionId value and { method, params, path, query, body, userId } are checked, i.e. if requests are repeated the same value in both fields, they will be blocked. But if any field has a different value, the request is OK.

x-wallet-uuid string

Sender Wallet UUID (if empty, your default Wallet UUID will be settled)

x-transaction-uuid stringrequired

The transaction ID is a UUID (v7) used to uniquely identify the object that will be created. All objects must have an identifier.

nonce stringrequired

The nonce ID is a UUID (v4) used to uniquely identify the request. All requests must have an identifier.

x-lang string

Possible values: [pt-BR, en-US]

Indicates the preferred language. Defaults to Brazilian Portuguese if unspecified.

x-product-uuid string

The product ID is a UUID (v4) used to identify the Z.ro product configuration.

x-product-target-user-uuid string

The product target user ID is a UUID (v4) used to identify what user account this request must be executed. Require: x-product-uuid.

application/json

Body

required

Payout creation request body. Choose one of the available payout method bodies.

oneOf
V1CreatePayoutBody
country stringrequired
Possible values: [CHL, ARG, PER]
Country ISO 3166-1-alpha-3 code for the payment.
payment_method stringrequired
Possible values: [BANK_TRANSFER]
Payment method used in the transaction.
amount_total numberrequired
Payment amount in cents. Min value is 1000 cents.
currency_tag stringrequired
Possible values: [CLP, ARS, PEN]
Payment currency ISO 4217 code
third_part_name stringrequired
Third Part first name.
third_part_last_name stringrequired
Third Part last name.
third_part_email stringrequired
Third Part email address.
third_part_phone stringrequired
Third Part phone number.
third_part_document stringrequired
Third Part document.
third_part_document_type stringrequired
Possible values: [DNI, RUT, PAS, CE, RUC, CUIL, CUIT]
Third Part document type.
third_part_address_zip_code stringrequired
User Address Zip Code.
third_part_address_street stringrequired
User Address Street.
third_part_address_number stringrequired
User Address number.
third_part_address_city stringrequired
User Address City.
third_part_address_state stringrequired
User Address state.
third_part_address_country stringrequired
User Address Country.
third_part_address_complement string
User Address Complement.
third_part_bank_code string
Bank identifier code (bank_code). To retrieve the valid value, call the endpoint GET /v1/payout/banks/:country. If the "code" field in the response is null, this field must also remain null.
third_part_account_type stringrequired
Possible values: [SA, CA, CP]
Account Type. Mapping: SA = Savings Account, CA = Checking Account, CP = Cell Phone / Mobile Wallet.
third_part_account_number stringrequired
Account Number.
V1CreateBankTransferPaymentBody
country stringrequired
Possible values: [CHL, PER, ARG]
Country ISO 3166-1-alpha-3 code for the payment.
payment_method stringrequired
Possible values: [BANK_TRANSFER]
Payment method used in the transaction.
amount_total numberrequired
Payment amount in cents. Min value is 100 cents.
currency_tag numberrequired
Possible values: [CLP, PEN, ARS]
Payment currency ISO 4217 code
third_part_name stringrequired
Third Part first name.
third_part_last_name stringrequired
Third Part last name.
third_part_email stringrequired
Third Part email address.
third_part_phone stringrequired
Third Part phone number.
third_part_document stringrequired
Third Part document.
third_part_document_type stringrequired
Possible values: [DNI, RUT, PAS, CE, RUC, CUIL, CUIT]
Third Part document type.
third_part_address_zip_code stringrequired
User Address Zip Code.
third_part_address_street stringrequired
User Address Street.
third_part_address_number stringrequired
User Address number.
third_part_address_city stringrequired
User Address City.
third_part_address_state stringrequired
User Address state.
third_part_address_country stringrequired
User Address Country.
third_part_address_complement string
User Address Complement.
third_part_bank_code string
Bank identifier code (bank_code). To retrieve the valid value, call the endpoint GET /v1/payout/banks/:country. If the "code" field in the response is null, this field must also remain null.
third_part_account_type stringrequired
Possible values: [SA, CA, CP]
Account Type. Mapping: SA = Savings Account, CA = Checking Account, CP = Cell Phone / Mobile Wallet.
third_part_account_number stringrequired
  Account Number rules by banks in Peru:

  - **BBVA Bank (001):** 18 or 20 digits  
    Ex: 001106660100012345 (18) |  (20)  

  - **Bank of Credit (002):**  
    • 14 digits for Savings Account  

  - **Interbank (003):** 13 digits  

  - **Scotiabank (004):** 10 digits (3 agency + 7 account)  
    Ex: 0037651234  

  - **Other banks:** 20-digit CCI (Ex: 00219400254640654321)  

Responses

200

Payout created successfully.

application/json

Schema

Schema

id stringrequired

Payout ID.

status stringrequired

Payout status.

created_at date-timerequired

Payout creation date.

updated_at date-timerequired

Payout update date.

Example (from schema)

{
  "id": "0197b169-da6b-7ba2-b053-ce413ae39afd",
  "status": "PENDING",
  "created_at": "2025-10-22T15:30:01.719Z",
  "updated_at": "2025-10-22T15:30:01.719Z"
}

400

If any required params are missing or has invalid format or type.

401

User authentication failed.

422

If any required params are missing or has invalid format or type.

Loading...