Mercado de pagos fraccionados

Esta función permite a los comerciantes dividir los pagos entre varios destinatarios, lo que resulta especialmente útil para los modelos de mercado en los que las transacciones deben dividirse entre distintos vendedores o partes interesadas. Los comerciantes pueden especificar cómo se divide el pago, incluidos los importes, los destinatarios y las comisiones aplicables.

La función de pago fraccionado depende de la compatibilidad del proveedor de pagos seleccionado. Yuno actúa únicamente como organizador del pago, no como procesador. Asegúrese de que su proveedor admita pagos fraccionados antes de usar esta función.

Características principales

Las características principales del mercado de pagos fraccionados incluyen:

• Dividir pagos: Define cómo se distribuye el importe total pago entre los distintos perceptores.
• Configuración flexible: Admite divisiones basadas en valores absolutos.
• Integración con proveedores: Las divisiones pueden ser ejecutadas por proveedores de pago que soporten esta funcionalidad.
• Gestión detallada de las comisiones: El sistema permite ajustar con precisión cómo se gestionan las comisiones por transacción y las devoluciones de cargos.
• Transferencia de Onboarding : Permite la transferencia de onboardings entre diferentes destinatarios.

Para utilizar esta función, primero debe dar de alta a sus destinatarios para la división de pago y , a continuación, crear el pago especificando la información necesaria.

1. Incorporación

El modelo de onboarding Yuno está diseñado para ayudar a los mercados a conectar y gestionar sin problemas a sus submercaderes a través de múltiples proveedores de pago . El elemento central de este sistema es el objeto destinatario, que representa a cada submercader dentro del ecosistema del mercado.

• Cada propietario de mercado 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 mercado puede registrar uno o varios destinatarios, que son los submercaderes que se van a embarcar.
• A continuación, cada destinatario se vincula individualmente a una o varias conexiones, en función de los procesadores de pago que vaya a utilizar.

Esta arquitectura permite:

• Un proceso de incorporación único y unificado.
• Seguimiento de estado independiente por proveedor.
• Fácil escalamiento de operaciones subcomerciales entre proveedores.

Este diseño garantiza la flexibilidad, la transparencia y la trazabilidad total a lo largo del ciclo de vida de onboarding . El endpoint destinatarios se utiliza para crear y gestionar cada perfil de submercader y para activar los correspondientes flujos de trabajo onboarding específicos del proveedor.

Flujos de incorporación

Yuno ofrece dos flujos de incorporación para subcomerciantes, lo que proporciona flexibilidad en función del estado actual del subcomerciante con los proveedores de pago.

1. Cuentas preincorporadas: Si un subcomerciante ya ha completado el proceso de incorporación con un proveedor específico (por ejemplo, a través de un panel o plataforma externa), el mercado puede proporcionar el proveedor correspondiente. recipient_id Durante la creación. En este escenario, no se requiere ninguna incorporación adicional y el estado se establecerá inmediatamente en SUCCEEDED (onboardings.type=PREVIOUSLY_ONBOARDED).

2. Incorporación dinámica: Si no se proporcionan credenciales, Yuno iniciará el proceso de incorporación para el proveedor elegido (onboardings.type=ONE_STEP_ONBOARDING o TWO_STEP_ONBOARDING). Este proceso puede incluir:

   1. Envío de formulario o redirección a una página de incorporación alojada.
   2. Cargar documentación legal o financiera.
   3. Completando los pasos de validación KYC/KYB.

A lo largo del ciclo de vida de incorporación, un destinatario puede experimentar varios estados que reflejan el estado actual del proceso:

Estos estados ayudan al mercado a comprender el ciclo de vida de la incorporación e implementar mecanismos adecuados de reintento, alerta o respaldo cuando sea necesario.

Este enfoque flexible permite a los mercados adaptar el proceso de incorporación a sus necesidades operativas, manteniendo el control y la visibilidad.

Flujo de trabajo

El flujo de trabajo de incorporación sigue un proceso estructurado que garantiza la correcta integración de los subcomerciantes en el ecosistema del mercado. El diagrama a continuación ilustra el flujo completo, desde la configuración inicial hasta el procesamiento del pago.

Pasos del flujo de trabajo:

1. Organización y configuración de cuentas: El propietario del mercado crea una organización en Yuno y configura las cuentas con las conexiones del proveedor de pago.

2. Creación de destinatarios: Para cada submercader, el marketplace crea un destinatario utilizando el endpoint API Crear Destinatarios, especificando:

   • provider_recipient_id para subcomerciantes preincorporados
   • Detalles de conexión del proveedor para la nueva incorporación

3. Ejecución deOnboarding :

   • Pre-incorporado: El estado se convierte inmediatamente en SUCCEEDED
   • Nueva incorporación:Yuno inicia un flujo específico del proveedor con progresión de estado desde CREATED → PENDING → SUCCEEDED

4. Creación de pagos: Una vez que los destinatarios se hayan incorporado correctamente (SUCCEEDED estado), el mercado puede crear pagos con el split_marketplace .

5. Procesamiento del reparto: El proveedor de pago ejecuta la división según la distribución definida, transfiriendo fondos a la parte designada de cada beneficiario.

2. Integración de pagos divididos

En esta sección, exploramos cómo split_marketplace El objeto se utiliza para dividir un payment entre varios destinatarios. Este objeto es una matriz donde cada entrada especifica un destinatario y su parte del pago correspondiente.

ℹ️

En este paso, se hace referencia a los destinatarios creados en el Paso 1 (Incorporación).

Para type = PURCHASE o MARKETPLACE, incluye el recipient_id de ese destinatario.

Para PAYMENTFEE, VAT y COMMISSION, recipient_id es opcional.

{
  "split_marketplace": [
    {
      "provider_recipient_id": "recipient_123",
      "type": "PURCHASE",
      "amount": {
        "value": 750,
        "currency": "EUR"
      }
    },
    {
      "type": "COMMISSION",
      "amount": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ]
}

{
  "split_marketplace": [
    {
      "recipient_id": "4b31a9b8-4cd2-4e47-93cf-03729241bd68",
      "type": "PURCHASE",
      "amount": {
        "value": 750,
        "currency": "EUR"
      }
    },
    {
      "recipient_id": "9104911d-5df9-429e-8488-ad41abea1a4b",
      "type": "COMMISSION",
      "amount": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ]
}

3. Transferencia de incorporación

El objetivo de este flujo es permitir la transferencia de embarques entre receptores de forma controlada y reversible.

El proceso consta de varias etapas. En primer lugar, se crea el destinatario inicial con su onboarding (un paso previo). Posteriormente, cuando se requiere una transferencia, se siguen los pasos para crear el nuevo destinatario, utilizar el servicio de transferencia y, si es necesario, revertir la operación.

1. Destinatario e onboarding (antes de cualquier transferencia): Crear destinatario y, a continuación, crear onboarding.

📘

Este paso se realiza con antelación, cuando se crea un nuevo destinatario y se le asigna su onboarding . No forma parte de la transferencia en sí.

Si decide transferir el onboarding a otro destinatario, continúe el flujo:

2. Cree el nuevo destinatario y onboarding: Utilice los endpoints Crear destinatario y Crear onboarding para configurar el destinatario y el onboarding que recibirán la transferencia.

3. Transfiera el onboarding: Utilice transferir el onboarding e incluir:

   • recipient_id: el ID del destinatario de destino
   • onboarding_id: el onboarding para transferir

   El onboarding se transferirá al nuevo destinatario.

4. Invertir la transferencia (opcional): Usar onboarding inversa para revertir la transferencia anterior, siempre que la misma recipient_id y onboarding_id.

El objeto onboarding incluye un objeto 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.

Validaciones

En esta sección, describimos las validaciones necesarias para garantizar el éxito de los pagos fraccionados.

• El total de todas las fracciones debe coincidir con el monto del pago total.
• Por cada división se deberá enviar un objeto por cada participante, asegurando que la suma de montos sea igual al monto total del pago.
• En los escenarios en los que no se necesita una identificación de destinatario directo para el propietario del mercado (por ejemplo, con Adyen), type El campo puede servir como bandera (por ejemplo, COMMISSION) para indicar la participación del propietario del mercado, lo que hace que provider_recipient_id opcional para esa división específica.
• Cualquiera recipient_id o provider_recipient_id debe incluirse para la división, pero no para ambos.
• Si falta algún campo obligatorio o no es válido, la solicitud generará un error.
• Si se utilizan varios proveedores de pago para pagos divididos, recomendamos utilizar el objeto destinatarios, ya que permite definir más de un proveedor para cada destinatario.

Puntos finales de API involucrados

En esta sección se enumeran los puntos finales de API involucrados en la gestión de pagos divididos.

• Crear destinatarios: POST: https://api-sandbox.y.uno/v1/recipients
• Crear incorporación: 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
• Autorización de captura: POST: https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/capture
• Pago de reembolso: 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
• Traslado onboarding: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/transfer
• onboarding inversa: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/reverse-transfer