Introducción

Gracias por interesarte en integrar SPIDI a tu aplicación o plataforma. Aquí encontrarás todo lo que necesitas para empezar a recibir pagos de forma rápida, segura y simple, usando nuestra API.

Sabemos que cada producto es distinto, por eso diseñamos SPIDI para adaptarse a distintos tipos de integración. En esta guía te explicamos las formas principales de integrar y recibir pagos con SPIDI, sus flujos técnicos y cómo monitorear cada transacción de manera eficiente.

Tanto si estás desarrollando una app, un sitio web o simplemente necesitas compartir un enlace de pago, esta documentación está pensada para acompañarte paso a paso en ese proceso.

¿Cómo integrar Pagos con SPIDI?

SPIDI ofrece dos formas diferentes de integrar y recibir pagos. Cada una tiene particularidades en el flujo, el retorno del usuario y la forma de monitorear el estado del pago.

Botones de Pago SPIDI

Ideales cuando deseas que tus usuarios puedan realizar pagos directamente en tu sitio web o aplicación móvil, sin salir de alli.

Solicitudes de Pago SPIDI

Son la solución ideal para generar enlaces que puedes compartir por email, WhatsApp, SMS u otros canales para recibir pagos. Estos enlaces ya están preconfigurados con el monto e identificación, lo que simplifica la experiencia del pagador y permite recibir pagos organizados y trazables, conforme a la planificación de tu operación.

Todas las soluciones permiten crear de forma programada sesiones de pago y consultar sus resultados en tiempo real, reduciendo la intervención manual y minimizando errores operativos.

🧾 Base común de todos los flujos

• Todos los procesos se basan en la creación de una sesión de pago a través del API de SPIDI, especificando un monto (en bolívares o en una moneda de referencia como dólar BCV, euro BCV, peso colombiano o USDT) y una identificación que permite asociar la transacción con tu sistema de origen.

• Al crear la sesión, SPIDI genera un hash único que identifica de forma segura cada operación y el status del enlace es pending.

• En la respuesta se devuelve un payment_url, y deberás llevar al usuario que va a pagar a esa dirección para finalizar el proceso de pago.

• El pago siempre ocurre desde la página de SPIDI, donde el cliente verá una interfaz segura, clara y vinculada visualmente con tu aplicación.

• Una vez finalizado el pago, SPIDI puede redirigir automáticamente al usuario hacia la success_url o failure_url, en caso de haber sido configuradas.

• La API de SPIDI tambien permite consultar el estado de esa sesión de pago, conocer su resultado y opcionalmente sincronizarlo con tu plataforma mediante webhooks o consultas directas.

• Cada sesión puede asociarse a un acuerdo de liquidación, donde se definen las reglas personalizadas de liquidación, las cuentas destino y los splits específicos entre varios receptores.

• Puedes habilitar que la sesión ofrezca distintas opciones de pago inmediatas: débito bancario, pago con criptomonedas (Binance Pay) o Pago Móvil, todas con liquidación directa en bolívares (El comercio o usuario de SPIDI siempre recibe automáticamente el pago en Bolívares, sin importar si el cliente paga con su cuenta bancaria en Bs o con criptomonedas).

Diferencias entre Botón de Pago y Solicitud de Pago

Aunque ambos productos comparten la misma infraestructura y lógica de liquidación, presentan diferencias clave en su forma de integración, comportamiento y administración de sesiones.

Característica	Botón de Pago (SPIDI)	Solicitud de Pago (SPIDI)
🌐 Ubicación del payment_url	Generalmente se integra dentro del entorno de tu aplicación o sitio web.	No se embebe; se envía al cliente mediante canales externos (QR, correo, WhatsApp, SMS).
⏱️ Momento de creación de la sesión	La sesión se crea por API en el momento del clic del usuario.	La sesión se crea por API cuando se desee, de forma programada o manual.
⏳ Duración de la sesión	Corto: expira a los 10 minutos desde su creación.	Configurable: Puede tener fecha de vencimiento o nunca expirar. Si vence, puede mostrar mensaje personalizado.
💰 Momento y condiciones de pago	El pago siempre ocurre el mismo día. No se permiten operaciones cercanas a la medianoche.	El pago puede ocurrir cualquier día. Si la moneda base no es Bs., el monto se ajusta a la tasa BCV vigente al momento del acceso.
🔑 Referencia interna	No requiere una internal_reference para crear la sesión.	Requiere una internal_reference para asociar la sesión a una operación o cliente específico.
🚦 Estados posibles (status)	pending, paid, failed, expired. Un estado failed termina la sesión de pago.	pending, paid, expired. Un pago fallido no termina la sesión, por lo que no existe el estado failed.

Paradas SPIDI

En escenarios de suscripciones, pagos recurrentes o relaciones comerciales continuas, las Paradas SPIDI son el acompañante ideal de las Solicitudes de Pago.

Una Parada es una URL única y permanente asignada a cada cliente, desde la cual puede consultar, atender y pagar sus solicitudes activas o anteriores. Gracias a este mecanismo, el cliente no necesita recibir nuevos enlaces cada vez que se genera una solicitud: basta con acceder a su Parada para revisar o completar los pagos pendientes.

Desde una Parada, el cliente puede:

• Visualizar solicitudes pendientes, pagadas o vencidas.
• Pagar directamente, sin depender de nuevos envíos de enlace.
• Consultar su historial de pagos y operaciones anteriores.