Saltar al contenido principal
PATCH
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 o Continuar onboarding) 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

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.

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

El identificador único del destinatario

Cuerpo

application/json
onboarding_id
string<uuid>

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.

Ejemplo:

"1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"

merchant_recipient_id
string

Identificador único del destinatario definido por el comercio (MAX 255; MIN 1).

first_name
string

Nombre del beneficiario. (MAX 80; MIN 1).

last_name
string

Apellido del beneficiario. (MAX 80; MIN 1).

date_of_birth
string

Fecha de nacimiento del beneficiario en formato YYYY-MM-DD (MAX 10; MIN 10).

entity_type
enum<string>

Tipo de organización del beneficiario. GOVERNMENTAL, PUBLIC, NON_PROFIT, PRIVATE

Opciones disponibles:
GOVERNMENTAL,
PUBLIC,
NON_PROFIT,
PRIVATE
website
string

La URL del sitio web del vendedor (MAX 255; MIN 3).

industry
string

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
string

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

email
string

Email del beneficiario (MAX 255; MIN 3).

phone
object
address
object
withdrawal_methods
object[]
documentation
object[]

Arreglo de objetos de documentación

onboardings
object[]

Arreglo de objetos de onboarding para distintos proveedores de pago

split_configuration
object

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

Respuesta

Destinatario actualizado correctamente

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[] | null

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.

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"