Saltar al contenido principal

Botón web

El Botón sirve para recibir pagos dentro de tu web o app: creas una sesión, llevas a la persona a la payment_url y confirmas el pago desde tu backend.

¿Primera vez?

Si es tu primer pago, sigue el tutorial paso a paso. Esta guía es la referencia concentrada del Botón.

Botón: recibe un pago dentro de tu web

1. Crea la sesión de Botón​

curl -X POST https://sim-productos.abiertolab.com/api/v1/ext/payment-sessions/buttons \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{
    "amount_reference": 50,
    "currency_reference": "USD",
    "identifier_label": "Pedido",
    "identifier": "ORD-0001",
    "description": "Compra en mi tienda",
    "success_url": "https://miapp.com/pago-exitoso",
    "failure_url": "https://miapp.com/pago-fallido",
    "agreement_id": "<agreement_id>",
    "webhook_url": "https://miapp.com/webhooks/spidi"
  }'

Campos obligatorios: amount_reference, currency_reference, identifier_label, identifier, description, success_url, failure_url, agreement_id. La respuesta trae payment_url y data.status: pending.

2. Lleva a la persona al pago​

<a href="<payment_url>" class="btn-spidi">Pagar con SPIDI</a>

Al terminar, SPIDI la redirige a tu success_url (o failure_url).

3. Confirma desde tu backend​

No confíes en la redirección

Volver a success_url no garantiza el pago. Confírmalo con GET status o por el webhook. → Success URL: verificar status.

curl https://sim-productos.abiertolab.com/api/v1/ext/payment-sessions/status/<session_id> \
  -H "Authorization: Bearer <token>"     # -> { "data": { "status": "paid" } }

4. Procesa el aviso (webhook)​

Al pagar, llega payment_session.paid a tu webhook_url (firmado). Verifícalo y responde 2xx. → Manejar notificaciones.

paid no es el dinero acreditado

paid confirma el débito (leg 1) — no que el dinero ya está en manos del beneficiario. La acreditación (leg 2) llega solo por webhook (payment_session.accredited) y no cambia el status. → Transacción a dos tiempos.

Botón para App (móvil)​

Si integras desde una app móvil, abres la misma payment_url desde la app: por deeplink al navegador (con retorno a tu app mediante las success_url/failure_url) o dentro de un WebView. La confirmación (consultar status + webhook) es idéntica a la del Botón web.

Por confirmar con SPIDI

El detalle del retorno a la app (esquema de deeplink, manejo del WebView) proviene de la documentación previa de SPIDI y está por confirmar contra la implementación vigente.

Reglas del Botón​

  • Vigencia: una sesión de Botón expira a los ~10 minutos de creada si no se paga.
  • Horario: no se permiten operaciones en las horas cercanas a la medianoche (ventana de corte diario).
  • Monedas de referencia (currency_reference): dólar (BCV), euro (BCV), peso colombiano y USDT, cada una con su tasa correspondiente.
Por confirmar con SPIDI

Estas reglas provienen de la documentación previa de SPIDI; los valores exactos (minutos de expiración, ventana de medianoche, lista de monedas y su tasa) deben confirmarse con SPIDI antes de asumirlos en producción.

Probar sin pago real​

En el simulador, fuerza el desenlace en vez de pagar a mano:

curl -X POST https://sim-productos.abiertolab.com/control/sessions/<session_id>/outcome \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"leg":1,"outcome":"paid"}'

→ Usar el simulador