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.

Página canónica

Esta es la página de referencia del modelo mental. Otras secciones la enlazan en vez de repetirla.

Conceptos base: el modelo mental de un pago con SPIDI

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.

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 detalle que confunde a todo integrador

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.

Las dos reglas de oro

1. El estado real lo manda tu backend, no la redirección. Volver a success_url no significa que te pagaron: confírmalo con GET status o por el webhook.
2. El dinero confirmado es el leg 2. paid es 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.