Características principales
Las características principales de split payments marketplace incluyen:- Pagos divididos: Define cómo se distribuye el monto total del pago entre los distintos destinatarios.
- Configuración flexible: Admite divisiones basadas en montos absolutos y divisiones con cálculo automático.
- Auto Split Configuration: Define reglas a nivel de destinatario (porcentaje, fijo o mixto) para automatizar el cálculo de las divisiones sin especificar montos en cada solicitud de pago.
- Integración con proveedores: Las divisiones pueden ser ejecutadas por proveedores de pago que admitan esta funcionalidad.
- Manejo detallado de tarifas: El sistema permite ajustar con precisión cómo se gestionan las tarifas de transacción y los contracargos. En cada entrada de la división, el objeto
liabilitydefine quién paga la tarifa de transacción (processing_fee:MERCHANT,RECIPIENToSHARED) y si el destinatario es responsable de los contracargos (chargebacks). Consulta Integración de pagos divididos. - Transferencia de onboarding: Permite transferir onboardings entre distintos destinatarios.
- Onboarding
El modelo de onboarding de Yuno está diseñado para ayudar a los marketplaces a conectar y gestionar sin fricciones a sus subcomercios a través de múltiples proveedores de pago. El elemento central de este sistema es el objeto recipient, que representa a cada subcomercio individual dentro del ecosistema del marketplace.
- Cada propietario de marketplace está representado en Yuno como una organización.
- Dentro de una organización se pueden crear una o más cuentas, cada una configurada con su propio conjunto de conexiones a proveedores de pago (por ejemplo, Stripe, Adyen, dLocal).
- Para cada cuenta, el marketplace puede registrar uno o más destinatarios, que son los subcomercios que se incorporarán.
- Cada destinatario se vincula luego de forma individual a una o más conexiones, según los procesadores de pago que vaya a usar.
- Un proceso de onboarding único y unificado.
- Seguimiento independiente del estado por proveedor.
- Escalar fácilmente las operaciones de subcomercios entre proveedores.
Recipients, Sellers y Payouts. Los destinatarios son el modelo de subcomercio: los incorporas por proveedor y los referencias en
split_marketplace y en Transferencias independientes. Sellers (Franchise) es una funcionalidad distinta: un comercio franquicia registra identidades de seller por proveedor para que Yuno resuelva el merchant_id correcto de la conexión al momento del pago. Payouts es una API independiente que envía fondos a beneficiarios mediante métodos de retiro bancarios, con tarjeta o con billetera.Flujos de onboarding
Yuno ofrece dos flujos de onboarding para subcomercios, con flexibilidad según el estado actual del subcomercio con los proveedores de pago.-
Cuentas ya incorporadas: Si un subcomercio ya completó el proceso de onboarding con un proveedor específico (por ejemplo, mediante un dashboard o una plataforma externa), el marketplace puede enviar el
recipient_idcorrespondiente durante la creación. En este caso no se requiere ningún onboarding adicional y el estado se establece de inmediato enSUCCEEDED(onboardings.type=PREVIOUSLY_ONBOARDED). -
Onboarding dinámico: Si no se proporcionan credenciales, Yuno iniciará el proceso de onboarding para el proveedor elegido (
onboardings.type=ONE_STEP_ONBOARDINGoTWO_STEP_ONBOARDING). Este proceso puede incluir:- Envío de un formulario o redirección a una página de onboarding alojada.
- Carga de documentación legal o financiera.
- Finalización de los pasos de validación KYC/KYB.
Flujo de trabajo
El flujo de trabajo de onboarding sigue un proceso estructurado que garantiza que los subcomercios se integren correctamente en el ecosistema del marketplace. El diagrama a continuación ilustra el flujo completo, desde la configuración inicial hasta el procesamiento del pago.
- Configuración de organización y cuenta: El propietario del marketplace crea una organización en Yuno y configura cuentas con conexiones a proveedores de pago.
-
Creación del destinatario: Para cada subcomercio, el marketplace crea un destinatario con el endpoint Create Recipients API, especificando uno de los siguientes:
provider_recipient_idpara subcomercios ya incorporados- Detalles de la conexión con el proveedor para un nuevo onboarding
-
Ejecución del onboarding:
- Ya incorporado: El estado pasa de inmediato a
SUCCEEDED - Nuevo onboarding: Yuno inicia el flujo específico del proveedor, con una progresión de estados de
CREATED→PENDING→SUCCEEDED
- Ya incorporado: El estado pasa de inmediato a
-
Creación del pago: Una vez que los destinatarios se incorporaron correctamente (estado
SUCCEEDED), el marketplace puede crear pagos con el objetosplit_marketplace. - Procesamiento de la división: El proveedor de pago ejecuta la división según la distribución definida y transfiere a cada destinatario la parte que le corresponde.
- Auto Split Configuration
Yuno te permite definir reglas de división automática a nivel de destinatario. Cuando se crea un pago sin un amount explícito para un destinatario en el arreglo split_marketplace, Yuno usa estas reglas para calcular la división automáticamente.
Tipos de cálculo
El objetosplit_configuration admite tres métodos de cálculo:
Modo de redondeo
Para garantizar la precisión en distintas monedas, Yuno admite tres estrategias de redondeo para los cálculos automáticos:Implementación
Puedes definirsplit_configuration al crear o actualizar un destinatario.
*El requisito depende de
calculation_type:- PERCENTAGE:
percentageyrounding_modeson obligatorios. - FIXED:
fixed_amountes obligatorio. - MIXED:
percentage,fixed_amountyrounding_modeson obligatorios.
Example Recipient with Auto Split
- Integración de pagos divididos
En esta sección veremos cómo se usa el objeto split_marketplace para dividir un pago entre varios destinatarios. Este objeto es un arreglo en el que cada entrada especifica un destinatario y la parte del pago que le corresponde.
Pagos con una promoción de Yuno. La división se calcula sobre el monto que paga el cliente,
amount.value menos discount_amount, y las partes no pueden sumar más que ese monto: de lo contrario, el pago se rechaza con 400. Consulta Promociones.En este paso, referencia los destinatarios creados en el Paso 1 (Onboarding).Para
type = PURCHASE o MARKETPLACE, incluye el recipient_id de ese destinatario.Para PAYMENTFEE, VAT y COMMISSION, recipient_id es opcional.| Campo | Tipo | Descripción | Obligatorio | Valor de ejemplo |
|---|---|---|---|---|
recipient_id | string | El identificador único del destinatario dentro del marketplace.Usa el ID de un destinatario creado en el Paso 1 (Onboarding) cuando type es PURCHASE o MARKETPLACE. | Condicional | rec_test123 |
provider_recipient_id | string | El ID del destinatario según lo proporciona el proveedor de pago, si aplica. | Condicional | prov_rec_abc |
| Nota: | Debes proporcionar recipient_id o provider_recipient_id.Para los propietarios de marketplace (type=COMMISSION), provider_recipient_id es opcional si el proveedor no lo requiere. | |||
type* | enum | El tipo de elemento del detalle de la transacción. Las opciones son PURCHASE, PAYMENTFEE, VAT, COMMISSION, MARKETPLACE.recipient_id es obligatorio para PURCHASE y MARKETPLACE. | Condicional | PURCHASE |
| Nota: | Consideraciones de propagación
| |||
merchant_reference | string | Un identificador de la transacción de pago. Es opcional. Si no se especifica, se usará la referencia del comercio del pago principal para todas las transacciones de la división. (MÁX. 255; MÍN. 3 caracteres). | No | AAB01-432245 |
amount | struct | Especifica el monto de la división. Opcional si el destinatario tiene un split_configuration definido. | Condicional | |
value | number | El valor monetario de la división (por ejemplo, 7500 para 75.00). Obligatorio si se proporciona amount. | Condicional | 7500 |
currency | enum | La moneda en la que se realiza el pago (ISO 4217, 3 caracteres). Obligatorio si se proporciona amount. | Condicional | COP |
liability | struct | Información sobre la responsabilidad del destinatario respecto de las tarifas y los contracargos, si aplica. | No | |
processing_fee | enum | Especifica quién es responsable de la tarifa de transacción: MERCHANT, RECIPIENT, SHARED. | No | MERCHANT |
chargebacks | boolean | Indica si el destinatario es responsable de los contracargos (true si es responsable). | No | false |
| Nota: | Cálculo automático de la divisiónSi se omite amount, Yuno usará el split_configuration del destinatario para calcular la parte. Si ambos están presentes, prevalece el amount de la solicitud. |
Example using provider recipients directly
Example using Yuno recipients
Example with Implicit Auto-calculation
Fallback de destinatario para CARD y PIX
Para los pagos CARD y PIX creados mediantePOST /v1/payments, incluida la continuación de esos pagos, un intento que Yuno rechaza con RECIPIENT_NOT_FOUND puede continuar a través de una conexión elegible. Yuno rechaza un intento de esta manera, sin enviarlo al proveedor, cuando un destinatario de la división no tiene un onboarding utilizable con el proveedor enrutado (por ejemplo, cuando el único onboarding está BLOCKED o CANCELLED). No dependas de este fallback para los rechazos devueltos por el proveedor. Cada entrada de la división debe referenciar un recipient_id de Yuno, incluidas las entradas PAYMENTFEE, VAT y COMMISSION, donde de otro modo es opcional.
Una conexión de fallback es elegible solo cuando cada destinatario de la división tiene exactamente un onboarding activo en esa conexión, y ese onboarding tiene el estado SUCCEEDED y un ID de destinatario del proveedor no vacío. Los onboardings en un estado final, como BLOCKED, CANCELLED o DECLINED, no se cuentan. Un onboarding en otra conexión del mismo proveedor no califica. Si especificas recipient_type, el onboarding debe coincidir con ese tipo; de lo contrario, el onboarding correspondiente debe ser inequívoco.
Tu ruta configurada tiene prioridad:
- Se sigue un paso siguiente configurado antes de considerar otro proveedor inicial. Una vez que inicia el fallback de destinatario, un paso de pago que no puede resolver a todos los destinatarios en su conexión se rechaza localmente; su ruta configurada puede continuar con el siguiente paso.
- Un grupo de rechazo coincidente o un código de consejo del comercio (merchant advice code) coincidente sigue siendo una detención.
- Para las rutas con porcentajes de asignación configurados, cuando la ruta de un proveedor inicial terminaría de otro modo, Yuno puede seleccionar un proveedor elegible y aún no intentado entre las conexiones del primer paso de la ruta, dentro del mismo conjunto de condiciones. Si la ruta comienza con un paso de fraude o 3DS, Yuno no busca otro proveedor mediante este fallback. No recorre rutas anidadas ni ramas a las que solo se llega por errores. Se excluyen las conexiones en pausa, las conexiones marcadas por un monitor de enrutamiento y las conexiones con asignación de cero por ciento. Si varias conexiones califican, Yuno prueba primero la de mayor asignación.
DECLINED, el código de respuesta RECIPIENT_NOT_FOUND y sin ID de transacción del proveedor; no se envía ninguna solicitud a ese proveedor. Cuando el fallback tiene éxito, la siguiente transacción usa la conexión seleccionada con la misma división, y un reembolso se aplica a la transacción aprobada. Si no hay una alternativa elegible ni una continuación configurada, el pago termina sin otro cargo del proveedor. Un pago PIX ya aceptado y a la espera de pago no activa este fallback.
Este comportamiento no se aplica a las divisiones que contienen entradas sin un recipient_id de Yuno, incluidas las entradas que usan solo provider_recipient_id, ni a la verificación, la captura, el reembolso, la cancelación o la inscripción. No transfiere un pago aceptado a otro proveedor. Un token del proveedor que cambia la conexión seleccionada también impide el fallback a través de esa selección.
Actualizar la división de una transacción pagada
Cuando un pedido cambia después del pago (por ejemplo, lo entrega otro vendedor), puedes reemplazar la división de la transacción pagada con Actualizar la división de una transacción pagada en lugar de reembolsar y volver a cobrar. Las partes que envíes reemplazan toda la división anterior.El plazo para cambiar una división lo define el proveedor, no Yuno. Con Zoop, la división se puede cambiar hasta el final del día calendario del pago. Después de que se cierra el plazo, la actualización se rechaza con
409 SPLIT_UPDATE_WINDOW_CLOSED y la división no cambia. La actualización se habilita por conexión de proveedor; contacta a Yuno para habilitarla en la tuya.
- Transferencia de onboarding
El objetivo de este flujo es permitir la transferencia de onboardings entre destinatarios de forma controlada y reversible.
El proceso tiene varias etapas. Primero se crea el destinatario inicial con su onboarding (un paso previo). Más adelante, cuando se requiere una transferencia, sigue los pasos para crear el nuevo destinatario, usar el servicio de transferencia y, si es necesario, revertir la operación.
- Destinatario y onboarding (antes de cualquier transferencia): Crea el destinatario y luego crea el onboarding.
Este paso ocurre con anticipación, cuando se crea un nuevo destinatario y se le asigna su onboarding. No forma parte de la transferencia en sí.
- Crea el nuevo destinatario y el onboarding: Usa los endpoints crear destinatario y crear onboarding para configurar el destinatario y el onboarding que recibirán la transferencia.
-
Transfiere el onboarding: Usa transferir onboarding e incluye:
recipient_id: el ID del destinatario de destinoonboarding_id: el onboarding que se transferirá
-
Revierte la transferencia (opcional): Usa revertir onboarding para revertir la transferencia anterior, proporcionando el mismo
recipient_idyonboarding_id.
onboarding incluye un elemento history que almacena la trazabilidad completa del onboarding. Este historial incluye no solo las actualizaciones del objeto, sino también los eventos relacionados con las transferencias entre destinatarios, lo que garantiza una visibilidad completa del ciclo de vida.
- Transferencias independientes
Los comercios suelen necesitar enviar fondos a destinatarios (vendedores, proveedores, contratistas) de forma independiente del ciclo de vida de un pago, directamente desde el saldo de su organización. Esto se conoce como una Transferencia independiente o Forward Transfer.
Esta funcionalidad te permite:
- Distribuir los ingresos por ventas entre los vendedores de un marketplace.
- Pagar a contratistas tras trabajos completados (Gig Economy).
- Gestionar la distribución de ingresos por suscripciones o el pago de comisiones a afiliados.
- Ejecutar payouts masivos a varios destinatarios.
Estados de la transferencia
Un flujo de transferencia independiente pasa por varios estados según la respuesta del proveedor y las reversiones posteriores:Transacciones y reversiones
En el flujo de transferencia independiente, las operaciones directa y de reversión se tratan como transacciones independientes idénticas para mantener un registro de auditoría explícito. Esto significa que:- Transferencia directa (
SPLIT_TRANSFER): Creas una transferencia que mueve fondos de tu saldo a la conexión del destinatario. - Transferencia de reversión (
SPLIT_TRANSFER_REVERSE): Puedes revertir total o parcialmente elSPLIT_TRANSFERpara devolver los fondos a tu saldo. La transferencia directa original debe estar en estadoSUCCEEDEDpara que se pueda realizar una reversión.
Idempotencia
Tanto la creación como la reversión de transferencias independientes requieren una clave de idempotencia mediante el encabezadoX-Idempotency-Key. Esto te permite reintentar solicitudes de forma segura sin duplicar accidentalmente la distribución de fondos. Estas claves se conservan durante 24 horas. Las solicitudes duplicadas que usen la misma combinación de account_id y clave de idempotencia devolverán el objeto de transferencia original.
Validaciones
Para garantizar pagos divididos exitosos, se aplican las siguientes validaciones:- Coincidencia del total de la división: La suma de todas las divisiones debe coincidir con el monto total del pago.
- Existencia del destinatario: Cada
recipient_idincluido en la división debe corresponder a un destinatario incorporado correctamente. - Moneda de Auto Split: Si un destinatario tiene un
split_configuration, sucurrencydebe coincidir exactamente con elamount.currencydel pago. - Consistencia del monto: Si proporcionas un
amount.valuepara un destinatario consplit_configuration, debe coincidir con el resultado del cálculo automático. - Límites de cada división: El valor resuelto de cada división individual debe ser mayor que cero y menor o igual que el monto total del pago.
- Precisión mínima: Para las divisiones
PERCENTAGE, el valor calculado debe ser de al menos0.0001(mínimo de la plataforma). - Campos obligatorios:
- Para divisiones manuales (sin
split_configuration):amount.valueyamount.currencyson obligatorios. - Si se proporciona
split_configurationdurante la creación del destinatario:calculation_typeycurrencyson siempre obligatorios.
- Para divisiones manuales (sin
- Regla de exclusión: Debes incluir
recipient_idoprovider_recipient_iden cada elemento de la división, pero nunca ambos. - Múltiples proveedores: Para los destinatarios vinculados a varios proveedores de pago, usa el objeto recipients para gestionar la lógica de la división entre conexiones.
Endpoints de API involucrados
Esta sección enumera los endpoints de API involucrados en la gestión de pagos divididos.- Crear recipients: POST:
https://api-sandbox.y.uno/v1/recipients - Crear onboarding: POST:
https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings - Continuar onboarding: POST:
https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/continue - Crear pago: POST:
https://api-sandbox.y.uno/v1/payments - Capturar autorización: POST:
https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/capture - Actualizar la división de una transacción pagada: PUT:
https://api-sandbox.y.uno/v1/payments/{payment_id}/transactions/{transaction_id}/split-marketplace - Reembolsar pago: POST:
https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/refund - Cancelar o reembolsar un pago: POST:
https://api-sandbox.y.uno/v1/payments/{id}/cancel-or-refund - Cancelar o reembolsar un pago con transacción: POST:
https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/cancel-or-refund - Transferir onboarding: POST:
https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/transfer - Revertir transferencia de onboarding: POST:
https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/reverse-transfer - Crear transferencia independiente: POST:
https://api-sandbox.y.uno/v1/split-marketplace/transfers - Obtener transferencia independiente: GET:
https://api-sandbox.y.uno/v1/split-marketplace/transfers/{transfer_id} - Revertir transferencia independiente: POST:
https://api-sandbox.y.uno/v1/split-marketplace/transfers/{transfer_id}/reverse