El SDK: pagar dentro de tu aplicación
Con la API de Productos, tu cliente sale de tu aplicación: le entregas un enlace y paga en la página de SPIDI. Con el SDK, no sale: paga dentro de tu propia pantalla, y tú diseñas esa pantalla.
Es la misma plataforma y el mismo dinero. Cambia dónde ocurre el momento del pago.
El problema que resuelve, que es de abandono
Cuando el pago salta a otra pantalla —un navegador, una pestaña nueva, una página que no se parece a tu aplicación— una parte del público se pierde ahí. No por desconfianza: por cambio de contexto. La persona deja de reconocer dónde está, duda, y el pago no avanza.
Y ese efecto no es parejo. En operaciones de calle, transporte, comercio de barrio o atención rápida, el salto de pantalla cuesta mucho más que en un público habituado a comprar en línea. Si ese es tu caso, es probablemente la razón principal para mirar el SDK.
| El flujo no se rompe | El pagador nunca sale de tu aplicación ni ve una interfaz que no reconoce |
| La experiencia es tuya | Tus colores, tu tipografía, tus textos |
| Menos pasos, menos abandono | Desaparece la carga de una página externa y la espera que la acompaña |
| Un contrato, cuatro plataformas | Lo que aprendes en una te sirve en las otras tres |
Qué cubre y qué sigue siendo tuyo
Esta es la distinción que más conviene tener clara, porque decide cuánto trabajo es del SDK y cuánto de tu backend:
| El SDK se ocupa de | Tu backend sigue ocupándose de |
|---|---|
| Cargar una sesión de pago que ya existe | Autenticarse contra la API de SPIDI |
| Identificar a quien paga | Crear el acuerdo de liquidación |
| Confirmar el débito con la clave del SMS | Crear cada sesión de pago |
| Verificar el resultado | Consultar el estado y liberar el servicio |
Todo cuelga del session_id. Lo crea tu backend contra la API, exactamente como hoy; sin él, el SDK no tiene contexto. Es decir: el SDK no sustituye nada de lo que ya está en este portal — se apoya encima.
Una aplicación instalada en un teléfono es extraíble: cualquier credencial empaquetada ahí es, en la práctica, pública. Tu aplicación le pide el token a tu propio backend y se lo pasa al SDK.
No trae interfaz, y es a propósito
El SDK no te da una pantalla de pago hecha. Te da el cliente, los tipos, el formateo y la validación; la pantalla la haces tú, con tu identidad visual y dentro de tu flujo.
Eso es lo que resuelve: que quien paga no salte a otro sitio en el momento en que más se abandona una compra.
Las cuatro plataformas
| SDK | Entorno mínimo | Cómo se distribuye |
|---|---|---|
| Kotlin | Android (minSdk 21) · JVM 17 | Artifact Registry de Google Cloud, con rol de lectura sobre el repositorio Maven |
| React | React 18+ · TypeScript | Registro de npm, paquete privado de la organización @spidi |
| Swift | iOS 15+ · macOS 12+ | Swift Package Manager, desde el repositorio de Git |
| Go | Go 1.22+ | Módulo privado de Git, con llaves SSH y variable de entorno |
Las cuatro implementan el mismo contrato observable —formatos de monto, validación, códigos de error y la regla de que la confirmación no se reintenta—. Lo que cambia es la superficie opcional: React es el más completo (trae la máquina de estados entera, hooks, prop getters y eventos, y sirve igual para React Native); en Kotlin, Swift y Go la secuencia del flujo la orquesta tu aplicación.
Dónde se prueba
Contra el sandbox de SPIDI, que es donde vive tu integración hasta que la certifiques. No hay un simulador del débito: en el sandbox los desenlaces ocurren, no se fuerzan, así que los casos malos —un banco caído, una clave equivocada— se prevén en el código en vez de ensayarse.
→ Entornos y URLs, donde está el recorrido completo de los tres.
Cómo se consigue
Los cuatro paquetes son privados. No se instalan desde un registro público: el acceso se solicita a tu asesor de SPIDI, que habilita tu cuenta o tu llave. Las credenciales del sandbox llegan por el mismo camino.
Si un install falla, lo primero que hay que descartar es siempre lo mismo: que tu cuenta tenga el rol de lectura y que el token siga vigente.
No existe un simulador del débito, y lo que decide si el dinero se mueve no es el entorno al que apuntas: es de dónde salió la sesión. Hay tres reglas más que conviene saber antes de escribir, no después. → Antes de tocar dinero real