---
title: "Create Recipient"
method: POST
path: "/recipients"
---

# Create Recipient

`POST /recipients`

## Request body

- Recipient
  - `account_id` string, required — Unique id of the account in Yuno (MAX 64; MIN 36).
  - `merchant_recipient_id` string, required — Unique identifier of the recipient defined by the merchant (MAX 255; MIN 1).
  - `national_entity` 'INDIVIDUAL' | 'ENTITY', required — Beneficiary's national entity type. Could be INDIVIDUAL or ENTITY.
  - `entity_type` 'GOVERNMENTAL' | 'PUBLIC' | 'NON_PROFIT' | 'PRIVATE' — The Beneficiary's type of organization. GOVERNMENTAL, PUBLIC, NON_PROFIT, PRIVATE
  - `first_name` string, required — Beneficiary's name. (MAX 80; MIN 1).
  - `last_name` string, required — Beneficiary's last name. (MAX 80; MIN 1).
  - `date_of_birth` string — The Beneficiary's date of birth in the YYYY-MM-DD format (MAX 10; MIN 10).
  - `legal_name` string — Beneficiary's name. (MAX 80; MIN 1) Only necessary when national entity is ENTITY.
  - `email` string — The Beneficiary's email (MAX 255; MIN 3).
  - `country` string, required — The Beneficiary's country (ISO 3166-1 MAX 2; MIN 2).
  - `website` string — The seller's website URL (MAX 255; MIN 3).
  - `industry` string — The seller's industry (MAX 235; MIN 1). For more information access the Industry category reference page.
  - `merchant_category_code` string — MCC - The merchant category code (MAX 235; MIN 1).
  - `document` object — Beneficiary's document information
    - `document_number` string, required — Beneficiary's national document id (MAX 40; MIN 3).
    - `document_type` string, required — Beneficiary's document type (MAX 6; MIN 2).
  - `phone` object — Specifies the customer's phone number object.
    - `country_code` string, required — The country calling code of the customer's phone (MAX 3; MIN 1). Check the Country reference to see the phone codes. This field is required if the 'phone' object is included in the request.
    - `number` string, required — The customer's phone number, without the country code (MAX 32; MIN 1). This field is required if the 'phone' object is included in the request.
  - `address` object — Address
    - `address_line_1` string — The primary billing address line (MAX 255; MIN 3).
    - `address_line_2` string — The secondary billing address line (MAX 255; MIN 3).
    - `city` string — The city considered for the address (MAX 255; MIN 3).
    - `country` string — The country considered for the address (ISO 3166-1 MAX 2; MIN 2). Required if address is present.
    - `state` string — The state / province considered for the address (MAX 255; MIN 3).
    - `zip_code` string — The zipcode considered for the address (MAX 11; MIN 4).
    - `neighborhood` string — The neighborhood address line (MAX 255; MIN 3).
  - `split_configuration` object — Rules for automatic split calculation at the recipient level.
    - `calculation_type` 'PERCENTAGE' | 'FIXED' | 'MIXED', required — The method used to calculate the split amount.
    - `percentage` number — Percentage of the total payment amount to be split (0.01-100.00). Required if calculation_type is PERCENTAGE or MIXED.
    - `fixed_amount` number — Fixed amount to be split. Required if calculation_type is FIXED or MIXED.
    - `currency` string, required — ISO 4217 currency code. Required for all calculation types.
    - `rounding_mode` 'STANDARD' | 'ROUND_UP' | 'ROUND_DOWN' — The rounding strategy for calculated amounts. Required for PERCENTAGE and MIXED.
  - `legal_representatives` object[] — Owners/beneficials of the recipient. Required when `national_entity = ENTITY`.
    - `merchant_reference` string — Legal representative's identification id (MAX 255; MIN 3).
    - `first_name` string — First name (MAX 255; MIN 1).
    - `last_name` string — Last name (MAX 255; MIN 1).
    - `email` string, email — Email (MAX 255; MIN 1).
    - `date_of_birth` string, date — YYYY-MM-DD (MAX 10; MIN 10).
    - `country` string — Country ISO 3166-1 (2).
    - `nationality` string — Nationality ISO 3166-1 (2).
    - `title` string — Job title (MAX 255; MIN 1).
    - `publicly_exposed_person` boolean — PEP flag.
    - `ultimate_beneficial_owner` boolean — UBO flag.
  - `withdrawal_methods` object — Withdrawal methods for the merchant
    - `bank` object — Bank's account information
      - `code` string — Bank's code (MAX 3; MIN 3).
      - `branch` string — Bank's branch (MAX 3; MIN 3).
      - `branch_digit` string — Bank's branch digit (MAX 3; MIN 3).
      - `account` string — Beneficiary's bank account number (MAX 250; MIN 3).
      - `account_digit` string — Beneficiary's bank account digit (MAX 250; MIN 3).
      - `account_type` 'CHECKINGS' | 'SAVINGS' — Beneficiary's bank account type. Allowed values: CHECKINGS, SAVINGS.
      - `routing` string — Beneficiary's bank account routing number.
      - `country` string — The bank account's country (ISO 3166-1 MAX 2; MIN 2).
      - `currency` string — The bank account's currency (ISO 4217 MAX 3; MIN 3).
      - `payout_schedule` 'DAY' | 'WEEK' | 'MONTH' | 'HOLD' — Payout schedule preference.
  - `documentation` object[] — Array of documentation objects
    - `file_name` string, required — The name of the documentation sent (MAX 255; MIN 3).
    - `content_type` 'application/pdf' | 'image/jpeg' | 'image/png', required — The type of the documentation sent by the merchant.
    - `content_category` 'ACCOUNT_REQUIREMENT' | 'BANK_STATEMENT' | 'BUSINESS_ICON' | 'BUSINESS_LOGO' | 'CANCEL_POLICY' | 'CUSTOMER_INTERACTION' | 'DRIVERS_LICENCE' | 'IDENTIFICATION_DOCUMENT' | 'IDENTIFICATION_DOCUMENT_BACK' | 'IDENTIFICATION_DOCUMENT_FRONT' | 'LEGAL_AGREEMENT' | 'OTHERS' | 'PASSPORT' | 'PAYMENT_DETAIL' | 'PROOF_OF_ADDRESS' | 'PROOF_OF_AUTHENTICITY' | 'PROOF_OF_DELIVERY' | 'PROOF_OF_DIRECTOR' | 'PROOF_OF_INDUSTRY' | 'PROOF_OF_NATIONAL_ID_NUMBER' | 'PROOF_OF_OWNERSHIP' | 'PROOF_OF_REGISTRATION' | 'PROOF_OF_RELATIONSHIP' | 'PROOF_OF_SERVICE' | 'PROOF_OF_SOURCE_OF_FUNDS' | 'PROOF_OF_SOURCE_OF_WEALTH' | 'PROOF_OF_TAX' | 'PROVIDER_IDENTITY_DOCUMENT' | 'RECEIPT' | 'REFUND_POLICY' | 'SELFIE' | 'SERVICE_AGREEMENT' | 'SIGNATURE' | 'TERMS_AND_CONDITIONS' | 'VAT_DOCUMENT', required — The category of the documentation sent by the merchant.
    - `content` string, required — The content of the documentation sent by the merchant encoded in base64. Max size: 2MB.
  - `onboardings` object[] — Array of onboarding objects for different payment providers
    - `account_id` string — Optional account id for this onboarding. If omitted, the top-level recipient account_id applies.
    - `type` 'PREVIOUSLY_ONBOARDED' | 'ONBOARD_ONTO_THE_PROVIDER', required — Type of onboarding. If its done by Yuno.
    - `workflow` 'HOSTED_BY_PROVIDER' | 'DIRECT', required — Workflow of the onboarding.
    - `description` string — Optional description of the onboarding (MAX 255; MIN 3).
    - `callback_url` string — URL in case to redirect your customer after the onboarding process with the provider, if needed.
    - `provider` object, required
      - `id` 'PAGARME' | 'ALELO' | 'EDENRED' | 'PLUXEE' | 'VR' | 'STRIPE' | 'ADYEN', required — Provider id.
      - `connection_id` string, required — ID of the connection in Yuno
      - `recipient_id` string — The unique identifier of the provider's recipient.
      - `recipient_type` 'MEAL' | 'FOOD' | 'MULTI_BENEFITS' | 'FLEET' — The type of recipient for the provider.
    - `documentation` object[] — Array of documentation objects for this onboarding
      - `file_name` string, required — The name of the documentation sent (MAX 255; MIN 3).
      - `content_type` 'application/pdf' | 'image/jpeg' | 'image/png', required — The type of the documentation sent by the merchant.
      - `content_category` 'ACCOUNT_REQUIREMENT' | 'BANK_STATEMENT' | 'BUSINESS_ICON' | 'BUSINESS_LOGO' | 'CANCEL_POLICY' | 'CUSTOMER_INTERACTION' | 'DRIVERS_LICENCE' | 'IDENTIFICATION_DOCUMENT' | 'IDENTIFICATION_DOCUMENT_BACK' | 'IDENTIFICATION_DOCUMENT_FRONT' | 'LEGAL_AGREEMENT' | 'OTHERS' | 'PASSPORT' | 'PAYMENT_DETAIL' | 'PROOF_OF_ADDRESS' | 'PROOF_OF_AUTHENTICITY' | 'PROOF_OF_DELIVERY' | 'PROOF_OF_DIRECTOR' | 'PROOF_OF_INDUSTRY' | 'PROOF_OF_NATIONAL_ID_NUMBER' | 'PROOF_OF_OWNERSHIP' | 'PROOF_OF_REGISTRATION' | 'PROOF_OF_RELATIONSHIP' | 'PROOF_OF_SERVICE' | 'PROOF_OF_SOURCE_OF_FUNDS' | 'PROOF_OF_SOURCE_OF_WEALTH' | 'PROOF_OF_TAX' | 'PROVIDER_IDENTITY_DOCUMENT' | 'RECEIPT' | 'REFUND_POLICY' | 'SELFIE' | 'SERVICE_AGREEMENT' | 'SIGNATURE' | 'TERMS_AND_CONDITIONS' | 'VAT_DOCUMENT', required — The category of the documentation sent by the merchant.
      - `content` string, required — The content of the documentation sent by the merchant encoded in base64. Max size: 1MB.
    - `withdrawal_methods` object[] — Withdrawal methods for this onboarding
      - `bank` object — Bank's account information
        - `code` string — Bank's code (MAX 3; MIN 3).
        - `branch` string — Bank's branch (MAX 3; MIN 3).
        - `branch_digit` string — Bank's branch digit (MAX 3; MIN 3).
        - `account` string — Beneficiary's bank account number (MAX 250; MIN 3).
        - `account_digit` string — Beneficiary's bank account digit (MAX 250; MIN 3).
        - `account_type` 'CHECKINGS' | 'SAVINGS' | 'VISTA' | 'PIX_EMAIL' | 'PIX_PHONE' | 'PIX_DOCUMENT_ID' | 'PIX_BANK_ACCOUNT' — Beneficiary's bank account type (MAX 3; MIN 1). Could be: CHECKINGS, SAVINGS, VISTA, PIX_EMAIL, PIX_PHONE, PIX_DOCUMENT_ID, PIX_BANK_ACCOUNT.
        - `routing` string — Beneficiary's bank account routing number.
        - `country` string — The bank account's country (ISO 3166-1 MAX 2; MIN 2).
        - `currency` string — The bank account's currency (ISO 4217 MAX 3; MIN 3).

## Response `201`

Recipient created successfully

- RecipientResponse
  - `id` string — The unique identifier of the recipient.
  - `account_id` string — The account identifier associated with this recipient.
  - `merchant_recipient_id` string — Unique identifier of the recipient defined by the merchant.
  - `national_entity` string — Beneficiary's national entity type.
  - `entity_type` string — Beneficiary's type of organization.
  - `first_name` string — Beneficiary's name.
  - `last_name` string — Beneficiary's last name.
  - `legal_name` unknown
  - `email` string — The Beneficiary's email.
  - `date_of_birth` string — Beneficiary's date of birth.
  - `country` string — The Beneficiary's country.
  - `website` string — The seller's website URL.
  - `industry` string — The seller's industry.
  - `merchant_category_code` string — The merchant category code (MCC) (MAX 235; MIN 1).
  - `document` object
    - `document_number` string
    - `document_type` string
  - `phone` object
    - `country_code` string
    - `number` string
  - `address` object
    - `address_line_1` string
    - `address_line_2` string
    - `city` string
    - `country` string
    - `state` string
    - `zip_code` string
    - `neighborhood` string
  - `legal_representatives` object[]
    - `merchant_reference` string
    - `first_name` string
    - `last_name` string
    - `email` string
    - `date_of_birth` string
    - `country` string
    - `nationality` string
    - `title` string
    - `publicly_exposed_person` boolean
    - `ultimate_beneficial_owner` boolean
    - `document` object
      - `document_type` string
      - `document_number` string
    - `phone` object
      - `country_code` string
      - `number` string
    - `address` object
      - `address_line_1` string
      - `address_line_2` unknown
      - `country` string
      - `state` string
      - `city` string
      - `zip_code` string
  - `withdrawal_methods` object
    - `bank` object
      - `code` string
      - `branch` string
      - `branch_digit` string
      - `account` string
      - `account_digit` string
      - `account_type` string
      - `routing` string
      - `country` string
      - `currency` string
  - `documentation` object[]
    - `file_name` string
    - `content_type` string
    - `content_category` string
    - `content` string
  - `onboardings` object[]
    - `id` string
    - `type` string
    - `workflow` string
    - `status` string
    - `callback_url` string
    - `provider` object
      - `id` string
      - `connection_id` string
      - `recipient_id` unknown
      - `redirect_url` unknown
      - `onboarding_url` unknown
      - `legal_entity` unknown
      - `balance_account_id` unknown
      - `legal_entity_id` unknown
    - `documentation` object[]
      - `file_name` string
      - `content_type` string
      - `content_category` string
      - `content` string
    - `legal_representatives` object[]
    - `requirements` object[]
      - `field` string
      - `message` string
      - `status` string
    - `withdrawal_methods` object
      - `bank` object
        - `code` string
        - `branch` string
        - `branch_digit` unknown
        - `account` string
        - `account_digit` unknown
        - `account_type` string
        - `routing` string
        - `country` string
        - `currency` string
    - `terms_of_service` object
      - `acceptance` boolean
      - `date` string
      - `ip` string
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `split_configuration` object — Rules for automatic split calculation at the recipient level.
    - `calculation_type` 'PERCENTAGE' | 'FIXED' | 'MIXED' — The method used to calculate the split amount.
    - `percentage` number — Percentage of the total payment amount to be split (0.01-100.00). Required if calculation_type is PERCENTAGE or MIXED.
    - `fixed_amount` number — Fixed amount to be split. Required if calculation_type is FIXED or MIXED.
    - `currency` string — ISO 4217 currency code. Required for all calculation types.
    - `rounding_mode` 'STANDARD' | 'ROUND_UP' | 'ROUND_DOWN' — The rounding strategy for calculated amounts. Required for PERCENTAGE and MIXED.
  - `created_at` string, date-time — Recipient creation date (ISO 8601 MAX 27; MIN 27).
  - `updated_at` string, date-time — Last Recipient updated date (ISO 8601 MAX 27; MIN 27).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden

---

[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/revisions/05b629819b49/schema)