El contrato del SDK y sus errores
Estas cinco reglas valen igual en las cuatro plataformas, y son la causa de casi todos los rechazos evitables. Si tu integración falla y no sabes por qué, empieza por aquí.
1 · El instrumento es el teléfono, no un nombre de método
El campo del instrumento espera el número de teléfono del pagador, con su prefijo: 04121234567.
No es el nombre de un medio de pago. Enviar ahí una etiqueta —como el nombre de un método— hace que la operación falle.
2 · Los montos van con coma y sin separador de miles
Hay dos funciones de formateo y confundirlas es la causa más común de un monto rechazado:
| Función | Para qué | Con 1234.5 produce |
|---|---|---|
formatBsAmount | Enviar a la API | 1234,50 |
formatAmount | Mostrar en pantalla | 1.234,50 |
La API rechaza el separador de miles. Usa los constructores y las funciones del SDK en lugar de armar las cadenas a mano.
3 · El banco tiene dos identificadores, y no son intercambiables
bank.code— el código bancario nacional de cuatro dígitos. Va al crear la transacción.bank.id— el UUID de SPIDI. Va al guardar la sesión y en la confirmación.
Cruzarlos produce rechazos del banco sin razón aparente: el mensaje no te dice que el problema es el identificador. Si el banco rechaza y no entiendes por qué, esto es lo primero que hay que mirar.
4 · Persiste antes de confirmar
Arma el bloque de la transacción y guárdalo en la sesión antes de confirmar el débito.
Si la confirmación se pierde, eso es lo único que deja rastro. Guardar después no sirve: el momento de riesgo es exactamente el que queda sin registrar.
5 · Valida y sanea antes de gastar una petición
El SDK trae las mismas reglas que aplica el checkout de SPIDI, con los límites de cada campo. Los mensajes de validación son personalizables; los que no definas quedan en los de SPIDI.
| Campo | Acepta | Máximo |
|---|---|---|
| Cédula | Solo dígitos | 9 |
| Teléfono | Solo dígitos | 7 |
| Clave de pago | Solo dígitos | 8 |
Errores y cómo responder
Los errores traen un mensaje redactado para mostrárselo al pagador y un código estable con el que decides en tu código. Los que más aparecen:
| Situación | Qué hacer |
|---|---|
| La sesión expiró o no existe | Pídele a tu backend una sesión nueva |
| La identificación no es válida | Resalta el campo de la cédula y deja que corrija |
| El banco no está disponible | Sugiere otro banco de la lista |
| Tiempo de espera agotado o error de red | Consulta el estado. No reintentes la confirmación |
| El banco rechaza sin razón clara | Revisa si cruzaste bank.code con bank.id |
| La API rechaza el monto | Usaste formatAmount en lugar de formatBsAmount |
| Falta un campo en la transacción | Hay campos obligatorios aunque vayan vacíos: revisa que estén todos |
| El monto en cripto está por debajo del mínimo | Sube el monto o cambia a débito inmediato |
El motivo casi siempre es el mismo: la cédula y el teléfono no corresponden al titular en ese banco. Es un dato del pagador, no un fallo de tu integración — díselo con esas palabras y deja que lo corrija.
Cada guía de instalación trae además la tabla de problemas frecuentes de su plataforma.