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

# Actualizar destinatario

> Actualiza los detalles de un destinatario de marketplace existente, identificado por su recipient_id.

Actualiza un destinatario existente. Solo se actualizarán los campos especificados.

## Actualizaciones de cuenta bancaria

Para los onboardings de Zoop y Pagar.me con un ID de destinatario del proveedor, una actualización explícita de `withdrawal_methods.bank` espera el resultado del proveedor. Los demás campos del destinatario conservan su comportamiento de actualización actual.

Sin `onboarding_id`, Yuno combina los campos bancarios que envías con la cuenta bancaria guardada del destinatario para formar una sola cuenta para los onboardings elegibles. No combina tu solicitud con la cuenta bancaria distinta de cada proveedor. Envía una cuenta completa si la cuenta guardada no aporta los campos faltantes. Los tipos de cuenta aceptados son `CHECKINGS` y `SAVINGS`.

Con `onboarding_id`, la actualización bancaria se dirige solo a ese onboarding y deja sin cambios el valor predeterminado del destinatario y los demás onboardings. Los campos omitidos se toman de la cuenta guardada del onboarding, o del valor predeterminado del destinatario si el onboarding no tiene un registro bancario guardado. Si el onboarding no muestra ninguna cuenta bancaria, envía una cuenta completa.

Por ejemplo, una tienda cambia su cuenta de payout de A a B. Zoop confirma B, pero Pagar.me no confirma el cambio. Yuno mantiene B para Zoop, conserva la cuenta guardada anterior de Pagar.me y actualiza el valor predeterminado del destinatario a B. La solicitud devuelve un error que describe los resultados. **Un error no significa que todos los proveedores hayan quedado sin cambios.** Los cambios exitosos de los proveedores no se revierten.

El valor predeterminado del destinatario avanza después de que al menos un proveedor confirma la actualización. Si todos los proveedores intentados la rechazan o tienen un resultado desconocido, se mantiene el valor predeterminado anterior. Cuando no hay ningún destino elegible vinculado a un proveedor, la cuenta puede guardarse localmente. Leer una cuenta guardada desde Yuno no es una confirmación independiente de un resultado desconocido del proveedor.

Las actualizaciones bancarias no se aplican a los onboardings en `ERROR`, `BLOCKED`, `CANCELLED`, `INACTIVE`, `TRANSFERRED` o `TERMINATED`. Dirigirse a uno de ellos (con `onboarding_id`, [Actualizar onboarding](https://docs.y.uno/es/reference/recipients-for-marketplace/update-onboarding.md) o [Continuar onboarding](https://docs.y.uno/es/reference/recipients-for-marketplace/continue-onboarding.md)) devuelve `400 INVALID_STATE`; una actualización a nivel de destinatario sin `onboarding_id` los omite y conserva su cuenta anterior.

## Errores bancarios y reintentos

| Respuesta | Significado | Acción |
| - | - | - |
| `400 INVALID_PARAMETERS` | La cuenta está incompleta o no es válida, o un proveedor la rechazó explícitamente. Una solicitud con varios proveedores aún puede haberse aplicado a otro proveedor. | Lee todos los mensajes de resultado y corrige los campos indicados. |
| `400 INVALID_STATE` | El onboarding de destino está en un estado que no acepta actualizaciones bancarias. No se envía ninguna solicitud al proveedor. | No reintentes la actualización bancaria en este onboarding. |
| `400 REQUEST_CANNOT_BE_PROCESSED` | O bien la admisión de la actualización bancaria no estaba disponible y no se envió ninguna solicitud al proveedor, o bien al menos un proveedor confirmó la cuenta bancaria (listado como `APPLIED` en los mensajes) y una actualización posterior que no es bancaria falló. | Si un proveedor aparece como `APPLIED`, no vuelvas a enviar la cuenta bancaria; reenvía solo los cambios restantes que no son bancarios. De lo contrario, reintenta la misma solicitud prevista. |
| `400 OPERATION_NOT_SUPPORTED_BY_PROVIDER` | Sin `onboarding_id`, el destinatario también tiene un onboarding cuyo proveedor no admite actualizaciones bancarias. Los proveedores compatibles listados como `APPLIED` fueron actualizados. | Lee los mensajes de resultado. Para cambiar solo un proveedor compatible, envía `onboarding_id`. |
| `409 PROVIDER_TIMEOUT_AMBIGUOUS` | Al menos un resultado no está confirmado. Esto puede incluir rechazos de proveedores que el conector no puede distinguir de una escritura incierta. | Lee primero los mensajes de resultado. Si indican que el proveedor creó la cuenta pero no la convirtió en la cuenta de liquidación, o que la cuenta de liquidación cambió, corrígelo en el proveedor en lugar de reenviar. De lo contrario, revisa la cuenta del proveedor antes de enviar una cuenta bancaria distinta, y reenvía la misma cuenta prevista después del tiempo de espera de aproximadamente tres minutos. |
| `409 ONBOARDING_OPERATION_IN_PROGRESS` | Otra operación retiene la cuenta, o no se pudo intentar uno o más destinos. | Sigue la guía de la respuesta y reintenta la misma solicitud prevista. |

El tiempo de espera reduce las operaciones superpuestas; no garantiza que una escritura tardía del proveedor haya terminado. No reintentes automáticamente con una cuenta distinta. Los mensajes de diagnóstico pueden identificar nombres de campo seguros y omitir los detalles sensibles del proveedor.

En una solicitud que contiene tanto campos bancarios como otros campos del destinatario, Yuno procesa primero los bancarios. Cuando se intentan actualizaciones con proveedores, los demás campos se procesan solo después de que al menos un proveedor confirma la cuenta bancaria. Yuno aún puede devolver un error para los proveedores restantes. Los cambios bancarios confirmados no se revierten si una actualización posterior que no es bancaria falla.

Los resultados bancarios no cambian por sí mismos el estado del ciclo de vida del onboarding. Los proveedores pueden enviar eventos de onboarding de forma independiente después de un cambio bancario, por lo que aún puede llegar un webhook de onboarding.


## OpenAPI

````yaml openapi/es/recipients-for-marketplace/update-recipient-1.json PATCH /recipients/{recipient_id}
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}:
    parameters:
      - name: recipient_id
        in: path
        required: true
        description: El identificador único del destinatario
        schema:
          type: string
    patch:
      summary: Actualizar destinatario
      description: >-
        En los onboardings vinculados a proveedor de Zoop y Pagar.me, las
        actualizaciones bancarias explícitas esperan la confirmación del
        proveedor. Los resultados desconocidos devuelven 409; los cambios
        confirmados no se revierten. Consulta la guía del endpoint para el
        direccionamiento, los resultados parciales y las pautas de reintento.
      operationId: update-recipient
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                onboarding_id:
                  type: string
                  format: uuid
                  description: >-
                    ID de un onboarding existente que pertenece al destinatario.
                    Cuando se establece, los campos de identidad enviados en
                    esta solicitud (por ejemplo, first_name, email, phone,
                    address) se almacenan como una sobrescritura por onboarding
                    solo para ese onboarding, sin modificar el destinatario
                    compartido; cuando se omite, la actualización se aplica al
                    destinatario compartido y se propaga a todos los onboardings
                    no terminales. Solo de solicitud, no se devuelve en las
                    respuestas ni en los webhooks.
                  example: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed
                merchant_recipient_id:
                  type: string
                  description: >-
                    Identificador único del destinatario definido por el
                    comercio (MAX 255; MIN 1).
                first_name:
                  type: string
                  description: Nombre del beneficiario. (MAX 80; MIN 1).
                last_name:
                  type: string
                  description: Apellido del beneficiario. (MAX 80; MIN 1).
                date_of_birth:
                  type: string
                  description: >-
                    Fecha de nacimiento del beneficiario en formato YYYY-MM-DD
                    (MAX 10; MIN 10).
                entity_type:
                  type: string
                  enum:
                    - GOVERNMENTAL
                    - PUBLIC
                    - NON_PROFIT
                    - PRIVATE
                  description: >-
                    Tipo de organización del beneficiario. GOVERNMENTAL, PUBLIC,
                    NON_PROFIT, PRIVATE
                website:
                  type: string
                  description: La URL del sitio web del vendedor (MAX 255; MIN 3).
                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.
                merchant_category_code:
                  type: string
                  description: 'MCC: el código de categoría del comercio (MAX 235; MIN 1).'
                email:
                  type: string
                  description: Email del beneficiario (MAX 255; MIN 3).
                phone:
                  type: object
                  properties:
                    country_code:
                      type: string
                      description: >-
                        Código de área del teléfono celular del beneficiario.
                        (MAX 3; MIN 2).
                    number:
                      type: string
                      description: >-
                        Número de teléfono celular del beneficiario. (MAX 32;
                        MIN 1).
                address:
                  type: object
                  properties:
                    address_line_1:
                      type: string
                      description: >-
                        La línea principal de la dirección de facturación del
                        cliente (MAX 255; MIN 3).
                    address_line_2:
                      type: string
                      description: >-
                        La línea secundaria de la dirección de facturación del
                        cliente (MAX 255; MIN 3).
                    city:
                      type: string
                      description: >-
                        La ciudad considerada para la dirección de facturación
                        (MAX 255; MIN 3).
                    state:
                      type: string
                      description: >-
                        Estado / provincia considerado para la dirección de
                        facturación (MAX 255; MIN 3).
                    zip_code:
                      type: string
                      description: >-
                        Código postal considerado para la dirección de
                        facturación (MAX 11; MIN 4).
                withdrawal_methods:
                  type: array
                  items:
                    type: object
                    properties:
                      bank:
                        type: object
                        properties:
                          code:
                            type: string
                            description: Código del banco (MAX 3; MIN 3).
                          branch:
                            type: string
                            description: Sucursal del banco (MAX 3; MIN 3).
                          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).
                          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 (MAX 3;
                              MIN 1).
                          routing:
                            type: string
                            description: >-
                              Número de ruta de la cuenta bancaria del
                              beneficiario.
                          country:
                            type: string
                            description: >-
                              País de la cuenta bancaria (ISO 3166-1 MAX 2; MIN
                              2).
                          currency:
                            type: string
                            description: >-
                              Moneda de la cuenta bancaria (ISO 4217 MAX 3; MIN
                              3).
                documentation:
                  type: array
                  description: Arreglo de objetos de documentación
                  items:
                    type: object
                    properties:
                      file_name:
                        type: string
                        description: >-
                          El nombre de la documentación enviada (MAX 255; MIN
                          3).
                      content_type:
                        type: string
                        description: Tipo de documentación enviada por el comercio.
                      content_category:
                        type: string
                        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.
                onboardings:
                  type: array
                  description: >-
                    Arreglo de objetos de onboarding para distintos proveedores
                    de pago
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - PREVIOUSLY_ONBOARDED
                          - ONBOARD_ONTO_THE_PROVIDER
                        description: Tipo de onboarding. Si lo realiza Yuno.
                      workflow:
                        type: string
                        enum:
                          - HOSTED_BY_PROVIDER
                          - DIRECT
                        description: Flujo de trabajo del onboarding.
                      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.
                      provider:
                        type: object
                        properties:
                          id:
                            type: string
                            enum:
                              - PAGARME
                              - ALELO
                              - EDENRED
                              - PLUXEE
                              - VR
                              - STRIPE
                              - ADYEN
                            description: ID del proveedor.
                            example: PAGARME
                          recipient_id:
                            type: string
                            description: >-
                              Identificador único del destinatario del
                              proveedor.
                      documentation:
                        type: array
                        description: >-
                          Arreglo de objetos de documentación para este
                          onboarding
                        items:
                          type: object
                          properties:
                            file_name:
                              type: string
                              description: >-
                                El nombre de la documentación enviada (MAX 255;
                                MIN 3).
                            content_type:
                              type: string
                              description: Tipo de documentación enviada por el comercio.
                            content_category:
                              type: string
                              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.
                      withdrawal_methods:
                        type: array
                        description: Métodos de retiro para este onboarding
                        items:
                          type: object
                          properties:
                            bank:
                              type: object
                              properties:
                                code:
                                  type: string
                                  description: Código del banco (MAX 3; MIN 3).
                                branch:
                                  type: string
                                  description: Sucursal del banco (MAX 3; MIN 3).
                                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).
                                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
                                    (MAX 3; MIN 1).
                                routing:
                                  type: string
                                  description: >-
                                    Número de ruta de la cuenta bancaria del
                                    beneficiario.
                                country:
                                  type: string
                                  description: >-
                                    País de la cuenta bancaria (ISO 3166-1 MAX
                                    2; MIN 2).
                                currency:
                                  type: string
                                  description: >-
                                    Moneda de la cuenta bancaria (ISO 4217 MAX
                                    3; MIN 3).
                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
            examples:
              Update Contact Info:
                value:
                  email: newemail@example.com
                  phone:
                    country_code: '57'
                    number: '9876543210'
              Update Address:
                value:
                  address:
                    address_line_1: New Street 123
                    city: New City
                    state: New State
                    zip_code: '12345'
              Update Banking Info:
                value:
                  withdrawal_methods:
                    bank:
                      code: '123'
                      branch: YYY
                      account: '987654321'
                      account_type: CHECKINGS
              Update Onboarding:
                value:
                  onboardings:
                    - type: ONBOARD_ONTO_THE_PROVIDER
                      workflow: DIRECT
                      callback_url: https://myapp.com/new-callback
                      provider:
                        id: ADYEN
              Update Single Onboarding:
                value:
                  onboarding_id: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed
                  email: new.email@example.com
                  phone:
                    country_code: '1'
                    number: '5551234567'
      responses:
        '200':
          description: Destinatario actualizado correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientResponse'
              examples:
                Success Response:
                  value:
                    id: 9104911d-5df9-429e-8488-ad41abea1a4b
                    account_id: 9104911d-5df9-429e-8488-ad41abea1a4b
                    merchant_recipient_id: AAAA01
                    national_entity: INDIVIDUAL
                    first_name: John
                    last_name: Doe
                    email: newemail@example.com
                    country: CO
                    created_at: '2024-01-15T10:30:00Z'
                    updated_at: '2024-01-15T11:45:00Z'
        '400':
          description: >-
            Solicitud no válida o rechazo bancario definitivo. En una solicitud
            que afecta a varios proveedores, es posible que otro proveedor ya
            haya aplicado el cambio bancario; lee los mensajes del resultado. Un
            400 también puede darse después de un cambio bancario confirmado
            cuando falla una actualización posterior que no es bancaria
            (REQUEST_CANNOT_BE_PROCESSED), o significar que el estado del
            onboarding seleccionado no acepta actualizaciones bancarias
            (INVALID_STATE).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Invalid Parameters:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        Provider rejected or requires attention to field:
                        withdrawal_methods.bank.
        '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.
        '409':
          description: >-
            Resultado bancario sin confirmar, o una operación de onboarding
            impide esta solicitud. Revisa el código y los mensajes; es posible
            que ya se haya producido un cambio confirmado en el proveedor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unconfirmed bank update:
                  value:
                    code: PROVIDER_TIMEOUT_AMBIGUOUS
                    messages:
                      - >-
                        Provider ZOOP, onboarding
                        3f6c1a2e-8b4d-4c7e-9a1f-5d2e7b9c0a14: UNKNOWN.
                      - >-
                        The provider did not confirm this bank update. Inspect
                        the provider account before retrying; untrusted provider
                        diagnostics were omitted.
                      - >-
                        Unconfirmed outcomes require provider reconciliation
                        before a different bank is submitted. Resend the same
                        intended account after the approximately three-minute
                        cooldown.
                Operation in progress:
                  value:
                    code: ONBOARDING_OPERATION_IN_PROGRESS
                    messages:
                      - >-
                        A bank or onboarding operation is in progress. After an
                        unconfirmed result, reconcile the provider account
                        before resending the same intended account after about
                        three minutes.
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:
            - 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
            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_PARAMETERS
        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.