Saltar al contenido principal

Botones de Pago

¿Qué son los botones de pago SPIDI?​

Los Botones de Pago SPIDI son la forma más directa de recibir pagos inmediatos desde tu sitio web o aplicación móvil, permitiendo que tus usuarios paguen desde cualquier banco venezolano o de Binance Pay (USDT) sin salir de alli.

El botón SPIDI te permite habilitar todos los medios de pago inmediatos del país —débito bancario, Pago Móvil y Binance Pay (USDT)—, con liquidación directa en bolívares.

Tipos de botones de pago​

Los botones pueden integrarse en dos modalidades, según el entorno en el que desees implementarlos:

  • 🖥️ Botón SPIDI para Web: para sitios o aplicaciones web, donde el pago ocurre directamente en el navegador.

  • 📱 Botón SPIDI para App: pensado para aplicaciones móviles (Android, iOS o frameworks híbridos), con soporte para deeplinks o navegación WebView.

Base común de todos los flujos de Botones de pago​

  • 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 estado inicial (status) del enlace es pending.

  • La sesión tiene una vida útil de 10 minutos, tras lo cual caduca automáticamente si no se completa el pago.

  • Los posibles estados de una sesión son: pending, paid, failed, expired.

    • Un estado failed termina definitivamente la sesión de pago.

  • El pago siempre ocurre el mismo día; en horas cercanas a la medianoche no se permiten operaciones, para garantizar la correcta conciliación entre sistemas bancarios.

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

  • 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.

  • Un segundo endpoint permite consultar el estado de la 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 Móvil o pago con criptomonedas (Binance Pay), todas con liquidación directa en bolívares.

Resumen de endpoints​

Ambas modalidades utilizan los mismos endpoints base del API:

  • Crear sesión de pago (B): genera la sesión y devuelve el payment_url.

  • Consultar sesión de pago (B): permite verificar el estado y resultado de la transacción (pending, paid, failed, expired).

SPIDI se encarga del resto: conexión bancaria, validación, liquidación y notificación, garantizando confirmaciones inmediatas y trazabilidad completa.

Botón SPIDI para Web​

El Botón SPIDI para Web permite integrar pagos inmediatos en cualquier sitio o aplicación web, ofreciendo a tus usuarios una experiencia de pago fluida, segura y dentro del navegador.
Dependiendo de cómo desees abrir la página de pago de SPIDI, existen dos estrategias posibles de integración.

Estrategia 1 — Misma pestaña (recomendada)​

Flujo​

Tu aplicación web → SPIDI (misma pestaña) → Redirección automática a tu web (éxito o fallo)

Pasos​

  1. El usuario hace clic en el botón de pago en tu web.

  2. Tu backend crea una sesión de pago con SPIDI mediante el endpoint de creación, incluyendo:

    • success_url: URL de éxito (obligatoria)

    • failure_url: URL de error (obligatoria)

    • webhook_url: opcional, pero altamente recomendado

  3. SPIDI responde con un session_id.

  4. Tu frontend construye el payment_url → {url_base}/{session_id}.

  5. Rediriges al usuario con window.location.href para abrir SPIDI en la misma pestaña.

  6. Una vez completado el intento de pago, SPIDI redirige automáticamente al success_url o failure_url, concatenando el parámetro session_id.

    • Ejemplo:

      • {success_url}?session_id=sess_abc123

      • {failure_url}?session_id=sess_abc123

  7. Tu aplicación debe leer el session_id desde la URL y consultar el endpoint de estado de sesión para validar el resultado.
    Nunca asumas que llegar al success_url implica un pago exitoso; siempre valida con el endpoint.

  8. Si implementaste un webhook, también recibirás la notificación en tu API.

Consideraciones técnicas​

  • SPIDI solo agrega el parámetro session_id en la redirección.

  • No incluye estado ni información sensible.

  • Los estados posibles son: pending, paid, failed, expired.

Nota estratégica — Comprobante y fidelización​

Al consultar el estado de una sesión mediante el endpoint de status, SPIDI devuelve también una URL única del comprobante de pago.
Se recomienda mostrar este enlace al usuario desde tu aplicación:

  • Mejora la transparencia y la confianza.

  • En el comprobante, SPIDI invita al usuario a registrarse, lo que:

    • Mejora su experiencia en futuros pagos.

    • Reduce las comisiones que SPIDI le cobra a tu aplicación.

    • Establece una relación directa SPIDI–usuario, facilitando futuros cobros.

Incluir el comprobante es una buena práctica que mejora la UX y reduce costos operativos a mediano plazo.

Estrategia 2 — Nueva pestaña (casos especiales)​

Flujo​

Tu aplicación web → Nueva pestaña con SPIDI → El usuario cierra la pestaña → Regresa manualmente a tu web

Cuándo usarla​

Solo en casos donde necesites mostrar el pago en una pestaña separada por razones de experiencia de usuario o restricciones técnicas del navegador.

Pasos​

  1. El usuario hace clic en el botón de pago.

  2. Tu backend crea la sesión de pago con SPIDI, incluyendo únicamente:

    • webhook_url (opcional, pero recomendado).

    • success_url y failure_url deben quedar vacíos.

  3. SPIDI responde con el session_id.

  4. Tu frontend construye el payment_url → {url_base}/{session_id}.

  5. Pides al usuario abrir el enlace en una nueva pestaña.

  6. El pago se realiza en la página de SPIDI.

  7. Al finalizar, el usuario cierra la pestaña manualmente y vuelve a la pestaña original.

  8. Tu aplicación puede:

    • Consultar periódicamente el estado de la sesión.

    • Mostrar un botón “Ya pagué” para disparar la verificación.

    • Usar el webhook para recibir la confirmación en backend.

Nota estratégica — Comprobante y fidelización​

Al igual que en la estrategia 1, el endpoint de status devuelve la URL del comprobante de pago SPIDI.
Mostrar este comprobante en tu interfaz genera confianza y reduce costos a largo plazo al incentivar el registro del usuario en SPIDI.

Botón SPIDI para App​

El Botón SPIDI para App permite integrar pagos inmediatos dentro de aplicaciones móviles (Android, iOS o frameworks híbridos) mediante deeplinks o navegación WebView, manteniendo la experiencia del usuario dentro del entorno de tu app.

Integración para Aplicaciones Móviles​

Cuando tu app abre la página de pago de SPIDI dentro de un WebView, existen dos estrategias posibles para recuperar el control una vez que el usuario finaliza (o cancela) el pago.

Estrategia 1 — Uso de deeplink (recomendada)​

Flujo​

Tu App móvil → SPIDI (WebView) → Redirección automática a tu app (éxito o fallo)

Pasos​

  1. El usuario hace clic en el botón de pago dentro de tu app.

  2. Tu backend crea una sesión de pago con SPIDI, incluyendo:

    • success_url: tu deeplink de éxito (por ejemplo, miapp://pago-exitoso)

    • failure_url: tu deeplink de error (por ejemplo, miapp://pago-fallido)

    • webhook_url: opcional, pero altamente recomendado

  3. SPIDI responde con el session_id y el payment_url ({url_base}/{session_id}).

  4. Abres el payment_url dentro de un WebView moderno (por ejemplo, WKWebView o Chrome Custom Tabs).

  5. Una vez el usuario completa o cancela el pago, SPIDI redirige al success_url o failure_url, concatenando el parámetro session_id:

    • miapp://pago-exitoso?session_id=sess_abc123

    • miapp://pago-fallido?session_id=sess_abc123

  6. Tu app intercepta el deeplink y abre la pantalla nativa correspondiente.

  7. Con el session_id, consulta el endpoint de estado para verificar el resultado (pending, paid, failed, expired).

  8. Si configuraste un webhook, también recibirás la notificación automática en tu API.

Ventajas​

  • No requiere lógica adicional para interceptar URLs.

  • El sistema operativo detecta automáticamente el esquema (miapp://) y abre tu app.

  • Es la forma más limpia y segura de retornar al flujo original.

Estrategia 2 — Captura del cambio de URL​

Flujo​

Tu App móvil → SPIDI (WebView) → Detección de cambio de URL → Cierre del WebView → Pantalla nativa (éxito o fallo)

Pasos​

  1. El usuario hace clic en el botón de pago.

  2. Tu backend crea una sesión de pago con SPIDI, incluyendo:

    • webhook_url: opcional, pero altamente recomendado.

    • success_url y failure_url: pueden dejarse vacíos.

  3. SPIDI responde con el session_id.

  4. Tu app construye el payment_url → {url_base}/{session_id} y lo abre en el WebView.

  5. Cuando el pago termina, la URL dentro del WebView cambia hacia una página de resultado de SPIDI.

  6. Tu app debe:

    • Detectar el cambio de URL dentro del WebView.

    • Cerrar el WebView desde tu código.

    • Mostrar la pantalla nativa correspondiente (éxito o fallo).

  7. Tu app conserva el session_id y consulta el endpoint de estado para validar el resultado.

  8. Si configuraste un webhook, también recibirás la notificación en tu backend.

Ventajas y consideraciones​

  • Útil cuando no puedes registrar un esquema personalizado.

  • Requiere lógica en el WebView para analizar URLs entrantes.

  • Asegúrate de usar componentes modernos como WKWebView, Chrome Custom Tabs o equivalentes en React Native, Flutter o Capacitor.

Nota técnica sobre WebView​

SPIDI requiere que el WebView soporte:

  • Interceptar cambios de URL.

  • Ejecutar JavaScript.

  • Estar actualizado con soporte de seguridad moderno.

Ejemplos recomendados:

  • iOS: WKWebView

  • Android: Chrome Custom Tabs

  • React Native / Flutter / Capacitor: WebView con interceptores de URL activos

Nota estratégica — Comprobante de pago y fidelización​

Al consultar el estado de una sesión mediante el endpoint de status, SPIDI devuelve también una URL única del comprobante de pago.
Mostrar este comprobante en tu app tiene beneficios clave:

  • Mejora la transparencia y la confianza del usuario.

  • En la página del comprobante, SPIDI invita al usuario a registrarse, lo que:

    • Facilita sus futuros pagos.

    • Reduce las comisiones que SPIDI le cobra a tu aplicación.

    • Establece una relación directa SPIDI–usuario, facilitando cobros posteriores.

💡 Consejo: Mostrar el comprobante desde tu app no solo mejora la experiencia del usuario, sino que también reduce costos operativos a mediano plazo.