Saltar al contenido principal

Transacción a dos tiempos

Un pago en SPIDI no es un solo evento: es un débito y, después, una acreditación. Entender esto evita el error de integración más común.

Transacción a dos tiempos

Los dos tiempos​

Leg 1 — Débito​

El primer paso existe para asegurar la recepción efectiva de los fondos: una única transacción de débito a la cuenta del pagador. El pagador paga, se debita el origen y la sesión pasa de pending a uno de:

  • paid — el pago salió bien (los fondos ya están).
  • failed — el pago fue rechazado (solo aplica al Botón).
  • expired — la sesión venció sin pagarse.

Se emite el webhook payment_session.paid.

Leg 2 — Acreditación​

La acreditación solo puede ocurrir después de tener los fondos (leg 1) y de debitar la comisión de la transacción. Con eso hecho, el dinero se acredita a una o varias cuentas, según el acuerdo que elegiste para ese pago. Se emite el webhook payment_session.accredited.

Un evento de acreditación por cada parte del acuerdo

El webhook de acreditación recibe un evento por cada transacción de crédito, uno por cada parte especificada en el acuerdo:

  • Acuerdo sin split → una sola parte → un evento (payment_session.accredited).
  • Acuerdo con split → una acreditación por receptor + el cierre → varias llamadas a tu mismo webhook_url para esa única sesión. → Split.

El detalle que confunde a todo integrador​

El status nunca refleja el leg 2

Tras paid, el status de la sesión se queda en paid — la acreditación no lo cambia. El leg 2 viaja solo por webhook (payment_session.accredited).

Si tu integración solo consulta GET status esperando un accredited, nunca llegará. Para saber que el dinero se acreditó, escucha el webhook.

Cómo se ve en el tiempo​

crear sesión
   │  status: pending
   ▼
LEG 1  debita  ──────────►  status: paid        + webhook payment_session.paid
   │
   ▼
LEG 2  acredita ─────────►  status: paid (igual) + webhook payment_session.accredited
                                                    (aquí se aplica la comisión)

Por qué importa​

  • Confirmar el pago (leg 1): consulta GET status o escucha payment_session.paid.
  • Confirmar que te llegó el dinero (leg 2): escucha payment_session.accredited — no lo verás en el status.

Pruébalo​

En el simulador puedes forzar cada tiempo por separado y ver ambos webhooks:

# leg 1 (débito)
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"}'
# leg 2 (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":2,"outcome":"accredited"}'

→ Usar el simulador · Manejar notificaciones