---
title: "Create Payout"
method: POST
path: "/payouts"
---

# Create Payout

`POST /payouts`

## Request body

- object
  - `account_id` string, required — The unique identifier of the account. You find this information on [the Yuno dashboard](https://dashboard.y.uno/) (UUID, 36 chars.).
  - `merchant_reference` string, required — The unique identifier of the merchant's payout (MAX 255; MIN 3).
  - `description` string — The description of the payout (MAX 255; MIN 3).
  - `country` 'AR' | 'BO' | 'BR' | 'CL' | 'CO' | 'CR' | 'EC' | 'SV' | 'GT' | 'HN' | 'MX' | 'NI' | 'PA' | 'PY' | 'PE' | 'US' | 'UY', required — Country where the transaction must be processed (MAX 2; MIN 2; [ISO 3166-1](country-reference)).
  - `purpose` 'FAMILY_AND_FRIENDS' | 'PERSONAL_TRANSFER' | 'REMITTANCES' | 'PROVIDER_SERVICES' | 'ADVERTISING_SERVICES' | 'REPRESENTATION_SERVICES' | 'ADVISORY_SERVICES' | 'FREELANCER_SERVICES' | 'SUPPLIER' | 'BUSINESS_TO_BUSINESS' | 'MARKETPLACE' | 'PAYROLL' | 'GIFTS_AND_BENEFITS' | 'EXPENSES' | 'CORPORATE_PAYMENT' | 'PURCHASE_OF _PHYSICAL_GOODS' | 'PURCHASE_OF _DIGITAL_GOODS' | 'PURCHASE_OF_SERVICES' | 'INVESTMENTS' | 'CAPITAL_CONTRIBUTION' | 'INVESTMENTS_SHARES' | 'TAXES' | 'LOGISTICS_AND_TRANSPORTATION' | 'DELIVERY' | 'AFFILIATION_PROGRAM' | 'LOANS' | 'REAL_STATE' | 'RENT' | 'TRAVEL_FLIGHTS' | 'TRAVEL_ACCOMMODATIONS' | 'EDUCATION' | 'TUITION_COSTS' | 'TRAININGS' | 'CHARITY' | 'MEDICAL_SERVICES' | 'SAVINGS' | 'RETIREMENT' | 'PENSION' | 'INSURANCE' | 'REWARDS' | 'TRADEMARKS_AND_COPYRIGHT' | 'ENTERTAINMENT' | 'GOVERNMENT' | 'OTHERS', required — Indicates the purpose for the payout. Possible enum values: Check the <a href='https://docs.y.uno/reference/the-payout-object#purposes-list'>Purpose list</a>.
  - `amount` object, required — Specifies the payout amount object, with the value and currency.
    - `value` number, required — The payout amount (multiple of 0.0001).
    - `currency` string, required — The currency used to make the payout. For a full list of currency codes, see [Country reference](/reference/country-reference) (MAX 3; MIN 3; ISO 4217).
  - `beneficiary` object, required — Specifies the beneficiary object with their identification.
    - `merchant_beneficiary_id` string, required — Unique identifier of the recipient defined by the merchant (MAX 255; MIN 1).
    - `national_entity` 'INDIVIDUAL' | 'ENTITY' — Beneficiary's national entity type. Individual by default
    - `first_name` string — Beneficiary's name (MAX 80).
    - `last_name` string — Beneficiary's last name (MAX 80).
    - `legal_name` string — Beneficiary's name (MAX 80). Only necessary when national entity is ENTITY.
    - `email` string — The beneficiary's email (MAX 255; MIN 3).
    - `country` 'AR' | 'BO' | 'BR' | 'CL' | 'CO' | 'CR' | 'EC' | 'SV' | 'GT' | 'HN' | 'MX' | 'NI' | 'PA' | 'PY' | 'PE' | 'US' | 'UY', required — The beneficiary's country (MAX 2; MIN 2; [ISO 3166-1](country-reference)).
    - `date_of_birth` string — The beneficiary's date of birth in the YYYY-MM-DD format (MAX 10; MIN 10).
    - `document` object — Beneficiary's national document
      - `document_number` string, required — The document number (MAX 40; MIN 3).
      - `document_type` 'DNI' | 'CI' | 'LC' | 'LE' | 'CUIT' | 'CUIL' | 'PAS' | 'CPF' | 'RG' | 'CNH' | 'CNPJ' | 'RUT' | 'RUN' | 'CC' | 'CE' | 'NIT' | 'DUI' | 'PIC' | 'DPI' | 'IFR' | 'INE' | 'CP' | 'RFC' | 'CURP' | 'CIP' | 'CIC' | 'CUI' | 'RUC' — Document type (MAX 6, MIN 1; [Country reference](country-reference)).
    - `phone` object — Beneficiary's cell phone
      - `country_code` string — The country calling code of the phone (MAX 3; MIN 1). Check the [Country reference](country-reference) to see the phone codes.
      - `number` string — The phone number, without the country code (MAX 32; MIN 1).
    - `address` object — Beneficiary's address
      - `address_line_1` string — The primary address line (MAX 255; MIN 3).
      - `address_line_2` string — The secondary address line (MAX 255; MIN 1).
      - `city` string — The city considered for the address (MAX 255; MIN 3).
      - `country` 'AR' | 'BO' | 'BR' | 'CL' | 'CO' | 'CR' | 'EC' | 'SV' | 'GT' | 'HN' | 'MX' | 'NI' | 'PA' | 'PY' | 'PE' | 'US' | 'UY' — The country (MAX 2; MIN 2; [ISO 3166-1](country-reference)).
      - `state` string — The state/province from the address (MAX 255; MIN 3).
      - `zip_code` string — The zipcode for the address (MAX 11; MIN 4).
  - `withdrawal_method` object, required — The withdrawal method to make the payout.
    - `type` 'ASTROPAY_PAYOUT' | 'CARD' | 'NEQUI_PAYOUT' | 'PAYPAL_PAYOUT' | 'PIX_PAYOUT' | 'AFIRME_PAYOUT' | 'ECOMMPAY_PAYOUT' | 'QI_PAYOUT' | 'STP_PAYOUT' | 'TRANSFIYA_PAYOUT' | 'UNLIMINT_PAYOUT', required — Withdrawal method type.
    - `provider_id` 'ASTROPAY' | 'NEQUI' | 'PAYPAL' | 'UNLIMINT', required — The provider to process the payouts with
    - `vaulted_token` string — The vaulted token for a previously stored payment_method. If a payment is created using a vaulted_token (MAX: 64; MIN: 36).
    - `original_transaction_id` string — Id of the referenced payment transaction. Only for payouts to CARD. (MAX 64; MIN 36)
    - `original_payment_id` string — The id of the referenced payment (UUID; 36 chars.).
    - `on_hold` boolean — Defines if the merchant wants to hold the payout and sets it to be processed later using the Release payout endpoint.
    - `detail` object — Withdrawal method details. Only the object corresponding to the withdrawal method type is necessary.
      - `bank_transfer` object — Bank transfer details to make the payout.
        - `code` string, required — The beneficiary's specific financial institution code (MAX 8).
        - `branch` string — The beneficiary's specific financial institution branch (MAX 8).
        - `branch_digit` string — The beneficiary's specific financial institution branch digit (MAX 2).
        - `account` object — Beneficiary's financial institution account number or financial institution account alias, such as Clabe for MX (MAX 255; MIN 3).
          - `number` string, required — Beneficiary's bank account number or bank account alias, such as Clabe for MX (MAX 250; MIN 3)
          - `digit` string — Beneficiary's bank account digit (MAX 250; MIN 3)
          - `type` 'CHECKINGS' | 'SAVINGS' | 'VISTA' | 'PIX_EMAIL' | 'PIX_PHONE' | 'PIX_DOCUMENT_ID' | 'PIX_BANK_ACCOUNT' — Beneficiary's bank account type.
        - `address` object — Bank transfer address details
          - `address_line_1` string — The primary address line (MAX 255; MIN 3).
          - `address_line_2` string — The secondary address line (MAX 255; MIN 1).
          - `city` string — The city considered for the address (MAX 255; MIN 3).
          - `country` 'AR' | 'BO' | 'BR' | 'CL' | 'CO' | 'CR' | 'EC' | 'SV' | 'GT' | 'HN' | 'MX' | 'NI' | 'PA' | 'PY' | 'PE' | 'US' | 'UY' | '' — The country (MAX 2; MIN 2; [ISO 3166-1](country-reference)).
          - `state` string — The state/province from the address (MAX 255; MIN 3).
          - `zip_code` string — The zipcode for the address (MAX 11; MIN 4).
      - `wallet` object — Wallet details to make the withdrawal.
        - `code` string — Beneficiary's wallet account identification code (MAX 3; MIN 250)
        - `email` string — The Beneficiary's email (MAX 255; MIN 3)
        - `country` string — The Beneficiary's country (ISO 3166-1 MAX 2; MIN 2)
        - `document` object — Wallet's owner national document associated to the withdrawal account.
          - `document_number` string, required — The document number (MAX 40; MIN 3).
          - `document_type` 'DNI' | 'CI' | 'LC' | 'LE' | 'CUIT' | 'CUIL' | 'PAS' | 'CPF' | 'RG' | 'CNH' | 'CNPJ' | 'RUT' | 'RUN' | 'CC' | 'CE' | 'NIT' | 'DUI' | 'PIC' | 'DPI' | 'IFR' | 'INE' | 'CP' | 'RFC' | 'CURP' | 'CIP' | 'CIC' | 'CUI' | 'RUC' — Document type (MAX 6, MIN 1; [Country reference](country-reference)).
        - `phone` object — Wallet's owner phone associated to the withdrawal account.
          - `country_code` string — The country calling code of the phone (MAX 3; MIN 1). Check the [Country reference](country-reference) to see the phone codes.
          - `number` string — The phone number, without the country code (MAX 32; MIN 1).
  - `metadata` object[] — Specifies a list of metadata objects. You can add up to 50 metadata objects.
    - `key` string — The metadata key (MAX 48; MIN 1).
    - `value` string — The metadata key value (MAX 512; MIN 1).

## Response `201`

201

- union
  - object
    - `id` string
    - `account_id` string
    - `status` string
    - `merchant_reference` string
    - `purpose` string
    - `country` string
    - `description` string
    - `amount` object
      - `currency` string
      - `value` integer
    - `beneficiary` object
      - `merchant_beneficiary_id` string
      - `national_entity` string
      - `first_name` string
      - `last_name` string
      - `legal_name` string
      - `email` string
      - `country` string
      - `date_of_birth` string
      - `document` object
        - `document_type` string
        - `document_number` string
      - `phone` object
        - `country_code` string
        - `number` string
      - `address` object
        - `address_line_1` string
        - `address_line_2` string
        - `country` string
        - `state` string
        - `city` string
        - `zip_code` string
    - `metadata` unknown[]
      - unknown
    - `created_at` string
    - `updated_at` string
    - `transactions` object[]
      - `id` string
      - `status` string
      - `type` string
      - `response_code` string
      - `merchant_reference` string
      - `purpose` string
      - `description` string
      - `amount` object
        - `currency` string
        - `value` integer
      - `withdrawal_method` object
        - `type` string
        - `detail` object
          - `bank_transfer` unknown
          - `wallet` object
            - `code` string
            - `email` unknown
            - `country` unknown
            - `document` unknown
            - `phone` unknown
      - `provider_data` object
        - `id` string
        - `transaction_id` string
        - `account_id` string
        - `beneficiary_id` string
        - `status` string
        - `status_detail` string
        - `raw_response` string
      - `created_at` string
      - `updated_at` string
  - object
    - `id` string
    - `account_id` string
    - `status` string
    - `merchant_reference` string
    - `purpose` string
    - `country` string
    - `description` unknown
    - `amount` object
      - `currency` string
      - `value` number
    - `beneficiary` object
      - `merchant_beneficiary_id` string
      - `national_entity` unknown
      - `first_name` unknown
      - `last_name` unknown
      - `legal_name` unknown
      - `email` unknown
      - `country` string
      - `date_of_birth` unknown
      - `document` unknown
      - `phone` unknown
      - `address` unknown
    - `metadata` unknown[]
      - unknown
    - `created_at` string
    - `updated_at` string
    - `transactions` object[]
      - `id` string
      - `status` string
      - `type` string
      - `response_code` string
      - `merchant_reference` string
      - `purpose` string
      - `description` unknown
      - `amount` object
        - `currency` string
        - `value` number
      - `withdrawal_method` object
        - `type` string
        - `detail` object
          - `bank_transfer` unknown
          - `wallet` object
            - `code` unknown
            - `email` unknown
            - `country` unknown
            - `document` unknown
            - `phone` object
              - …
      - `provider_data` object
        - `id` string
        - `transaction_id` string
        - `account_id` string
        - `beneficiary_id` string
        - `status` string
        - `status_detail` string
        - `raw_response` string
      - `created_at` string
      - `updated_at` string
  - object
    - `id` string
    - `account_id` string
    - `status` string
    - `merchant_reference` string
    - `purpose` string
    - `country` string
    - `description` unknown
    - `amount` object
      - `currency` string
      - `value` integer
    - `beneficiary` object
      - `merchant_beneficiary_id` string
      - `national_entity` unknown
      - `first_name` unknown
      - `last_name` unknown
      - `legal_name` unknown
      - `email` unknown
      - `country` string
      - `date_of_birth` unknown
      - `document` unknown
      - `phone` unknown
      - `address` unknown
    - `metadata` unknown[]
      - unknown
    - `created_at` string
    - `updated_at` string
    - `transactions` object[]
      - `id` string
      - `status` string
      - `type` string
      - `response_code` string
      - `merchant_reference` string
      - `purpose` string
      - `description` unknown
      - `amount` object
        - `currency` string
        - `value` integer
      - `withdrawal_method` object
        - `type` string
        - `detail` object
          - `bank_transfer` unknown
          - `wallet` object
            - `code` string
            - `email` unknown
            - `country` unknown
            - `document` unknown
            - `phone` unknown
      - `provider_data` object
        - `id` string
        - `transaction_id` string
        - `account_id` string
        - `beneficiary_id` string
        - `status` string
        - `status_detail` string
        - `raw_response` string
      - `created_at` string
      - `updated_at` string
  - object
    - `id` string
    - `account_id` string
    - `status` string
    - `merchant_reference` string
    - `purpose` string
    - `country` string
    - `description` unknown
    - `amount` object
      - `currency` string
      - `value` integer
    - `beneficiary` object
      - `merchant_beneficiary_id` string
      - `national_entity` unknown
      - `first_name` unknown
      - `last_name` unknown
      - `legal_name` unknown
      - `email` unknown
      - `country` string
      - `date_of_birth` unknown
      - `document` unknown
      - `phone` unknown
      - `address` unknown
    - `metadata` unknown[]
      - unknown
    - `created_at` string
    - `updated_at` string
    - `transactions` object[]
      - `id` string
      - `status` string
      - `type` string
      - `response_code` string
      - `merchant_reference` string
      - `purpose` string
      - `description` unknown
      - `amount` object
        - `currency` string
        - `value` integer
      - `withdrawal_method` object
        - `type` string
        - `detail` object
          - `bank_transfer` unknown
          - `wallet` object
            - `code` string
            - `email` unknown
            - `country` unknown
            - `document` unknown
            - `phone` unknown
      - `provider_data` object
        - `id` string
        - `transaction_id` string
        - `account_id` string
        - `beneficiary_id` string
        - `status` string
        - `status_detail` string
        - `raw_response` string
      - `created_at` string
      - `updated_at` string
  - object
    - `id` string
    - `account_id` string
    - `status` string
    - `merchant_reference` string
    - `purpose` string
    - `country` string
    - `description` string
    - `amount` object
      - `currency` string
      - `value` integer
    - `beneficiary` object
      - `merchant_beneficiary_id` string
      - `national_entity` unknown
      - `first_name` unknown
      - `last_name` unknown
      - `legal_name` unknown
      - `email` unknown
      - `country` string
      - `date_of_birth` unknown
      - `document` unknown
      - `phone` unknown
      - `address` unknown
    - `metadata` object[]
      - `key` string
      - `value` string
    - `transactions` object[]
      - `id` string
      - `status` string
      - `type` string
      - `response_code` string
      - `merchant_reference` string
      - `purpose` string
      - `description` string
      - `amount` object
        - `currency` string
        - `value` integer
      - `withdrawal_method` object
        - `type` string
        - `provider_id` string
        - `original_transaction_id` unknown
        - `detail` object
          - `bank_transfer` unknown
          - `wallet` object
            - `code` string
            - `email` unknown
            - `country` unknown
            - `document` unknown
            - `phone` unknown
      - `provider_data` object
        - `id` string
        - `transaction_id` string
        - `account_id` string
        - `beneficiary_id` string
        - `status` string
        - `status_detail` string
        - `raw_response` string
      - `created_at` string
      - `updated_at` string
    - `created_at` string
    - `updated_at` string

## Other responses

- `400` — 400

---

[API](https://skmtc.net/y/apis/ai-caller.md) · [All operations](https://skmtc.net/y/apis/ai-caller/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/y/ai-caller/versions/05b629819b49/schema)