> ## 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.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Crear destinatario

> Crea un destinatario para recibir fondos de pagos divididos en un marketplace

Crea  un nuevo destinatario para escenarios de pago dividido. Este endpoint permite a los comercios definir destinatarios que pueden recibir porciones de los pagos en modelos de marketplace o de pago dividido.


## OpenAPI

````yaml openapi/es/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
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /recipients:
    post:
      summary: Crear destinatario
      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: '{{connection_id}}'
                        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
              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: Destinatario creado correctamente
          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: Solicitud incorrecta
          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: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    code: INVALID_CREDENTIALS
                    messages:
                      - Invalid credentials
        '403':
          description: Prohibido
          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: ID único de la cuenta en Yuno (MAX 64; MIN 36).
          example: 9104911d-5df9-429e-8488-ad41abea1a4b
        merchant_recipient_id:
          type: string
          description: >-
            Identificador único del destinatario definido por el comercio (MAX
            255; MIN 1).
          example: AAAA01
        national_entity:
          type: string
          enum:
            - INDIVIDUAL
            - ENTITY
          description: >-
            Tipo de entidad nacional del beneficiario. Puede ser INDIVIDUAL o
            ENTITY.
          example: INDIVIDUAL
        entity_type:
          type: string
          enum:
            - GOVERNMENTAL
            - PUBLIC
            - NON_PROFIT
            - PRIVATE
          description: >-
            Tipo de organización del beneficiario. GOVERNMENTAL, PUBLIC,
            NON_PROFIT, PRIVATE
          example: PRIVATE
        first_name:
          type: string
          description: Nombre del beneficiario. (MAX 80; MIN 1).
          example: John
        last_name:
          type: string
          description: Apellido del beneficiario. (MAX 80; MIN 1).
          example: Doe
        date_of_birth:
          type: string
          description: >-
            Fecha de nacimiento del beneficiario en formato YYYY-MM-DD (MAX 10;
            MIN 10).
          example: '1990-02-28'
          minLength: 10
          maxLength: 10
        legal_name:
          type: string
          description: >-
            Nombre del beneficiario. (MAX 80; MIN 1) Solo es necesario cuando la
            entidad nacional es ENTITY.
          example: Arcos dorados S.A.
        email:
          type: string
          description: Email del beneficiario (MAX 255; MIN 3).
          example: john.doe@email.com
        country:
          type: string
          description: País del beneficiario (ISO 3166-1 MAX 2; MIN 2).
          example: CO
        website:
          type: string
          description: La URL del sitio web del vendedor (MAX 255; MIN 3).
          example: https://y.uno
          minLength: 3
          maxLength: 255
        industry:
          type: string
          description: >-
            Industria del vendedor (MAX 235; MIN 1). Para más información,
            accede a la página de referencia de categorías de industria.
          example: VIRTUAL_GOODS
          minLength: 1
          maxLength: 235
        merchant_category_code:
          type: string
          description: 'MCC: el código de categoría del comercio (MAX 235; MIN 1).'
        document:
          type: object
          description: Información del documento del beneficiario
          required:
            - document_number
            - document_type
          properties:
            document_number:
              type: string
              description: ID del documento nacional del beneficiario (MAX 40; MIN 3).
              example: '1093333333'
            document_type:
              type: string
              description: Tipo de documento del beneficiario (MAX 6; MIN 2).
              example: CC
        phone:
          type: object
          description: Indica el objeto del número de teléfono del cliente.
          required:
            - country_code
            - number
          properties:
            country_code:
              type: string
              description: >-
                Código de llamada del país del teléfono del cliente (MAX 3; MIN
                1). Consulta la referencia de países para ver los códigos
                telefónicos. Este campo es obligatorio si el objeto 'phone' se
                incluye en la solicitud.
              example: '1'
            number:
              type: string
              description: >-
                El número de teléfono del cliente, sin el código de país (MAX
                32; MIN 1). Este campo es obligatorio si la solicitud incluye el
                objeto 'phone'.
              example: '5551234567'
        address:
          type: object
          description: Dirección
          properties:
            address_line_1:
              type: string
              description: Línea principal de la dirección de facturación (MAX 255; MIN 3).
              example: 'Calle 34 # 56 - 78'
            address_line_2:
              type: string
              description: >-
                Línea secundaria de la dirección de facturación (MAX 255; MIN
                3).
              example: Apartamento 502, Torre I
            city:
              type: string
              description: La ciudad considerada para la dirección (MAX 255; MIN 3).
              example: Bogota
            country:
              type: string
              description: >-
                País considerado para la dirección (ISO 3166-1 MAX 2; MIN 2).
                Obligatorio si hay una dirección.
              example: CO
            state:
              type: string
              description: >-
                Estado / provincia considerado para la dirección (MAX 255; MIN
                3).
              example: Cundinamarca
            zip_code:
              type: string
              description: Código postal considerado para la dirección (MAX 11; MIN 4).
              example: '111111'
            neighborhood:
              type: string
              description: Línea de dirección del barrio (MAX 255; MIN 3).
              example: Downtown
        split_configuration:
          type: object
          description: >-
            Reglas para el cálculo automático de la división a nivel de
            destinatario.
          required:
            - calculation_type
            - currency
          properties:
            calculation_type:
              type: string
              description: El método que se usa para calcular el monto del split.
              enum:
                - PERCENTAGE
                - FIXED
                - MIXED
              example: PERCENTAGE
            percentage:
              type: number
              description: >-
                Porcentaje del monto total del pago que se va a dividir
                (0.01-100.00). Obligatorio si calculation_type es PERCENTAGE o
                MIXED.
              minimum: 0.01
              maximum: 100
              example: 10.5
            fixed_amount:
              type: number
              description: >-
                Monto fijo que se va a dividir. Obligatorio si calculation_type
                es FIXED o MIXED.
              minimum: 0.0001
              example: 5
            currency:
              type: string
              description: >-
                Código de moneda ISO 4217. Obligatorio para todos los tipos de
                cálculo.
              example: USD
            rounding_mode:
              type: string
              description: >-
                La estrategia de redondeo para los montos calculados.
                Obligatorio para PERCENTAGE y MIXED.
              enum:
                - STANDARD
                - ROUND_UP
                - ROUND_DOWN
              example: STANDARD
        legal_representatives:
          type: array
          description: >-
            Propietarios o beneficiarios del destinatario. Obligatorio cuando
            `national_entity = ENTITY`.
          items:
            type: object
            properties:
              merchant_reference:
                type: string
                minLength: 3
                maxLength: 255
                description: ID de identificación del representante legal (MAX 255; MIN 3).
              first_name:
                type: string
                minLength: 1
                maxLength: 255
                description: Nombre (MAX 255; MIN 1).
              last_name:
                type: string
                minLength: 1
                maxLength: 255
                description: Apellido (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: País ISO 3166-1 (2).
              nationality:
                type: string
                minLength: 2
                maxLength: 2
                description: Nacionalidad ISO 3166-1 (2).
              title:
                type: string
                minLength: 1
                maxLength: 255
                description: Cargo (MAX 255; MIN 1).
              publicly_exposed_person:
                type: boolean
                description: Indicador de PEP.
              ultimate_beneficial_owner:
                type: boolean
                description: Indicador de UBO.
        withdrawal_methods:
          type: object
          description: Métodos de retiro del comercio
          properties:
            bank:
              type: object
              description: Información de la cuenta bancaria
              properties:
                code:
                  type: string
                  description: Código del banco (MAX 3; MIN 3).
                  example: '246'
                branch:
                  type: string
                  description: Sucursal del banco (MAX 3; MIN 3).
                  example: XXXX
                branch_digit:
                  type: string
                  description: Dígito de la sucursal del banco (MAX 3; MIN 3).
                account:
                  type: string
                  description: Número de cuenta bancaria del beneficiario (MAX 250; MIN 3).
                  example: '1093333333'
                account_digit:
                  type: string
                  description: >-
                    Dígito de la cuenta bancaria del beneficiario (MAX 250; MIN
                    3).
                account_type:
                  type: string
                  enum:
                    - CHECKINGS
                    - SAVINGS
                  description: >-
                    Tipo de cuenta bancaria del beneficiario. Valores
                    permitidos: CHECKINGS, SAVINGS.
                  example: SAVINGS
                routing:
                  type: string
                  description: Número de ruta de la cuenta bancaria del beneficiario.
                  example: XXXXYYYYC
                country:
                  type: string
                  description: País de la cuenta bancaria (ISO 3166-1 MAX 2; MIN 2).
                  example: CO
                currency:
                  type: string
                  description: Moneda de la cuenta bancaria (ISO 4217 MAX 3; MIN 3).
                  example: COP
                payout_schedule:
                  type: string
                  enum:
                    - DAY
                    - WEEK
                    - MONTH
                    - HOLD
                  description: Preferencia de calendario de payout.
        documentation:
          type: array
          description: Arreglo de objetos de documentación
          items:
            type: object
            required:
              - file_name
              - content_type
              - content_category
              - content
            properties:
              file_name:
                type: string
                description: El nombre de la documentación enviada (MAX 255; MIN 3).
                example: PDF
              content_type:
                type: string
                enum:
                  - application/pdf
                  - image/jpeg
                  - image/png
                description: Tipo de documentación enviada por el comercio.
                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: Categoría de la documentación enviada por el comercio.
              content:
                type: string
                description: >-
                  Contenido de la documentación enviada por el comercio,
                  codificado en base64. Tamaño máximo: 2MB.
                example: >-
                  JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCg==
        onboardings:
          type: array
          description: Arreglo de objetos de onboarding para distintos proveedores de pago
          items:
            type: object
            required:
              - type
              - workflow
              - provider
            properties:
              account_id:
                type: string
                description: >-
                  ID de cuenta opcional para este onboarding. Si se omite, se
                  aplica el `account_id` del destinatario de nivel superior.
              type:
                type: string
                enum:
                  - PREVIOUSLY_ONBOARDED
                  - ONBOARD_ONTO_THE_PROVIDER
                description: Tipo de onboarding. Si lo realiza Yuno.
                example: PREVIOUSLY_ONBOARDED
              workflow:
                type: string
                enum:
                  - HOSTED_BY_PROVIDER
                  - DIRECT
                description: Flujo de trabajo del onboarding.
                example: HOSTED_BY_PROVIDER
              description:
                type: string
                description: Descripción opcional del onboarding (MAX 255; MIN 3).
              callback_url:
                type: string
                description: >-
                  URL a la que redirigir a tu cliente después del proceso de
                  onboarding con el proveedor, si es necesario.
                example: https://www.google.com
              provider:
                type: object
                required:
                  - id
                  - connection_id
                properties:
                  id:
                    type: string
                    enum:
                      - PAGARME
                      - ALELO
                      - EDENRED
                      - PLUXEE
                      - VR
                      - STRIPE
                      - ADYEN
                      - YUNO_TEST_PAYMENT_GW
                    description: ID del proveedor.
                    example: PAGARME
                  connection_id:
                    type: string
                    description: >-
                      ID de la conexión en Yuno. La conexión debe pertenecer a
                      la cuenta que realiza la llamada y su proveedor debe
                      coincidir con `provider.id`. De lo contrario, la API
                      devuelve 400 INVALID_PARAMETERS con el mensaje "Provider X
                      with connection ID Y is invalid."
                  recipient_id:
                    type: string
                    description: Identificador único del destinatario del proveedor.
                    example: AAAAA01
                  recipient_type:
                    type: string
                    description: El tipo de destinatario para el proveedor.
                    enum:
                      - MEAL
                      - FOOD
                      - MULTI_BENEFITS
                      - FLEET
                    example: MEAL
              documentation:
                type: array
                description: Arreglo de objetos de documentación para este onboarding
                items:
                  type: object
                  required:
                    - file_name
                    - content_type
                    - content_category
                    - content
                  properties:
                    file_name:
                      type: string
                      description: El nombre de la documentación enviada (MAX 255; MIN 3).
                      example: PDF
                    content_type:
                      type: string
                      enum:
                        - application/pdf
                        - image/jpeg
                        - image/png
                      description: Tipo de documentación enviada por el comercio.
                      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: Categoría de la documentación enviada por el comercio.
                    content:
                      type: string
                      description: >-
                        Contenido de la documentación enviada por el comercio,
                        codificado en base64. Tamaño máximo: 1MB.
                      example: >-
                        JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCg==
              withdrawal_methods:
                type: array
                description: Métodos de retiro para este onboarding
                items:
                  type: object
                  properties:
                    bank:
                      type: object
                      description: Información de la cuenta bancaria
                      properties:
                        code:
                          type: string
                          description: Código del banco (MAX 3; MIN 3).
                          example: '246'
                        branch:
                          type: string
                          description: Sucursal del banco (MAX 3; MIN 3).
                          example: XXXX
                        branch_digit:
                          type: string
                          description: Dígito de la sucursal del banco (MAX 3; MIN 3).
                        account:
                          type: string
                          description: >-
                            Número de cuenta bancaria del beneficiario (MAX 250;
                            MIN 3).
                          example: '1093333333'
                        account_digit:
                          type: string
                          description: >-
                            Dígito de la cuenta bancaria del beneficiario (MAX
                            250; MIN 3).
                        account_type:
                          type: string
                          enum:
                            - CHECKINGS
                            - SAVINGS
                            - VISTA
                            - PIX_EMAIL
                            - PIX_PHONE
                            - PIX_DOCUMENT_ID
                            - PIX_BANK_ACCOUNT
                          description: >-
                            Tipo de cuenta bancaria del beneficiario (MAX 3; MIN
                            1). Puede ser: CHECKINGS, SAVINGS, VISTA, PIX_EMAIL,
                            PIX_PHONE, PIX_DOCUMENT_ID, PIX_BANK_ACCOUNT.
                          example: SAVINGS
                        routing:
                          type: string
                          description: >-
                            Número de ruta de la cuenta bancaria del
                            beneficiario.
                          example: XXXXYYYYC
                        country:
                          type: string
                          description: >-
                            País de la cuenta bancaria (ISO 3166-1 MAX 2; MIN
                            2).
                          example: CO
                        currency:
                          type: string
                          description: >-
                            Moneda de la cuenta bancaria (ISO 4217 MAX 3; MIN
                            3).
                          example: COP
    RecipientResponse:
      type: object
      properties:
        id:
          type: string
          description: El identificador único del destinatario.
          example: 3aaa4d82-11e8-48ce-8ef5-04eee3a10802
        account_id:
          type: string
          description: El identificador de cuenta asociado a este destinatario.
          example: fe14c7c6-c75e-43b7-bdbe-4c87ad52c482
        merchant_recipient_id:
          type: string
          description: Identificador único del destinatario definido por el comercio.
          example: MERCHANT_182acf1d-faeb-4ff0-94cd-7fab11b282f6
        national_entity:
          type: string
          description: Tipo de entidad nacional del beneficiario.
          example: INDIVIDUAL
        entity_type:
          type: string
          description: Tipo de organización del beneficiario.
          example: PRIVATE
        first_name:
          type: string
          description: Nombre del beneficiario.
          example: Juan
        last_name:
          type: string
          description: Apellido del beneficiario.
          example: Perez
        legal_name:
          type:
            - string
            - 'null'
          description: Razón social del beneficiario.
          example: null
        email:
          type: string
          description: El correo electrónico del beneficiario.
          example: juan.perez@example.com
        date_of_birth:
          type: string
          description: Fecha de nacimiento del beneficiario.
          example: '1990-01-15'
        country:
          type: string
          description: El país del beneficiario.
          example: CO
        website:
          type: string
          description: La URL del sitio web del vendedor.
          example: https://juanperez.com
        industry:
          type: string
          description: El sector del vendedor.
          example: Technology
        merchant_category_code:
          type: string
          description: El código de categoría del comercio (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:
            - array
            - 'null'
          description: >-
            Reglas para el cálculo automático del split a nivel de destinatario.
            Se devuelve como un arreglo que contiene la regla de split actual,
            aunque las solicitudes envían `split_configuration` como un objeto.
            `null` cuando no hay configuración de split.
          items:
            type: object
            required:
              - calculation_type
              - currency
            properties:
              calculation_type:
                type: string
                description: El método que se usa para calcular el monto del split.
                enum:
                  - PERCENTAGE
                  - FIXED
                  - MIXED
                example: PERCENTAGE
              percentage:
                type: number
                description: >-
                  Porcentaje del monto total del pago que se va a dividir
                  (0.01-100.00). Obligatorio si calculation_type es PERCENTAGE o
                  MIXED.
                minimum: 0.01
                maximum: 100
                example: 10.5
              fixed_amount:
                type: number
                description: >-
                  Monto fijo que se va a dividir. Obligatorio si
                  calculation_type es FIXED o MIXED.
                minimum: 0.0001
                example: 5
              currency:
                type: string
                description: >-
                  Código de moneda ISO 4217. Obligatorio para todos los tipos de
                  cálculo.
                example: USD
              rounding_mode:
                type: string
                description: >-
                  La estrategia de redondeo para los montos calculados.
                  Obligatorio para PERCENTAGE y MIXED.
                enum:
                  - STANDARD
                  - ROUND_UP
                  - ROUND_DOWN
                example: STANDARD
              created_at:
                type: string
                format: date-time
                description: >-
                  Fecha y hora en que se estableció la configuración de split
                  (ISO 8601).
                example: '2026-10-13T19:31:45.154978Z'
        created_at:
          type: string
          format: date-time
          description: Fecha de creación del destinatario (ISO 8601 MAX 27; MIN 27).
          example: '2025-08-27T15:41:19.497413Z'
        updated_at:
          type: string
          format: date-time
          description: >-
            Fecha de la última actualización del destinatario (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: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.