> ## 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. # Create Recipient Creates a new recipient for split payment scenarios. This endpoint allows merchants to define recipients that can receive portions of payments in marketplace or split payment models. ## OpenAPI ````yaml openapi/recipients-for-marketplace/create-recipient-1.json POST /recipients openapi: 3.1.0 info: title: Recipients API version: 1.0.0 description: >- API for managing recipients in split payment scenarios. This feature enables merchants to split payments among multiple recipients, which is particularly beneficial for marketplace models where transactions need to be divided among different sellers or stakeholders. servers: - url: https://api-sandbox.y.uno/v1 security: - sec0: [] sec1: [] paths: /recipients: post: summary: Create Recipient operationId: create-recipient requestBody: content: application/json: schema: $ref: '#/components/schemas/Recipient' examples: Individual Recipient: value: account_id: 9104911d-5df9-429e-8488-ad41abea1a4b merchant_recipient_id: AAAA01 national_entity: INDIVIDUAL first_name: John last_name: Doe email: john.doe@email.com country: CO document: document_number: '1093333333' document_type: CC phone: country_code: '57' number: '3132450765' address: address_line_1: 'Calle 34 # 56 - 78' address_line_2: Apartamento 502, Torre I city: Bogota country: CO state: Cundinamarca zip_code: '111111' withdrawal_methods: bank: code: '246' branch: XXXX account: '1093333333' account_type: SAVINGS onboardings: - type: PREVIOUSLY_ONBOARDED workflow: DIRECT description: Onboarding Description callback_url: https://merchant.example.com/webhook/onboarding provider: id: VR connection_id: d2c1f0e9-8a90-432a-ab7c-fdee4c7d58e4 recipient_id: adct_1SB05NPD2RTdZORd recipient_type: FLEET documentation: - file_name: onboarding12.png content_type: image/png content_category: VAT_DOCUMENT content: VGV4dG8gZGUgZWplbXBsbyBwYXJhIEJhc2U2NA== terms_of_service: acceptance: true date: '2025-07-21T20:43:54.786342Z' ip: 129.21.111.11 created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' Create Recipient - US: value: account_id: '{{account_id}}' merchant_recipient_id: MERCHANT_usa_example_10 national_entity: INDIVIDUAL entity_type: PRIVATE first_name: NACHOSOS last_name: UNCAPO legal_name: null email: nach.dos@example.com date_of_birth: '1990-01-15' country: US website: https://johndoe.com industry: Software merchant_category_code: '5734' document: document_number: 123-45-6789 document_type: SSN phone: country_code: '1' number: '4151234567' address: address_line_1: 1234 Market Street address_line_2: Suite 100 city: San Francisco country: US state: California zip_code: '94103' neighborhood: SoMa legal_representatives: - merchant_reference: REP_US_001 first_name: Jane last_name: Smith email: jane.smith@example.com date_of_birth: '1985-05-20' country: US nationality: US title: CEO publicly_exposed_person: false ultimate_beneficial_owner: true document: document_type: SSN document_number: 987-65-4321 phone: number: '6469876543' country_code: '1' address: address_line_1: 1600 Amphitheatre Parkway address_line_2: null country: US state: CA city: Mountain View zip_code: '94043' withdrawal_methods: bank: code: '001' branch: '001' branch_digit: '001' account: '000123456789' account_digit: '001' account_type: CHECKINGS routing: '021000021' country: US currency: USD documentation: - file_name: document content_type: application/pdf content_category: SELFIE content: >- iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAIAAAACUFjqAAAAEklEQVR4nGP8z4APMOGVHbHSAEEsAROxCnMTAAAAAElFTkSuQmCC onboardings: - type: TWO_STEP_ONBOARDING workflow: DIRECT callback_url: https://merchant.example.com/webhook/onboarding provider: id: YUNO_TEST_PAYMENT_GW connection_id: '{{connection_id}}' recipient_id: null documentation: null withdrawal_methods: bank: code: '001' branch: '001' branch_digit: null account: '000123456789' account_digit: null account_type: CHECKINGS routing: '021000021' country: US currency: USD terms_of_service: acceptance: true date: '2025-06-18T00:00:00Z' ip: 192.168.1.100 Entity Recipient: value: account_id: 9104911d-5df9-429e-8488-ad41abea1a4b merchant_recipient_id: AAAA02 national_entity: ENTITY first_name: Business last_name: Corp legal_name: Arcos dorados S.A. email: business@corp.com country: CO document: document_number: '900123456' document_type: NIT phone: country_code: '57' number: '1234567890' address: address_line_1: 'Calle 123 # 45 - 67' city: Medellin country: CO state: Antioquia zip_code: '050001' onboardings: - type: TWO_STEP_ONBOARDING callback_url: https://myapp.com/callback provider: id: STRIPE connection_id: 02ea2568-d99e-4fb9-9bd3-7bb13a822d33 responses: '201': description: Recipient created successfully content: application/json: schema: $ref: '#/components/schemas/RecipientResponse' examples: Success Response: value: id: 3aaa4d82-11e8-48ce-8ef5-04eee3a10802 account_id: fe14c7c6-c75e-43b7-bdbe-4c87ad52c482 merchant_recipient_id: MERCHANT_182acf1d-faeb-4ff0-94cd-7fab11b282f6 national_entity: INDIVIDUAL entity_type: PRIVATE first_name: Juan last_name: Pérez legal_name: null email: juan.perez@example.com date_of_birth: '1990-01-15' country: CO website: https://juanperez.com industry: Technology merchant_category_code: '5734' document: document_number: '1234567890' document_type: CC phone: country_code: '57' number: '3001234567' address: address_line_1: 'Carrera 7 # 32-16' address_line_2: Oficina 201 city: Bogotá country: CO state: Cundinamarca zip_code: '110311' neighborhood: Centro legal_representatives: - merchant_reference: REP_001 first_name: María last_name: González email: maria.gonzalez@example.com date_of_birth: '1985-05-20' country: CO nationality: CO title: CEO publicly_exposed_person: false ultimate_beneficial_owner: true document: document_type: CC document_number: '0987654321' phone: country_code: '57' number: '3109876543' address: address_line_1: 'Calle 26 # 13-19' address_line_2: null country: CO state: Cundinamarca city: Bogotá zip_code: '110311' withdrawal_methods: bank: code: '001' branch: '004' branch_digit: '123' account: '1234567890' account_digit: '123' account_type: SAVINGS routing: '021000021' country: CO currency: COP documentation: - file_name: cc-front.pdf content_type: application/pdf content_category: IDENTIFICATION content: JVBERi0xLjQKJ... onboardings: - id: 84c42684-dbe5-4e0f-bd17-4d094e19762d type: TWO_STEP_ONBOARDING workflow: DIRECT status: PENDING callback_url: https://merchant.example.com/webhook/onboarding provider: id: ALELO connection_id: cc389b51-53a1-4a29-af40-c8cee26c3399 recipient_id: null redirect_url: null onboarding_url: null legal_entity: null balance_account_id: null legal_entity_id: null documentation: - file_name: utility-bill.pdf content_type: application/pdf content_category: ADDRESS_PROOF content: JVBERi0xLjQKJ... requirements: - field: document.cc message: Provide CC document image status: PENDING - field: address.proof message: Upload proof of address status: PENDING withdrawal_methods: bank: code: '002' branch: '002' branch_digit: null account: '9876543210' account_digit: null account_type: SAVINGS routing: '021000022' country: CO currency: COP terms_of_service: acceptance: true date: '2025-07-21T20:43:54Z' ip: 129.21.111.11 created_at: '2025-08-27T15:41:19.516982Z' updated_at: '2025-08-27T15:41:19.516989Z' created_at: '2025-08-27T15:41:19.497413Z' updated_at: '2025-08-27T15:41:19.497425Z' Create Recipient - US: value: id: 3aaa4d82-11e8-48ce-8ef5-04eee3a10802 account_id: fe14c7c6-c75e-43b7-bdbe-4c87ad52c482 merchant_recipient_id: MERCHANT_182acf1d-faeb-4ff0-94cd-7fab11b282f6 national_entity: INDIVIDUAL entity_type: PRIVATE first_name: John last_name: Smith legal_name: null email: john.smith@example.com date_of_birth: '1990-01-15' country: US website: https://johnsmith.com industry: Technology merchant_category_code: '5734' document: document_number: '987654321' document_type: SSN phone: country_code: '1' number: '6465551234' address: address_line_1: 123 Main Street address_line_2: Apt 4B city: New York country: US state: New York zip_code: '10001' neighborhood: null legal_representatives: - merchant_reference: REP_001 first_name: Emily last_name: Johnson email: emily.johnson@example.com date_of_birth: '1985-05-20' country: US nationality: US title: CEO publicly_exposed_person: false ultimate_beneficial_owner: true document: document_type: SSN document_number: '123456789' phone: number: '9175559876' country_code: '1' address: address_line_1: 456 Park Avenue address_line_2: null country: US state: New York city: New York zip_code: '10022' withdrawal_methods: bank: code: '001' branch: '001' branch_digit: '001' account: '1234567890' account_digit: '001' account_type: CHECKINGS routing: '021000021' country: US currency: USD documentation: - file_name: ssn-proof.pdf content_type: application/pdf content_category: IDENTIFICATION content: JVBERi0xLjQKJ... onboardings: - id: 84c42684-dbe5-4e0f-bd17-4d094e19762d type: TWO_STEP_ONBOARDING workflow: DIRECT status: PENDING callback_url: https://merchant.example.com/webhook/onboarding provider: id: ALELO connection_id: cc389b51-53a1-4a29-af40-c8cee26c3399 recipient_id: null redirect_url: null onboarding_url: null legal_entity: null balance_account_id: null legal_entity_id: null documentation: - file_name: utility-bill.pdf content_type: application/pdf content_category: ADDRESS_PROOF content: JVBERi0xLjQKJ... requirements: - field: document.ssn message: Provide SSN document image status: PENDING - field: address.proof message: Upload proof of address status: PENDING withdrawal_methods: bank: code: '002' branch: '002' branch_digit: null account: '9876543210' account_digit: null account_type: CHECKINGS routing: '021000022' country: US currency: USD terms_of_service: acceptance: true date: '2025-07-21T20:43:54Z' ip: 129.21.111.11 created_at: '2025-08-27T15:41:19.516982Z' updated_at: '2025-08-27T15:41:19.516989Z' created_at: '2025-08-27T15:41:19.497413Z' updated_at: '2025-08-27T15:41:19.497425Z' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Invalid Request: value: code: INVALID_REQUEST messages: - Invalid request format Transfer Error: value: id: 9778f631-504d-448f-b2c1-f7b903781df7 recipient_id: 82b12c8c-7d3d-4a21-a3c6-165cc04ca741 amount: currency: USD value: 50000 status: ERROR description: test transfer merchant_reference: cb18df20-21ae-4fed-8da9-fb81cfd56797 metadata: [] provider: null transactions: - code: 9eee65d1-6c3a-4076-9ef9-fa4bff73d597 type: SPLIT_TRANSFER status: ERROR provider_transfer_id: tr_1T9PTLIiMnPsFcbbFKyh1Nds provider_response_message: |- { "id": "tr_1T9PTLIiMnPsFcbbFKyh1Nds", "object": "transfer", "amount": 10000, "amount_reversed": 0, "balance_transaction": "txn_1T9PTMIiMnPsFcbbxRKvaZ3G", "created": 1773145996, "currency": "usd", "description": "test transfer" } provider_raw_response: '{.... }' created_at: '2026-03-10T13:39:19.342902Z' updated_at: '2026-03-10T13:39:19.342914Z' created_at: '2026-03-10T13:39:19.241990247Z' updated_at: '2026-03-10T13:39:19.242012664Z' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Unauthorized: value: code: INVALID_CREDENTIALS messages: - Invalid credentials '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Forbidden: value: code: AUTHORIZATION_REQUIRED messages: - The merchant has no authorization to use this API. components: schemas: Recipient: type: object required: - account_id - merchant_recipient_id - national_entity - first_name - last_name - country properties: account_id: type: string description: Unique id of the account in Yuno (MAX 64; MIN 36). example: 9104911d-5df9-429e-8488-ad41abea1a4b merchant_recipient_id: type: string description: >- Unique identifier of the recipient defined by the merchant (MAX 255; MIN 1). example: AAAA01 national_entity: type: string enum: - INDIVIDUAL - ENTITY description: Beneficiary's national entity type. Could be INDIVIDUAL or ENTITY. example: INDIVIDUAL entity_type: type: string enum: - GOVERNMENTAL - PUBLIC - NON_PROFIT - PRIVATE description: >- The Beneficiary's type of organization. GOVERNMENTAL, PUBLIC, NON_PROFIT, PRIVATE example: PRIVATE first_name: type: string description: Beneficiary's name. (MAX 80; MIN 1). example: John last_name: type: string description: Beneficiary's last name. (MAX 80; MIN 1). example: Doe date_of_birth: type: string description: >- The Beneficiary's date of birth in the YYYY-MM-DD format (MAX 10; MIN 10). example: '1990-02-28' minLength: 10 maxLength: 10 legal_name: type: string description: >- Beneficiary's name. (MAX 80; MIN 1) Only necessary when national entity is ENTITY. example: Arcos dorados S.A. email: type: string description: The Beneficiary's email (MAX 255; MIN 3). example: john.doe@email.com country: type: string description: The Beneficiary's country (ISO 3166-1 MAX 2; MIN 2). example: CO website: type: string description: The seller's website URL (MAX 255; MIN 3). example: https://y.uno minLength: 3 maxLength: 255 industry: type: string description: >- The seller's industry (MAX 235; MIN 1). For more information access the Industry category reference page. example: VIRTUAL_GOODS minLength: 1 maxLength: 235 merchant_category_code: type: string description: MCC - The merchant category code (MAX 235; MIN 1). document: type: object description: Beneficiary's document information required: - document_number - document_type properties: document_number: type: string description: Beneficiary's national document id (MAX 40; MIN 3). example: '1093333333' document_type: type: string description: Beneficiary's document type (MAX 6; MIN 2). example: CC phone: type: object description: Specifies the customer's phone number object. required: - country_code - number properties: country_code: type: string description: >- 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. example: '1' number: type: string description: >- 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. example: '5551234567' address: type: object description: Address properties: address_line_1: type: string description: The primary billing address line (MAX 255; MIN 3). example: 'Calle 34 # 56 - 78' address_line_2: type: string description: The secondary billing address line (MAX 255; MIN 3). example: Apartamento 502, Torre I city: type: string description: The city considered for the address (MAX 255; MIN 3). example: Bogota country: type: string description: >- The country considered for the address (ISO 3166-1 MAX 2; MIN 2). Required if address is present. example: CO state: type: string description: >- The state / province considered for the address (MAX 255; MIN 3). example: Cundinamarca zip_code: type: string description: The zipcode considered for the address (MAX 11; MIN 4). example: '111111' neighborhood: type: string description: The neighborhood address line (MAX 255; MIN 3). example: Downtown split_configuration: type: object description: Rules for automatic split calculation at the recipient level. required: - calculation_type - currency properties: calculation_type: type: string description: The method used to calculate the split amount. enum: - PERCENTAGE - FIXED - MIXED example: PERCENTAGE percentage: type: number description: >- Percentage of the total payment amount to be split (0.01-100.00). Required if calculation_type is PERCENTAGE or MIXED. minimum: 0.01 maximum: 100 example: 10.5 fixed_amount: type: number description: >- Fixed amount to be split. Required if calculation_type is FIXED or MIXED. minimum: 0.0001 example: 5 currency: type: string description: ISO 4217 currency code. Required for all calculation types. example: USD rounding_mode: type: string description: >- The rounding strategy for calculated amounts. Required for PERCENTAGE and MIXED. enum: - STANDARD - ROUND_UP - ROUND_DOWN example: STANDARD legal_representatives: type: array description: >- Owners/beneficials of the recipient. Required when `national_entity = ENTITY`. items: type: object properties: merchant_reference: type: string minLength: 3 maxLength: 255 description: Legal representative's identification id (MAX 255; MIN 3). first_name: type: string minLength: 1 maxLength: 255 description: First name (MAX 255; MIN 1). last_name: type: string minLength: 1 maxLength: 255 description: Last name (MAX 255; MIN 1). email: type: string format: email minLength: 1 maxLength: 255 description: Email (MAX 255; MIN 1). date_of_birth: type: string format: date minLength: 10 maxLength: 10 description: YYYY-MM-DD (MAX 10; MIN 10). country: type: string minLength: 2 maxLength: 2 description: Country ISO 3166-1 (2). nationality: type: string minLength: 2 maxLength: 2 description: Nationality ISO 3166-1 (2). title: type: string minLength: 1 maxLength: 255 description: Job title (MAX 255; MIN 1). publicly_exposed_person: type: boolean description: PEP flag. ultimate_beneficial_owner: type: boolean description: UBO flag. withdrawal_methods: type: object description: Withdrawal methods for the merchant properties: bank: type: object description: Bank's account information properties: code: type: string description: Bank's code (MAX 3; MIN 3). example: '246' branch: type: string description: Bank's branch (MAX 3; MIN 3). example: XXXX branch_digit: type: string description: Bank's branch digit (MAX 3; MIN 3). account: type: string description: Beneficiary's bank account number (MAX 250; MIN 3). example: '1093333333' account_digit: type: string description: Beneficiary's bank account digit (MAX 250; MIN 3). account_type: type: string enum: - CHECKINGS - SAVINGS description: >- Beneficiary's bank account type. Allowed values: CHECKINGS, SAVINGS. example: SAVINGS routing: type: string description: Beneficiary's bank account routing number. example: XXXXYYYYC country: type: string description: The bank account's country (ISO 3166-1 MAX 2; MIN 2). example: CO currency: type: string description: The bank account's currency (ISO 4217 MAX 3; MIN 3). example: COP payout_schedule: type: string enum: - DAY - WEEK - MONTH - HOLD description: Payout schedule preference. documentation: type: array description: Array of documentation objects items: type: object required: - file_name - content_type - content_category - content properties: file_name: type: string description: The name of the documentation sent (MAX 255; MIN 3). example: PDF content_type: type: string enum: - application/pdf - image/jpeg - image/png description: The type of the documentation sent by the merchant. example: application/pdf content_category: type: string enum: - 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 description: The category of the documentation sent by the merchant. content: type: string description: >- The content of the documentation sent by the merchant encoded in base64. Max size: 2MB. example: >- JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCg== onboardings: type: array description: Array of onboarding objects for different payment providers items: type: object required: - type - workflow - provider properties: account_id: type: string description: >- Optional account id for this onboarding. If omitted, the top-level recipient account_id applies. type: type: string enum: - PREVIOUSLY_ONBOARDED - ONBOARD_ONTO_THE_PROVIDER description: Type of onboarding. If its done by Yuno. example: PREVIOUSLY_ONBOARDED workflow: type: string enum: - HOSTED_BY_PROVIDER - DIRECT description: Workflow of the onboarding. example: HOSTED_BY_PROVIDER description: type: string description: Optional description of the onboarding (MAX 255; MIN 3). callback_url: type: string description: >- URL in case to redirect your customer after the onboarding process with the provider, if needed. example: https://www.google.com provider: type: object required: - id - connection_id properties: id: type: string enum: - PAGARME - ALELO - EDENRED - PLUXEE - VR - STRIPE - ADYEN description: Provider id. example: PAGARME connection_id: type: string description: ID of the connection in Yuno recipient_id: type: string description: The unique identifier of the provider's recipient. example: AAAAA01 recipient_type: type: string description: The type of recipient for the provider. enum: - MEAL - FOOD - MULTI_BENEFITS - FLEET example: MEAL documentation: type: array description: Array of documentation objects for this onboarding items: type: object required: - file_name - content_type - content_category - content properties: file_name: type: string description: The name of the documentation sent (MAX 255; MIN 3). example: PDF content_type: type: string enum: - application/pdf - image/jpeg - image/png description: The type of the documentation sent by the merchant. example: application/pdf content_category: type: string enum: - 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 description: The category of the documentation sent by the merchant. content: type: string description: >- The content of the documentation sent by the merchant encoded in base64. Max size: 1MB. example: >- JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCg== withdrawal_methods: type: array description: Withdrawal methods for this onboarding items: type: object properties: bank: type: object description: Bank's account information properties: code: type: string description: Bank's code (MAX 3; MIN 3). example: '246' branch: type: string description: Bank's branch (MAX 3; MIN 3). example: XXXX branch_digit: type: string description: Bank's branch digit (MAX 3; MIN 3). account: type: string description: Beneficiary's bank account number (MAX 250; MIN 3). example: '1093333333' account_digit: type: string description: Beneficiary's bank account digit (MAX 250; MIN 3). account_type: type: string enum: - CHECKINGS - SAVINGS - VISTA - PIX_EMAIL - PIX_PHONE - PIX_DOCUMENT_ID - PIX_BANK_ACCOUNT description: >- Beneficiary's bank account type (MAX 3; MIN 1). Could be: CHECKINGS, SAVINGS, VISTA, PIX_EMAIL, PIX_PHONE, PIX_DOCUMENT_ID, PIX_BANK_ACCOUNT. example: SAVINGS routing: type: string description: Beneficiary's bank account routing number. example: XXXXYYYYC country: type: string description: >- The bank account's country (ISO 3166-1 MAX 2; MIN 2). example: CO currency: type: string description: The bank account's currency (ISO 4217 MAX 3; MIN 3). example: COP documentation: type: array description: Array of documentation objects items: type: object properties: file_name: type: string description: The name of the documentation sent (MAX 255; MIN 3). content_type: type: string enum: - application/pdf - image/jpeg - image/png description: The type of the documentation sent by the merchant. content_category: type: string enum: - 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 description: The category of the documentation sent by the merchant. content: type: string description: >- The content of the documentation sent by the merchant encoded in base64. Max size: 1MB. onboardings: type: array description: Array of onboarding objects for different payment providers items: type: object properties: type: type: string enum: - PREVIOUSLY_ONBOARDED - ONBOARD_ONTO_THE_PROVIDER description: Type of onboarding. If its done by Yuno. workflow: type: string enum: - HOSTED_BY_PROVIDER - DIRECT description: Workflow of the onboarding. callback_url: type: string description: >- URL in case to redirect your customer after the onboarding process with the provider, if needed. provider: type: object properties: id: type: string enum: - PAGARME - ALELO - EDENRED - PLUXEE - VR - STRIPE - ADYEN description: Provider id. example: PAGARME connection_id: type: string description: Id of the connection in Yuno recipient_id: type: string description: The unique identifier of the provider's recipient. documentation: type: array description: Array of documentation objects for this onboarding items: type: object properties: file_name: type: string description: The name of the documentation sent (MAX 255; MIN 3). content_type: type: string enum: - application/pdf - image/jpeg - image/png description: The type of the documentation sent by the merchant. content_category: type: string enum: - 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 description: The category of the documentation sent by the merchant. content: type: string description: >- The content of the documentation sent by the merchant encoded in base64. Max size: 1MB. withdrawal_methods: type: array description: Withdrawal methods for this onboarding items: type: object properties: bank: type: object properties: code: type: string description: Bank's code (MAX 3; MIN 3). branch: type: string description: Bank's branch (MAX 3; MIN 3). branch_digit: type: string description: Bank's branch digit (MAX 3; MIN 3). account: type: string description: Beneficiary's bank account number (MAX 250; MIN 3). account_digit: type: string description: Beneficiary's bank account digit (MAX 250; MIN 3). account_type: type: string enum: - CHECKINGS - SAVINGS description: Beneficiary's bank account type (MAX 3; MIN 1). routing: type: string description: Beneficiary's bank account routing number. country: type: string description: The bank account's country (ISO 3166-1 MAX 2; MIN 2). currency: type: string description: The bank account's currency (ISO 4217 MAX 3; MIN 3). legal_representatives: type: array description: >- Object to indicate the owners of the organization. Adyen, Stripe and dlocal have fields related to that. items: type: object properties: merchant_reference: type: string minLength: 3 maxLength: 255 description: Legal representative's identification id (MAX 255; MIN 3). first_name: type: string minLength: 1 maxLength: 255 description: Legal representative's name. (MAX 255; MIN 1). example: John last_name: type: string minLength: 1 maxLength: 255 description: Legal representative's last name. (MAX 255; MIN 1). example: Doe email: type: string format: email minLength: 1 maxLength: 255 description: The Legal representative's email (MAX 255; MIN 1). example: john.doe@email.com date_of_birth: type: string format: date minLength: 10 maxLength: 10 description: >- The Legal representative's date of birth in the YYYY-MM-DD format (MAX 10; MIN 10). example: '1990-02-28' country: type: string minLength: 2 maxLength: 2 description: >- The Legal representative's country (ISO 3166-1 MAX 2; MIN 2) example: CO nationality: type: string minLength: 2 maxLength: 2 description: >- The Legal representative's nationality (MAX 2; MIN 2; ISO 3166-1). example: CO title: type: string minLength: 1 maxLength: 255 description: The title of the legal representative (MAX 255; MIN 1). example: CTO publicly_exposed_person: type: boolean description: >- Indicates if the legal representative is a publicly exposed person example: false ultimate_beneficial_owner: type: boolean description: >- Indicates if the legal representative is an ultimate beneficiary owner of the company example: false terms_of_service: type: object description: Object describing terms of service. required: - acceptance - date properties: acceptance: type: boolean description: If the terms of service were accepted by the recipient example: true date: type: string format: date-time description: Date of the terms of service acceptance example: '2022-07-09T20:43:54.786342Z' ip: type: string format: ipv4 description: IP of the terms of service acceptance example: 192.168.1.100 RecipientResponse: type: object properties: id: type: string description: The unique identifier of the recipient. example: 3aaa4d82-11e8-48ce-8ef5-04eee3a10802 account_id: type: string description: The account identifier associated with this recipient. example: fe14c7c6-c75e-43b7-bdbe-4c87ad52c482 merchant_recipient_id: type: string description: Unique identifier of the recipient defined by the merchant. example: MERCHANT_182acf1d-faeb-4ff0-94cd-7fab11b282f6 national_entity: type: string description: Beneficiary's national entity type. example: INDIVIDUAL entity_type: type: string description: Beneficiary's type of organization. example: PRIVATE first_name: type: string description: Beneficiary's name. example: Juan last_name: type: string description: Beneficiary's last name. example: Perez legal_name: type: - string - 'null' description: Beneficiary's legal name. example: null email: type: string description: The Beneficiary's email. example: juan.perez@example.com date_of_birth: type: string description: Beneficiary's date of birth. example: '1990-01-15' country: type: string description: The Beneficiary's country. example: CO website: type: string description: The seller's website URL. example: https://juanperez.com industry: type: string description: The seller's industry. example: Technology merchant_category_code: type: string description: The merchant category code (MCC) (MAX 235; MIN 1). example: '5734' document: type: object properties: document_number: type: string example: '1234567890' document_type: type: string example: CC phone: type: object properties: country_code: type: string example: '57' number: type: string example: '3001234567' address: type: object properties: address_line_1: type: string example: 'Carrera 7 # 32-16' address_line_2: type: - string - 'null' example: Oficina 201 city: type: string example: Bogota country: type: string example: CO state: type: string example: Cundinamarca zip_code: type: string example: '110311' neighborhood: type: string example: Centro legal_representatives: type: array items: type: object properties: merchant_reference: type: string example: REP_001 first_name: type: string example: Maria last_name: type: string example: Gonzalez email: type: string example: maria.gonzalez@example.com date_of_birth: type: string example: '1985-05-20' country: type: string example: CO nationality: type: string example: CO title: type: string example: CEO publicly_exposed_person: type: boolean example: false ultimate_beneficial_owner: type: boolean example: true document: type: object properties: document_type: type: string example: CC document_number: type: string example: '0987654321' phone: type: object properties: country_code: type: string example: '57' number: type: string example: '3109876543' address: type: object properties: address_line_1: type: string example: 'Calle 26 # 13-19' address_line_2: type: - string - 'null' example: null country: type: string example: CO state: type: string example: Cundinamarca city: type: string example: Bogota zip_code: type: string example: '110311' withdrawal_methods: type: object properties: bank: type: object properties: code: type: string example: '001' branch: type: string example: '004' branch_digit: type: - string - 'null' example: '123' account: type: string example: '1234567890' account_digit: type: - string - 'null' example: '123' account_type: type: string example: SAVINGS routing: type: string example: '021000021' country: type: string example: CO currency: type: string example: COP documentation: type: array items: type: object properties: file_name: type: string example: cc-front.pdf content_type: type: string example: application/pdf content_category: type: string example: IDENTIFICATION content: type: string example: JVBERi0xLjQKJ... onboardings: type: array items: type: object properties: id: type: string example: 84c42684-dbe5-4e0f-bd17-4d094e19762d type: type: string example: ONBOARD_ONTO_THE_PROVIDER workflow: type: string example: DIRECT status: type: string example: PENDING callback_url: type: string example: https://merchant.example.com/webhook/onboarding provider: type: object properties: id: type: string example: ALELO connection_id: type: string example: cc389b51-53a1-4a29-af40-c8cee26c3399 recipient_id: type: - string - 'null' example: null redirect_url: type: - string - 'null' example: null onboarding_url: type: - string - 'null' example: null legal_entity: type: - string - 'null' example: null balance_account_id: type: - string - 'null' example: null legal_entity_id: type: - string - 'null' example: null documentation: type: array items: type: object properties: file_name: type: string example: utility-bill.pdf content_type: type: string example: application/pdf content_category: type: string example: ADDRESS_PROOF content: type: string example: JVBERi0xLjQKJ... legal_representatives: type: array items: type: object example: [] requirements: type: array items: type: object properties: field: type: string example: document.cc message: type: string example: Provide CC document image status: type: string example: PENDING withdrawal_methods: type: object properties: bank: type: object properties: code: type: string example: '002' branch: type: string example: '002' branch_digit: type: - string - 'null' example: null account: type: string example: '9876543210' account_digit: type: - string - 'null' example: null account_type: type: string example: SAVINGS routing: type: string example: '021000022' country: type: string example: CO currency: type: string example: COP terms_of_service: type: object properties: acceptance: type: boolean example: true date: type: string example: '2025-07-21T20:43:54Z' ip: type: string example: 129.21.111.11 created_at: type: string format: date-time example: '2025-08-27T15:41:19.516982Z' updated_at: type: string format: date-time example: '2025-08-27T15:41:19.516989Z' split_configuration: type: object description: Rules for automatic split calculation at the recipient level. required: - calculation_type - currency properties: calculation_type: type: string description: The method used to calculate the split amount. enum: - PERCENTAGE - FIXED - MIXED example: PERCENTAGE percentage: type: number description: >- Percentage of the total payment amount to be split (0.01-100.00). Required if calculation_type is PERCENTAGE or MIXED. minimum: 0.01 maximum: 100 example: 10.5 fixed_amount: type: number description: >- Fixed amount to be split. Required if calculation_type is FIXED or MIXED. minimum: 0.0001 example: 5 currency: type: string description: ISO 4217 currency code. Required for all calculation types. example: USD rounding_mode: type: string description: >- The rounding strategy for calculated amounts. Required for PERCENTAGE and MIXED. enum: - STANDARD - ROUND_UP - ROUND_DOWN example: STANDARD created_at: type: string format: date-time description: Recipient creation date (ISO 8601 MAX 27; MIN 27). example: '2025-08-27T15:41:19.497413Z' updated_at: type: string format: date-time description: Last Recipient updated date (ISO 8601 MAX 27; MIN 27). example: '2025-08-27T15:41:19.497425Z' ErrorResponse: type: object properties: code: type: string example: INVALID_REQUEST messages: type: array items: type: string example: Invalid request securitySchemes: sec0: type: apiKey in: header name: public-api-key x-default: sec1: type: apiKey in: header name: private-secret-key x-default: ````