Conceptos base (modelo mental)
Antes de escribir una línea de código, conviene tener claro el modelo mental de un pago con SPIDI. Son cuatro ideas; con ellas, todo lo demás encaja.
Esta es la página de referencia del modelo mental. Otras secciones la enlazan en vez de repetirla.
En una frase: defines tu acuerdo (una vez) → creas una sesión con una sola llamada → escuchas avisos porque el pago te llega en dos tiempos. Las cuatro secciones de abajo desarrollan cada pieza.
1. La cuenta y el acuerdo de pago
Tu cuenta se autentica y obtiene un token (Bearer) para llamar a la API.
El acuerdo de pago (agreement, POST /api/v1/ext/agreements) define cómo recibes el dinero: a qué cuenta bancaria se acredita, qué métodos aceptas (débito inmediato, pago móvil, cripto) y si hay reparto (split) entre varios receptores. Creas el acuerdo una vez y luego lo reutilizas en muchos pagos.
Puedes tener varios acuerdos, de distintos tipos — uno por cada caso de uso de pago de tu negocio (con o sin split, distintos métodos o cuentas de destino, distintas reglas de reparto). En cada sesión eliges el acuerdo adecuado con su agreement_id.
Toda sesión de pago necesita un acuerdo — no solo cuando hay split. Sin un agreement_id válido no puedes abrir una sesión: el acuerdo es el contrato que le dice a SPIDI a dónde va el dinero antes de que exista el primer pago.
2. La sesión de pago
Cada pago que recibes es una sesión de pago, y la creas con una sola llamada (referenciando tu agreement_id). SPIDI te devuelve, en esa misma respuesta, una payment_url (la pantalla donde paga la persona) y un status que arranca en pending.
Hay dos formas de iniciarla:
- Botón — el pago ocurre dentro de tu web o app.
- Solicitud — un enlace que envías por un canal externo (WhatsApp, correo, QR).
Y dos variantes sobre el acuerdo: Split (repartir entre receptores) y Paradas (una URL permanente por cliente para pagos recurrentes).
3. La transacción tiene dos tiempos (legs)
Un pago no es un solo evento. Son dos:
| Leg 1 · Débito | Leg 2 · Acreditación | |
|---|---|---|
| Qué pasa | El pagador paga; se debita el origen | El dinero se acredita al beneficiario (y se reparte si hay split) |
status | pending → paid (o failed / expired) | sigue en paid |
| Comisión | — | se aplica aquí |
| Webhook | payment_session.paid | payment_session.accredited |
El status nunca pasa de paid por la acreditación. El leg 2 viaja solo por webhook. Si esperas que GET status diga accredited, te quedas esperando. → Transacción a dos tiempos.
4. Los avisos (webhooks)
Por eso escuchas avisos: como el leg 2 (la acreditación) no aparece en el status, es el webhook tu única fuente de verdad de que el dinero llegó. En cada transición importante, SPIDI POSTea un aviso a tu webhook_url con:
spidi-signature— un sello HMAC-SHA256 del cuerpo crudo, con el secreto de tu cuenta.spidi-timestamp— cuándo se generó.idempotency-key— para que deduplicar los reintentos.
Tu endpoint debe: verificar la firma, deduplicar por idempotency-key y responder 2xx. Si no respondes a tiempo, SPIDI reintenta. → Manejar notificaciones.
El webhook de acreditación recibe un evento por cada transacción de crédito, uno por cada parte especificada en el acuerdo: sin split, un solo payment_session.accredited; con split, una acreditación por receptor más el cierre — todas a tu mismo webhook_url. → Split.
Las dos reglas de oro
- El estado real lo manda tu backend, no la redirección. Volver a
success_urlno significa que te pagaron: confírmalo conGET statuso por el webhook. - El dinero confirmado es el leg 2.
paides el débito; la acreditación (leg 2) es la que te deja el dinero — y solo la conoces por webhook.
Siguiente paso
Ponlo en práctica: → Recibe tu primer pago.