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

> Inicia un nuevo onboarding para registrar a un destinatario con un proveedor de pago para payouts divididos

Crea un onboarding para un destinatario.

Este endpoint crea un onboarding para un destinatario y permite integrar submerchants con proveedores de pago en escenarios de pago dividido. Úsalo para registrar nuevos submerchants o configurar destinatarios antes de que puedan recibir pagos divididos.

## Descripción general

El onboarding es el primer paso del flujo de [marketplace con pagos divididos](https://docs.y.uno/es/docs/payment-features/split-payments-marketplace.md#/). Cada destinatario (submerchant) debe completar el onboarding con los proveedores de pago antes de poder recibir pagos divididos.

El proceso de onboarding admite dos flujos:

* **Cuentas con onboarding previo**: para submerchants que ya están registrados con los proveedores. Usa `type: "PREVIOUSLY_ONBOARDED"` y envía `provider.recipient_id`, que es obligatorio para este tipo. Consulta [Cuentas con onboarding previo](#previously-onboarded-accounts).
* **Onboarding dinámico**: para registrar nuevos submerchants, incluida la validación KYC/KYB (Know Your Customer/Know Your Business). Usa `type: "ONE_STEP_ONBOARDING"` o `type: "TWO_STEP_ONBOARDING"` (anteriormente `type: "ONBOARD_ONTO_PROVIDER"`).

> [!NOTE]
>
> **Onboarding en dos pasos**
>
> Para los flujos con `type: "TWO_STEP_ONBOARDING"`, usa el endpoint [Continuar onboarding](https://docs.y.uno/es/reference/recipients-for-marketplace/continue-onboarding.md) para completar el proceso KYC después de crear la cuenta.

## Cuentas con onboarding previo

Usa `type: "PREVIOUSLY_ONBOARDED"` para asociar una cuenta que el submerchant ya tiene en el proveedor, de modo que Yuno no cree una nueva.

Envía los ids de cuenta del proveedor en el objeto `provider`, junto con `provider.id` y `provider.connection_id`. Yuno reenvía los ids a la integración del proveedor exactamente como se envían:

| Campo | Descripción |
| - | - |
| `provider.recipient_id` | El id de cuenta del destinatario en el proveedor. Obligatorio para este tipo. |
| `provider.recipient_additional_id` | Un id de cuenta adicional, para proveedores que identifican una cuenta con más de un id. |
| `provider.balance_account_id` | La cuenta de saldo del destinatario en el proveedor. |
| `provider.legal_entity` | La entidad legal del destinatario en el proveedor. |
| `provider.recipient_type` | El tipo de destinatario para el proveedor. |

Cuáles de estos ids necesita un proveedor lo define su integración. Envía todos los ids que el proveedor usa para identificar la cuenta.

Lo que sucede después depende de si la integración del proveedor admite adoptar cuentas existentes:

* **La integración admite adoptar cuentas existentes**: Yuno registra la cuenta en el proveedor. La respuesta es `201` con estado `CREATED`, y el onboarding pasa luego a:
  * `SUCCEEDED` cuando el proveedor acepta la cuenta. Recibes el webhook `onboarding.succeeded`.
  * `ERROR` cuando el proveedor la rechaza, por ejemplo porque el id de cuenta no existe en el proveedor. El mensaje del proveedor está en `response_message` y recibes el webhook `onboarding.error`. Para corregirlo, [vuelve a registrar la cuenta](https://docs.y.uno/es/reference/recipients-for-marketplace/update-onboarding.md#previously-onboarded-accounts) con los ids correctos.
* **Cualquier otro proveedor**: el onboarding se registra como `SUCCEEDED` de inmediato y no se hace ninguna llamada al proveedor. Los ids se almacenan tal como se envían y no se validan en el proveedor, así que asegúrate de que sean correctos.

Qué proveedores adoptan cuentas existentes es una configuración del lado de Yuno por entorno, no un campo de la API. Para saber si está disponible para tu conexión con el proveedor, contacta a tu Key Account Manager.


## OpenAPI

````yaml openapi/es/recipients-for-marketplace/create-onboarding.json POST /recipients/{recipient_id}/onboardings
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/{recipient_id}/onboardings:
    post:
      summary: Crear onboarding
      operationId: post_{id}onboardings
      parameters:
        - in: path
          name: recipient_id
          description: ID del nuevo destinatario al que se transferirá el onboarding
          schema:
            type: string
          required: true
          example: 9104911d-5df9-429e-8488-ad41abea1a4b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
                - type
                - workflow
                - provider
              properties:
                account_id:
                  type: string
                  description: ID único de la cuenta en Yuno
                  example: 9104911d-5df9-429e-8488-ad41abea1a4b
                type:
                  type: string
                  enum:
                    - PREVIOUSLY_ONBOARDED
                    - ONE_STEP_ONBOARDING
                    - TWO_STEP_ONBOARDING
                  description: >-
                    Tipo de flujo de onboarding. PREVIOUSLY_ONBOARDED asocia una
                    cuenta que ya existe en el proveedor, ONE_STEP_ONBOARDING
                    crea la cuenta y hace el KYC en un solo paso, y
                    TWO_STEP_ONBOARDING primero crea la cuenta y hace el KYC
                    después.


                    En PREVIOUSLY_ONBOARDED, cuando la integración del proveedor
                    permite adoptar cuentas existentes, Yuno registra la cuenta
                    en el proveedor con los ids de `provider`: la respuesta es
                    201 con estado `CREATED`, y luego el onboarding pasa a
                    `SUCCEEDED` (webhook `onboarding.succeeded`) o a `ERROR` con
                    el mensaje del proveedor en `response_message` (webhook
                    `onboarding.error`). Con cualquier otro proveedor, el
                    onboarding se registra como `SUCCEEDED` de inmediato, no se
                    llama al proveedor y los ids no se validan. Qué proveedores
                    adoptan cuentas existentes es una configuración de Yuno por
                    entorno, no un campo de la API; consulta a tu Key Account
                    Manager.
                  example: PREVIOUSLY_ONBOARDED
                workflow:
                  type: string
                  enum:
                    - HOSTED_BY_PROVIDER
                    - DIRECT
                  description: Flujo del onboarding
                  example: HOSTED_BY_PROVIDER
                description:
                  type: string
                  minLength: 3
                  maxLength: 255
                  description: Descripción opcional del onboarding (MAX 255; MIN 3).
                callback_url:
                  type: string
                  format: uri
                  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
                  description: >-
                    Proveedor del onboarding. En PREVIOUSLY_ONBOARDED, los ids
                    de la cuenta del proveedor se reenvían a la integración del
                    proveedor exactamente como se enviaron; qué ids necesita
                    cada proveedor lo define su integración.
                  required:
                    - id
                    - connection_id
                  properties:
                    id:
                      type: string
                      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."
                      example: 8fee3cc6-f3cb-455d-b139-973866111a03
                    recipient_id:
                      type: string
                      description: >-
                        Identificador único del destinatario del proveedor.
                        Obligatorio cuando `type` es PREVIOUSLY_ONBOARDED; de lo
                        contrario, la API devuelve 400 con "Provider recipient
                        ID must be provided for previously onboarded type."
                      example: AAAAA01
                    recipient_additional_id:
                      type: string
                      description: >-
                        Identificador adicional del destinatario en el
                        proveedor, para los proveedores que identifican una
                        cuenta con más de un id. Si hace falta o no lo define la
                        integración del proveedor.
                      example: AAAAA01-SUB
                    balance_account_id:
                      type: string
                      description: >-
                        Identificador de la cuenta de saldo del destinatario en
                        el proveedor. Si hace falta o no lo define la
                        integración del proveedor.
                      example: BA00000000000000000000001
                    legal_entity:
                      type: string
                      description: >-
                        Identificador de la entidad legal del destinatario en el
                        proveedor. Si hace falta o no lo define la integración
                        del proveedor.
                      example: LE00000000000000000000001
                    recipient_type:
                      type: string
                      description: El tipo de destinatario para el proveedor.
                      enum:
                        - MEAL
                        - FOOD
                        - MULTI_BENEFITS
                        - FLEET
                      example: MEAL
                documentation:
                  type: array
                  description: Especifica el objeto de documentación.
                  items:
                    type: object
                    required:
                      - file_name
                      - content_type
                      - content_category
                      - content
                    properties:
                      file_name:
                        type: string
                        minLength: 3
                        maxLength: 255
                        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: El 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: >-
                          La categoría de la documentación enviada por el
                          comercio
                      content:
                        type: string
                        format: byte
                        description: >-
                          Contenido de la documentación enviada por el comercio,
                          codificado en base64. Tamaño máximo: 2MB.
                        example: >-
                          JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCg==
                withdrawal_methods:
                  type: object
                  description: Especifica el objeto de métodos de retiro.
                  properties:
                    bank:
                      type: object
                      description: struct
                      properties:
                        code:
                          type: string
                          minLength: 3
                          maxLength: 3
                          description: Código del banco (MAX 3; MIN 3)
                          example: '246'
                        branch:
                          type: string
                          minLength: 3
                          maxLength: 3
                          description: Sucursal del banco (MAX 3; MIN 3)
                          example: XXXX
                        branch_digit:
                          type: string
                          minLength: 3
                          maxLength: 3
                          description: Dígito de la sucursal del banco (MAX 3; MIN 3)
                        account:
                          type: string
                          minLength: 3
                          maxLength: 250
                          description: >-
                            Número de cuenta bancaria del beneficiario (MAX 3;
                            MIN 250)
                          example: '1093333333'
                        account_digit:
                          type: string
                          minLength: 3
                          maxLength: 250
                          description: >-
                            Dígito de la cuenta bancaria del beneficiario (MAX
                            3; MIN 250)
                        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
                          minLength: 2
                          maxLength: 2
                          description: País de la cuenta bancaria (ISO 3166-1 MAX 2; MIN 2)
                          example: CO
                        currency:
                          type: string
                          minLength: 3
                          maxLength: 3
                          description: >-
                            Moneda de la cuenta bancaria (ISO 3166-1 MAX 3; MIN
                            3)
                          example: COP
                legal_representatives:
                  type: array
                  description: >-
                    Objeto que indica los propietarios de la organización.
                    Adyen, Stripe y dlocal tienen campos relacionados con esto.
                  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 del representante legal. (MAX 255; MIN 1).
                        example: John
                      last_name:
                        type: string
                        minLength: 1
                        maxLength: 255
                        description: Apellido del representante legal. (MAX 255; MIN 1).
                        example: Doe
                      email:
                        type: string
                        format: email
                        minLength: 1
                        maxLength: 255
                        description: Email del representante legal (MAX 255; MIN 1).
                        example: john.doe@email.com
                      date_of_birth:
                        type: string
                        format: date
                        minLength: 10
                        maxLength: 10
                        description: >-
                          Fecha de nacimiento del representante legal en formato
                          YYYY-MM-DD (MAX 10; MIN 10).
                        example: '1990-02-28'
                      country:
                        type: string
                        minLength: 2
                        maxLength: 2
                        description: País del representante legal (ISO 3166-1 MAX 2; MIN 2)
                        example: CO
                      nationality:
                        type: string
                        minLength: 2
                        maxLength: 2
                        description: >-
                          Nacionalidad del representante legal (MAX 2; MIN 2;
                          ISO 3166-1).
                        example: CO
                      title:
                        type: string
                        minLength: 1
                        maxLength: 255
                        description: Cargo del representante legal (MAX 255; MIN 1).
                        example: CTO
                      publicly_exposed_person:
                        type: boolean
                        description: >-
                          Indica si el representante legal es una persona
                          expuesta políticamente
                        example: false
                      ultimate_beneficial_owner:
                        type: boolean
                        description: >-
                          Indica si el representante legal es un beneficiario
                          final de la empresa
                        example: false
                terms_of_service:
                  type: object
                  description: Objeto que describe los términos de servicio.
                  required:
                    - acceptance
                    - date
                  properties:
                    acceptance:
                      type: boolean
                      description: Si el destinatario aceptó los términos de servicio
                      example: true
                    date:
                      type: string
                      format: date-time
                      description: Fecha de aceptación de los términos de servicio
                      example: '2025-07-21T20:43:54.786342Z'
                    ip:
                      type: string
                      format: ipv4
                      description: IP de aceptación de los términos de servicio
                      example: 192.168.1.100
            examples:
              Create Onboarding:
                value:
                  account_id: '{{account-code}}'
                  type: PREVIOUSLY_ONBOARDED
                  workflow: DIRECT
                  callback_url: https://merchant.example.com/webhook/onboarding
                  provider:
                    id: VR
                    connection_id: '{{connection_id}}'
                    recipient_id: test01
                    recipient_type: MULTI_BENEFITS
                  documentation:
                    - file_name: onboarding.pdf
                      content_type: application/pdf
                      content_category: IDENTIFICATION_DOCUMENT
                      content: VGV4dG8gZGUgZWplbXBsbyBwYXJhIEJhc2U2NA==
                  withdrawal_methods:
                    bank:
                      code: '002'
                      branch: '002'
                      account: '9876543210'
                      account_type: CHECKINGS
                      country: US
                      currency: USD
                      routing: '021000022'
                  terms_of_service:
                    acceptance: true
                    date: '2025-07-21T20:43:54.786342Z'
                    ip: 129.21.111.11
      responses:
        '201':
          description: Creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientResponse'
              examples:
                Successful:
                  value:
                    id: 61df26d9-3750-4206-baab-f2e20683f35b
                    type: PREVIOUSLY_ONBOARDED
                    workflow: DIRECT
                    status: SUCCEEDED
                    callback_url: https://merchant.example.com/webhook/onboarding
                    provider:
                      id: STRIPE
                      connection_id: 8fee3cc6-f3cb-455d-b139-973866111a03
                      recipient_id: acct_1RvpogA4Jk50vKRE
                      redirect_url: null
                      onboarding_url: null
                      legal_entity: null
                    documentation:
                      - file_name: recipient.pdf
                        content_type: application/pdf
                        content_category: IDENTIFICATION_DOCUMENT
                        content: recipient.pdf-20ac42c2-ef01-4a0c-80dd-0f9f71c9cde7
                    legal_representatives:
                      - merchant_reference: ONB_001
                        first_name: Tatiana
                        last_name: González
                        email: tatiana.gonzalez@example.com
                        date_of_birth: '1985-05-20'
                        country: BR
                        nationality: BR
                        title: CEO
                        publicly_exposed_person: false
                        ultimate_beneficial_owner: true
                        document:
                          document_type: CC
                          document_number: '0987654321'
                        phone:
                          number: '3109876543'
                          country_code: '+57'
                        address:
                          address_line_1: 'Calle 26 # 13-19'
                          address_line_2: null
                          country: CO
                          state: Cundinamarca
                          city: Bogotá
                          zip_code: '110311'
                    requirements: []
                    withdrawal_methods:
                      bank:
                        code: '003'
                        branch: '003'
                        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:54.786342Z'
                      ip: 129.21.111.11
                    recipient:
                      id: 5a37f0c0-7689-4065-8348-4b5ff5bf9cc7
                      account_id: c24d6c92-99a7-40bb-bc7b-efc40337f9f4
                      merchant_recipient_id: MERCHANT_85ac5f5d-a169-46b3-bd87-80c0df2e6591
                      national_entity: INDIVIDUAL
                      entity_type: PRIVATE
                      first_name: Stebann
                      last_name: Castro
                      legal_name: Steban Castro
                      email: juan.perez@example.com
                      date_of_birth: '1992-01-21'
                      country: CO
                      website: https://juanperez.com
                      industry: Technology
                      merchant_category_code: '5740'
                      document:
                        document_number: '09082160000100'
                        document_type: CNPJ
                      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:
                            number: '3109876543'
                            country_code: '+57'
                          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: recipient.pdf
                          content_type: application/pdf
                          content_category: IDENTIFICATION_DOCUMENT
                          content: recipient.pdf-2bf73b44-33e3-49c7-b777-34a5178cfb45
                      created_at: '2025-08-22T17:54:05.711545Z'
                      updated_at: '2025-08-22T17:54:05.711561Z'
                    history:
                      id: 61df26d9-3750-4206-baab-f2e20683f35b
                      type: PREVIOUSLY_ONBOARDED
                      workflow: DIRECT
                      status: SUCCEEDED
                      callback_url: https://merchant.example.com/webhook/onboarding
                      provider:
                        id: STRIPE
                        connection_id: 8fee3cc6-f3cb-455d-b139-973866111a03
                        recipient_id: acct_1RvpogA4Jk50vKRE
                        redirect_url: null
                      documentation:
                        - file_name: recipient.pdf
                          content_type: application/pdf
                          content_category: IDENTIFICATION_DOCUMENT
                          content: recipient.pdf-20ac42c2-ef01-4a0c-80dd-0f9f71c9cde7
                      legal_representatives:
                        - merchant_reference: ONB_001
                          first_name: Tatiana
                          last_name: González
                          email: tatiana.gonzalez@example.com
                          date_of_birth: '1985-05-20'
                          country: BR
                          nationality: BR
                          title: CEO
                          publicly_exposed_person: false
                          ultimate_beneficial_owner: true
                          document:
                            document_type: CC
                            document_number: '0987654321'
                          phone:
                            number: '3109876543'
                            country_code: '+57'
                          address:
                            address_line_1: 'Calle 26 # 13-19'
                            address_line_2: null
                            country: CO
                            state: Cundinamarca
                            city: Bogotá
                            zip_code: '110311'
                      requirements: []
                      withdrawal_methods:
                        bank:
                          code: '003'
                          branch: '003'
                          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:54.786342Z'
                        ip: 129.21.111.11
                      recipient:
                        id: 5a37f0c0-7689-4065-8348-4b5ff5bf9cc7
                        account_id: c24d6c92-99a7-40bb-bc7b-efc40337f9f4
                        merchant_recipient_id: MERCHANT_85ac5f5d-a169-46b3-bd87-80c0df2e6591
                        national_entity: INDIVIDUAL
                        entity_type: PRIVATE
                        first_name: Stebann
                        last_name: Castro
                        legal_name: Steban Castro
                        email: juan.perez@example.com
                        date_of_birth: '1992-01-21'
                        country: CO
                        website: https://juanperez.com
                        industry: Technology
                        merchant_category_code: '5740'
                        document:
                          document_number: '09082160000100'
                          document_type: CNPJ
                        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:
                              number: '3109876543'
                              country_code: '+57'
                            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: recipient.pdf
                            content_type: application/pdf
                            content_category: IDENTIFICATION_DOCUMENT
                            content: recipient.pdf-2bf73b44-33e3-49c7-b777-34a5178cfb45
                        created_at: '2025-08-22T17:54:05.711545Z'
                        updated_at: '2025-08-22T17:54:05.711561Z'
                      created_at: '2025-08-22T17:57:58.460711Z'
                      updated_at: '2025-08-22T17:57:58.460724Z'
                    created_at: '2025-08-22T17:57:58.460711Z'
                    updated_at: '2025-08-22T17:57:58.460724Z'
                  summary: Successful
        '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:
    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: object
          description: >-
            Reglas para el cálculo automático de la división a nivel de
            destinatario.
          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 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.