Métodos de pago y qué pasa del otro lado
Qué métodos de pago aceptas lo decides en el acuerdo de liquidación, no en cada sesión. Así, todas las sesiones creadas sobre ese acuerdo heredan los mismos métodos.
Qué Pasa del Otro Lado
Tú diseñas hasta el clic. Lo que viene después no lo controlas — pero conviene que lo conozcas, porque es lo que tu cliente te va a preguntar.
Tu cliente no se registra en SPIDI ni instala nada. Abre el enlace, paga, y se acabó. No hay cuenta que crear, ni aplicación que bajar, ni contraseña que recordar. La cuenta en SPIDI la necesitas tú, no él.
Paga desde su banco, sin darse de alta en nada. Lo que sí existe es una lista de bancos admitidos —la misma para Débito Inmediato y Pago Móvil—: tu cliente no tiene que habilitar ni registrar nada, pero el banco desde el que paga tiene que estar en ella. → Límites y reglas de operación
Si paga en cripto, tú sigues recibiendo bolívares. La conversión ocurre por debajo y no cambia nada de tu lado.
Y si repartes el pago, él no se entera. Ve un solo monto y paga una vez; el reparto ocurre después, entre el banco y los receptores. → Split
Lo único que le piden aparte del monto es una clave — y esa clave no es de SPIDI. Es de su banco, y es lo que más soporte te va a ahorrar saber. Está justo abajo.
Dónde Se Configuran
En el campo payment_methods del acuerdo:
"payment_methods": {
"immediate_debit": true,
"mobile_payment": true,
"crypto": false
}
| Método | payment_methods | Qué es |
|---|---|---|
| Débito Inmediato | immediate_debit | Pago directo desde cuenta bancaria. El método por defecto |
| Pago Móvil | mobile_payment | El camino cuando la clave de pago no llega |
| Cripto | crypto | Método adicional. Se liquida en bolívares igual |
No son tres alternativas equivalentes, y el orden importa. Débito Inmediato es el camino por defecto y el primero que ve quien paga, porque es la mejor experiencia. Pago Móvil aparece cuando la clave de pago no llega — es la salida, no un igual. Y Cripto es un método adicional. Siempre enrutamos al método más simple que esté disponible.
Qué Ve Quien Paga
Los tres métodos conviven en una sola página de pago: quien paga elige ahí, no tú por él. Lo que cambia entre ellos es lo que se le pide.
Pago Móvil: la Clave de Pago No Es de SPIDI, Es de Su Banco
Es el punto donde más gente se atasca, y conviene que lo sepas aunque no lo programes tú: la clave de pago (OTP) la emite el banco del pagador, no SPIDI. Nosotros no la generamos, no la validamos y no podemos reenviarla.
Cómo la consigue quien paga, según su banco:
- Por SMS, enviando una palabra clave al número de su banco.
- Desde la app de su banco.
Es un código de 6 a 8 dígitos y tiene vida corta. La página de pago de SPIDI le guía en el proceso, pero la clave sale siempre de su banco.
Es la causa número uno de "el pago no me funciona" en el canal de soporte. Cuando tu cliente te escriba porque no le llega la clave, la respuesta no está en tu código ni en SPIDI: tiene que pedírsela a su banco. Saberlo te ahorra escalar un caso que no es tuyo.
Cripto: Tu Cliente Paga en Cripto, Tú Recibes Bolívares
No gestionas monederos, ni claves, ni conversión. Quien paga elige cripto en la página, y a ti se te liquida en bolívares igual que con cualquier otro método. Para tu integración no cambia nada: el mismo acuerdo, la misma sesión, los mismos webhooks.
Y no hace falta un acuerdo aparte. Con crypto: true en el mismo acuerdo, cada sesión puede pagarse en bolívares o en cripto sin que tú decidas cuál: lo elige quien paga, en la página.
La Tasa Se Fija al Crear la Sesión, No al Pagar
El monto que vas a recibir lo declaras en una moneda de referencia —currency_reference—, y SPIDI lo convierte a bolívares con la tasa vigente en el momento de crear la sesión. Si tu cliente paga veinte minutos después y la tasa se movió, a ti se te liquida con la que se fijó al principio.
Las monedas admitidas son cinco: USD, EUR, COP, USDT y VES. Cualquier otra devuelve 400.
Para USD y EUR es la tasa oficial del Banco Central de Venezuela; la respuesta la devuelve como bcv_rate_usd_ves y bcv_rate_eur_ves. Para COP y USDT viene en rate_col_ves y rate_usdt_ves. No la fija SPIDI y no se negocia.
Qué Te Devuelve un Pago en Cripto
Cuando el pago fue en cripto, GET /api/v1/ext/payment-sessions/status/<session_id> trae dentro de session_payment un bloque crypto_details. Si el pago fue por cualquier otro método, ese bloque viene null — y eso, no un campo aparte, es cómo distingues uno de otro.
| Campo | Qué trae |
|---|---|
provider_name | Dónde tenía el saldo quien pagó — Binance o Crixto |
payment_method_name | Por dónde entró — Binance Pay, Crixto Pay |
crypto_order_id | El identificador de la orden del proveedor, no de SPIDI. Es el que te van a pedir si algo falla |
currency_crypto | La cripto con la que se pagó. Hoy solo USDT |
amount_pay_by_user_crypto | Lo que pagó tu cliente en cripto. Puede no coincidir con el monto original: el proveedor puede aplicarle su propia comisión a él |
amount_transaction_ves | El monto en bolívares antes de la comisión del banco |
exchange_rate | La tasa cripto/fiat que se usó, con cuatro decimales |
paid_at | Cuándo confirmó el proveedor, en ISO 8601 |
El que guardas es crypto_order_id. Los demás son para tu conciliación o tu recibo; ese es el que abre un caso.
Es la confusión que más soporte cuesta de este método, y no la resuelve tu código.
El QR que muestra la página de pago es un deep link: está hecho para que el lector de QR normal de la cámara del teléfono lo abra y salte a la aplicación de la billetera. Si tu cliente lo escanea desde el escáner que Binance trae dentro, le sale «Código inválido» — y va a pensar que el pago está roto.
Si pones instrucciones en tu propio checkout, esa es la frase que ahorra el ticket: escanéalo con la cámara del teléfono.
Si el Pago Se Atasca del Lado del Proveedor
No lo puedes resolver por API: no hay endpoint que reintente ni que cancele una orden cripto. Se escala a SPIDI por soporte, y lo que piden es el crypto_order_id y la captura del pago hecho en la billetera. Por eso conviene que lo guardes aunque no lo uses para nada más.
Puedes crear el acuerdo con crypto: true y sesiones con cualquier moneda de referencia, y el ciclo entero funciona — pero el simulador recorre siempre la vía bancaria: crypto_details vuelve null y no se aplica ninguna tasa. → Conducir el ciclo
Cómo Responde SPIDI
Independientemente del método que use el pagador, a ti te liquidan en bolívares según tu acuerdo (respaldo de Banco Sofitasa). El método elegido por el cliente no cambia tu flujo de integración: la sesión recorre el mismo ciclo de vida y dispara los mismos webhooks.
Los límites exactos por método, la disponibilidad por banco y el comportamiento preciso de la respuesta los estamos documentando. Lo que ves aquí es el modelo de configuración, que es estable y no va a cambiar.