Saltar al contenido principal
POST
Crear onboarding
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. 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.
  • 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").
Onboarding en dos pasosPara los flujos con type: "TWO_STEP_ONBOARDING", usa el endpoint Continuar onboarding 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: 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 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.

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 nuevo destinatario al que se transferirá el onboarding

Cuerpo

application/json
account_id
string
requerido

ID único de la cuenta en Yuno

Ejemplo:

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

type
enum<string>
requerido

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.

Opciones disponibles:
PREVIOUSLY_ONBOARDED,
ONE_STEP_ONBOARDING,
TWO_STEP_ONBOARDING
Ejemplo:

"PREVIOUSLY_ONBOARDED"

workflow
enum<string>
requerido

Flujo del onboarding

Opciones disponibles:
HOSTED_BY_PROVIDER,
DIRECT
Ejemplo:

"HOSTED_BY_PROVIDER"

provider
object
requerido

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.

description
string

Descripción opcional del onboarding (MAX 255; MIN 3).

Required string length: 3 - 255
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"

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

Creado

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"