Saltar al contenido principal

Split (repartir entre receptores)

El Split reparte un pago entre varios receptores según reglas por banco de origen. Se arma en tres pasos: registras al partner, creas el acuerdo de recepción (split-receiving) y luego recibes el pago normalmente (Botón o Solicitud).

Split: reparte un pago entre varios receptores

1. Registra el partner (receptor)​

curl -X POST https://sim-productos.abiertolab.com/api/v1/ext/partner \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{
    "name": "Partner 1",
    "identification": "J-12345678-9",
    "contact_email": "partner@ejemplo.com",
    "contact_phone": "+58-412-0000000",
    "bank_code": "0105",
    "payment_phone_or_cnta": "01050000000000000000",
    "user_type": "comercial"
  }'

2. Crea el acuerdo de recepción (split-receiving)​

curl -X POST https://sim-productos.abiertolab.com/api/v1/ext/split-receiving-agreements \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{
    "title": "Partner 1 (recepción)",
    "description": "Recibir de marketplace X",
    "default_bank_account_id": "uuid_sofitasa_001",
    "rules": [
      { "origin_bank_code": "0105", "destination_bank_account_id": "uuid_mercantil_007" },
      { "origin_bank_code": "0108", "destination_bank_account_id": "uuid_provincial_001" }
    ]
  }'
  • rules — por cada banco de origen, a qué cuenta destino se reparte.

3. Recibe el pago normalmente​

Crea la sesión (Botón o Solicitud) con tu agreement_id habitual. El reparto se aplica en la acreditación (leg 2): el dinero se distribuye a los receptores configurados. → Botón web · Transacción a dos tiempos.

Un solo webhook_url, varias llamadas​

Configuras un único webhook_url por sesión — el mismo campo que usas en cualquier pago, con o sin split. La diferencia en split es que ese mismo endpoint recibe varias llamadas para una sola sesión, no una:

  • Una por receptor, cuando se le acredita su parte: payment_session.accreditation_to_recipient_completed (marcado "en desarrollo" en el contrato).
  • Una de cierre, cuando termina el reparto completo: payment_session.accredited — la misma que en un pago sin split, aquí con el resumen de lo acreditado a todos los receptores.

No hay una URL por receptor ni un webhook_url distinto por partner: todo llega a tu único endpoint, y distingues cada llamada por su event y por el id del receptor dentro del payload.

Un receptor es una cuenta, no una URL

Un receptor (rcv_…) es un destino de fondos: la cuenta bancaria a la que se acredita su parte (default_bank_account_id en el acuerdo de recepción — ver paso 2). No tiene webhook propio: las notificaciones del split siempre llegan a tu webhook_url, nunca al receptor.

Probar en el simulador​

Fuerza ambos tiempos y observa el webhook de acreditación:

curl -X POST https://sim-productos.abiertolab.com/control/sessions/<id>/outcome \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" -d '{"leg":1,"outcome":"paid"}'
curl -X POST https://sim-productos.abiertolab.com/control/sessions/<id>/outcome \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" -d '{"leg":2,"outcome":"accredited"}'
# -> webhook payment_session.accredited (con el resumen de lo acreditado a todos los receptores)

Hoy el simulador emite la llamada de cierre (accredited); la llamada por receptor (accreditation_to_recipient_completed) es parte del contrato pero aún no la reproduce. En producción, prepárate para recibir ambas.

El flujo completo (partner → split-receiving → botón → paid + accredited) está verificado contra el simulador (simulador/test/func/guides.func.test.ts).

→ Usar el simulador