Saltar al contenido principal
PATCH
Actualizar onboarding
Actualiza un onboarding existente de un destinatario. Solo se actualizarán los campos especificados. Este endpoint actualiza un onboarding existente de un destinatario, lo que permite modificar los detalles del onboarding después de su creación inicial. Úsalo cuando necesites actualizar la información del proveedor, la documentación, los datos bancarios u otros parámetros del onboarding de destinatarios existentes en el marketplace de pagos con split.

Requisitos previos

Este endpoint requiere un onboarding existente creado mediante Create Onboarding

Cuentas con onboarding previo

Para volver a registrar un onboarding PREVIOUSLY_ONBOARDED existente, por ejemplo después de que terminó en ERROR porque un id de cuenta era incorrecto, llama a PATCH /v1/recipients/{recipient_id}/onboardings/{onboarding_id} con el objeto provider: provider.id, provider.connection_id y los ids de cuenta.
Los ids de cuenta son los mismos que al crear: provider.recipient_id, provider.recipient_additional_id, provider.balance_account_id, provider.legal_entity y provider.recipient_type. Cuáles de ellos necesita un proveedor lo define su integración. Se reenvían exactamente como se envían.
  • La integración admite adoptar cuentas existentes: Yuno repite el registro en el proveedor y aplica su respuesta. El onboarding pasa a SUCCEEDED (webhook onboarding.succeeded) o a ERROR con el mensaje del proveedor en response_message (webhook onboarding.error). Un onboarding en ERROR pasa a SUCCEEDED una vez que el proveedor acepta los ids corregidos.
  • Cualquier otro proveedor: los ids se almacenan y no se hace ninguna llamada al proveedor. No se validan en el proveedor.
Una actualización sin ids del proveedor solo reenvía la notificación del estado actual; no vuelve a registrar la cuenta. 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.

Actualizar una 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. Actualiza solo el onboarding seleccionado; el valor predeterminado del destinatario y los demás onboardings permanecen sin cambios. Solo se guarda para el onboarding una cuenta confirmada. Los resultados de la actualización bancaria no cambian su estado de ciclo de vida. Envía una cuenta completa cuando el onboarding no muestre ninguna cuenta bancaria. Consulta errores bancarios y reintentos para ver resultados parciales, respuestas 400 y la guía de conciliación de 409. Para estos onboardings compatibles vinculados al proveedor, los campos que no son bancarios, distintos de documentation, se guardan en Yuno sin una actualización separada del perfil en el proveedor. Enviar una descripción o metadata no reenvía la cuenta bancaria guardada. En una solicitud mixta, el banco se procesa primero; los demás campos se guardan solo después de que tenga éxito. Los destinatarios incorporados previamente conservan la notificación de estado existente para las actualizaciones no bancarias sin documentation. Por ejemplo, cambiar solo la descripción de una tienda deja sin cambios su cuenta de pago confirmada y el estado del onboarding. Para cambiar la cuenta de pago, incluye withdrawal_methods.bank de forma explícita.

Actualizar la documentación

Para los onboardings de Zoop con un ID de destinatario del proveedor, una solicitud con documentation envía a Zoop los documentos de esa solicitud y espera el resultado. Esto incluye a los destinatarios incorporados previamente. Solo se envían las categorías de documentos de la solicitud, y la cuenta bancaria no se reenvía.
  • Si Zoop acepta los documentos, el onboarding toma el estado y los requisitos que informa Zoop, y se envía el webhook de onboarding habitual.
  • Si Zoop rechaza los documentos, o no se puede confirmar el envío o el estado resultante, la respuesta es 400 con el código PROVIDER_OPERATION_FAILED. Los documentos se guardan en Yuno, y el onboarding conserva su estado y requisitos anteriores. Reenvía solo documentation.
  • En una solicitud que también actualiza la cuenta bancaria, la actualización bancaria se procesa primero. Si luego fallan los documentos, el 400 también informa el resultado bancario. Un cambio bancario informado como APPLIED permanece aplicado, por lo que debes reenviar solo documentation.
Los onboardings en estado CANCELLED, BLOCKED, INACTIVE o TRANSFERRED rechazan las actualizaciones con 400 INVALID_STATE, excepto los destinatarios incorporados previamente: su actualización guarda documentation en Yuno sin enviarla al proveedor. Un onboarding TERMINATED siempre devuelve 400 INVALID_STATE.

Autorizaciones

public-api-key
string
header
predeterminado:<Your public-api-key>
requerido
private-secret-key
string
header
predeterminado:<Your private-secret-key>
requerido

Parámetros de ruta

recipient_id
string
requerido

ID del destinatario cuyo onboarding se actualizará

onboarding_id
string
requerido

ID del onboarding que se va a actualizar

Cuerpo

application/json
account_id
string

ID único de la cuenta en Yuno

Ejemplo:

"9104911d-5df9-429e-8488-ad41abea1a4b"

type
enum<string>

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.

Para volver a registrar un onboarding PREVIOUSLY_ONBOARDED, envía provider.id, provider.connection_id y los ids de la cuenta del proveedor. Cuando la integración del proveedor permite adoptar cuentas existentes, Yuno repite el registro y aplica la respuesta: el onboarding pasa a SUCCEEDED o a ERROR con el mensaje del proveedor en response_message. Con cualquier otro proveedor, los ids se guardan y no se llama al proveedor. Una actualización sin ids del proveedor solo vuelve a enviar la notificación del estado actual. Qué proveedores adoptan cuentas existentes es una configuración de Yuno por entorno; consulta a tu Key Account Manager.

Opciones disponibles:
PREVIOUSLY_ONBOARDED,
ONE_STEP_ONBOARDING,
TWO_STEP_ONBOARDING
Ejemplo:

"PREVIOUSLY_ONBOARDED"

workflow
enum<string>

Flujo del onboarding

Opciones disponibles:
HOSTED_BY_PROVIDER,
HOSTED_BY_YUNO,
DIRECT
Ejemplo:

"HOSTED_BY_PROVIDER"

callback_url
string<uri>

URL a la que redirigir a tu cliente después del proceso de onboarding con el proveedor, si es necesario.

Ejemplo:

"https://www.google.com"

provider
object

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. Envía id y connection_id junto con los ids para volver a registrar la cuenta.

documentation
object[]

Especifica el objeto de documentación.

withdrawal_methods
object

Especifica el objeto de métodos de retiro.

Objeto que indica los propietarios de la organización. Adyen, Stripe y dlocal tienen campos relacionados con esto.

terms_of_service
object

Objeto que describe los términos de servicio.

Respuesta

Actualizado

id
string

El identificador único del destinatario.

Ejemplo:

"3aaa4d82-11e8-48ce-8ef5-04eee3a10802"

account_id
string

El identificador de cuenta asociado a este destinatario.

Ejemplo:

"fe14c7c6-c75e-43b7-bdbe-4c87ad52c482"

merchant_recipient_id
string

Identificador único del destinatario definido por el comercio.

Ejemplo:

"MERCHANT_182acf1d-faeb-4ff0-94cd-7fab11b282f6"

national_entity
string

Tipo de entidad nacional del beneficiario.

Ejemplo:

"INDIVIDUAL"

entity_type
string

Tipo de organización del beneficiario.

Ejemplo:

"PRIVATE"

first_name
string

Nombre del beneficiario.

Ejemplo:

"Juan"

last_name
string

Apellido del beneficiario.

Ejemplo:

"Perez"

Razón social del beneficiario.

Ejemplo:

null

email
string

El correo electrónico del beneficiario.

Ejemplo:

"juan.perez@example.com"

date_of_birth
string

Fecha de nacimiento del beneficiario.

Ejemplo:

"1990-01-15"

country
string

El país del beneficiario.

Ejemplo:

"CO"

website
string

La URL del sitio web del vendedor.

Ejemplo:

"https://juanperez.com"

industry
string

El sector del vendedor.

Ejemplo:

"Technology"

merchant_category_code
string

El código de categoría del comercio (MCC) (MAX 235; MIN 1).

Ejemplo:

"5734"

document
object
phone
object
address
object
withdrawal_methods
object
documentation
object[]
onboardings
object[]
split_configuration
object

Reglas para el cálculo automático de la división a nivel de destinatario.

created_at
string<date-time>

Fecha de creación del destinatario (ISO 8601 MAX 27; MIN 27).

Ejemplo:

"2025-08-27T15:41:19.497413Z"

updated_at
string<date-time>

Fecha de la última actualización del destinatario (ISO 8601 MAX 27; MIN 27).

Ejemplo:

"2025-08-27T15:41:19.497425Z"