Infraestructura de tarjetas embebidas: Sparados Full API
La API completa de Sparados (Sparados Full API) está diseñada para empresas que desean emitir y gestionar tarjetas directamente desde sus propios sistemas, sin utilizar las interfaces web o móviles de Sparados como capa operativa principal. En este modelo, el socio es responsable de la interfaz de usuario (frontend), la lógica de negocio, la experiencia de usuario (UX), la comunicación con el cliente, el flujo de autenticación 3DS y la gestión de eventos de transacciones. Sparados proporciona la capa de la API encargada de la creación de usuarios, la generación de autorizaciones, la emisión automática de tarjetas, la configuración de límites, la entrega segura de datos sensibles de la tarjeta mediante JWE, los webhooks y los datos transaccionales.
Índice de contenidos:
Arquitectura central y modelo de objetos
La arquitectura de la API completa se basa en varios objetos principales: usuario, autorización, tarjeta y saldo.
Usuario (user): Representa al usuario final para quien se emitirá la tarjeta.
Autorización (approval): Es un objeto técnico y de negocio que vincula al usuario con la tarjeta, el presupuesto disponible, el periodo de validez y las reglas de uso.
Tarjeta (card): Representa el instrumento de pago virtual.
Saldo (balance): Representa la fuente de financiación utilizada por la tarjeta.
En la práctica, la integración consiste en crear un usuario, generar una autorización para dicho usuario, esperar a que la autorización cambie al estado DELIVERED (entregada), almacenar el identificador de tarjeta (cardId) devuelto y, posteriormente, gestionar el ciclo de vida de la tarjeta a través de la API.
Paso 1: Creación del usuario
El primer paso consiste en realizar una llamada a POST /secure/users/. El sistema del socio envía los datos del usuario, tales como correo electrónico (email), teléfono (phone), nombre (firstName), apellidos (lastName), fecha de nacimiento (dateOfBirth) y nacionalidad (nationality). La API devuelve un identificador de usuario que se utilizará más adelante al crear la autorización. Este paso es obligatorio debido a que, en el modelo de API completa, la tarjeta no se crea únicamente con una dirección de correo o un número de teléfono; es indispensable que la tarjeta esté vinculada a un registro de usuario existente en Sparados.
Paso 2: Creación de la autorización y consulta (polling)
El segundo paso es la creación de una autorización mediante POST /secure/approvals. El cuerpo de la petición contiene, entre otros campos, user.id, balance.id, divisa (currency), amountMinor, validFrom, validTo, zona horaria (timezone), la configuración de comercio electrónico (e-commerce) y los límites opcionales de la tarjeta.
Nota técnica sobre importes: El campo amountMinor se envía siempre en unidades menores (céntimos). Por tanto, un importe de 100 EUR debe enviarse como 10000, y 99.99 EUR como 9999.
Las fechas deben transmitirse en formato ISO 8601. Este punto de conexión (endpoint) da inicio al proceso de emisión de la tarjeta. Una vez creada la autorización, el sistema del socio debe consultar periódicamente (polling) el endpoint GET /secure/approvals/{approvalId} hasta que la autorización alcance el estado DELIVERED y devuelva el cardId.
Gestión de los estados de la autorización
Los estados de la autorización son fundamentales para la correcta implementación del flujo. Recibir una respuesta satisfactoria del endpoint de creación no significa que la tarjeta esté lista para ser utilizada. En un flujo típico, la autorización pasa primero por el estado ACCEPTED (aceptada) y luego a DELIVERED (entregada). Únicamente el estado DELIVERED indica que la tarjeta ha sido generada y está disponible para operaciones posteriores. El sistema del socio debe tratar este proceso de forma asíncrona y no asumir que el cardId estará disponible inmediatamente después de la primera respuesta de POST /secure/approvals.
Distinción entre los identificadores de saldo
Un detalle de implementación crítico es la diferencia entre balance.id y balanceId.
balance.id (utilizado al crear la autorización): es el identificador de alias de la tarjeta (Card Alias ID) asignado a la fuente de financiación.
balanceId (utilizado en GET /secure/balances/{balanceId}): es un identificador distinto proporcionado por Sparados.
Confundir estos valores es una fuente común de errores de integración, especialmente cuando el socio gestiona múltiples divisas, cuentas o programas de tarjetas dentro de un mismo sistema.
Límites de la tarjeta y gestión dinámica del presupuesto
Los límites de la tarjeta se configuran a nivel de autorización. El socio puede definir el presupuesto principal de la tarjeta, su periodo de validez y límites periódicos adicionales. La API completa también permite modificar el presupuesto disponible de la tarjeta después de haber sido emitida. Para reducir el presupuesto disponible, se debe enviar un valor negativo. Esto permite al sistema del socio ajustar el saldo de la tarjeta de forma dinámica en función de su propia lógica de negocio (por ejemplo, el estado de una reclamación, un coste aprobado, el valor de un pedido, el saldo del cliente o la decisión de un operador).
Seguridad de datos sensibles de la tarjeta mediante JWE
Los datos sensibles de la tarjeta se obtienen a través del endpoint específico de datos sensibles, el cual devuelve la información cifrada mediante JWE (JSON Web Encryption). El socio debe enviar una cabecera Public-Key que contenga una clave pública RSA codificada en base64 en formato SPKI PEM. Sparados cifra la respuesta utilizando los algoritmos RSA-OAEP-256 y A256GCM. La respuesta solo puede ser descifrada con la clave privada correspondiente.
El modelo recomendado consiste en generar el par de claves en el lado del cliente o en otra capa de la aplicación que sea segura y de confianza, enviar únicamente la clave pública a Sparados y descifrar el JWE fuera de la capa del backend. De este modo, se evita que el backend registre, almacene o procese el PAN (número de tarjeta), CVV o fecha de caducidad en texto plano.
Cumplimiento de PCI DSS y seguridad en el backend
Esta es la sección más crítica de la integración en términos de seguridad. La API completa otorga la capacidad técnica de recuperar los datos de la tarjeta, pero corresponde al socio decidir dónde se descifran, si se almacenan, si aparecen en los registros (logs), si pasan por el backend y qué parte de su entorno queda bajo el alcance de la normativa PCI DSS. El uso de JWE no exime automáticamente al socio de sus obligaciones de seguridad de datos de tarjetas. Si el backend del socio tiene acceso a los datos de la tarjeta en texto plano, dicho backend deberá ser considerado parte del entorno de datos de tarjetas (CDE - Card Data Environment).
Más información sobre PCI DSS: Desentrañando el PCI DSS: cómo elegir tu ruta de integración con Sparados
Seguridad en el transporte mediante mTLS
La comunicación de servidor a servidor (server-to-server) está protegida por TLS mutuo (mTLS). El cliente de la API debe utilizar un certificado de cliente, garantizando que la conexión TLS se autentique en ambos extremos. En la práctica, esto requiere que el socio configure correctamente los certificados en su entorno de backend, separe los certificados de prueba de los de producción y gestione la rotación de estos. Aunque esto añade complejidad a la implementación, es el modelo idóneo para las API financieras, donde un token de API estático no ofrecería un nivel de control de acceso suficiente.
Arquitectura de webhooks: 3DS y carteras digitales
La API completa utiliza webhooks para notificar eventos asíncronos:
Webhook de 3DS: Permite a Sparados enviar al socio los datos necesarios para gestionar la autenticación de transacciones de comercio electrónico, incluyendo el código de un solo uso (OTP), amountMinor, currency, merchantName, cardId, userId y los últimos cuatro dígitos de la tarjeta. Esto faculta al socio para hacer llegar el mensaje de autenticación al usuario a través de sus propios canales, como SMS, correo electrónico, notificaciones push o mensajería dentro de la aplicación.
Webhook de carteras digitales (wallets): Informa al socio sobre los eventos relacionados con la tokenización en Apple Pay y Google Pay, tales como la entrega del código de activación, la activación del token o la eliminación de la tarjeta de la cartera digital.
Buenas prácticas de webhooks e idempotencia
Los endpoints de webhooks en el lado del socio deben ser idempotentes. Es posible que el mismo evento se entregue más de una vez, por lo que el sistema no debe ejecutar operaciones irreversibles por el único hecho de haber recibido una petición. Una implementación adecuada debe contemplar reintentos, tiempos de espera (timeouts), validación del origen de la petición, respuestas HTTP rápidas y el procesamiento asíncrono de las operaciones de negocio. El webhook no debe bloquearse a la espera de flujos de trabajo internos de larga duración.
Gestión de transacciones y mapeo de recursos
Las transacciones se gestionan a través de la API de Transacciones. El socio puede consultar los datos de las transacciones y recibir eventos para mapear los pagos con tarjeta con sus propios objetos de negocio. Dependiendo del caso de uso, este objeto puede ser un caso de asistencia, un gasto de empleado, una reclamación, un pedido, una reserva o un pago, entre otros.
Desde la perspectiva de la integración, es fundamental almacenar la relación entre el userId, approvalId, cardId, balanceId y el identificador de negocio propio del socio. Sin este mapeo, los procesos de conciliación y la gestión de disputas se vuelven innecesariamente complejos.
Análisis arquitectónico: Ventajas y desventajas
Ventajas | Desventajas |
• Control total sobre el frontend y la experiencia de usuario (UX). • Sin necesidad de redirigir a los usuarios a interfaces externas. • Emisión automática de tarjetas mediante API. • Límites programables y gestión dinámica del presupuesto. • Entrega segura de datos sensibles cifrados (JWE). • Webhooks para la gestión de 3DS y carteras digitales. • Máxima seguridad en el transporte basada en mTLS. | • Mayor complejidad técnica y arquitectónica. • Gestión obligatoria de certificados de cliente. • Diseño complejo de webhooks y lógica de idempotencia. • Dependencia estricta de un mapeo personalizado de identificadores. • Consideraciones rigurosas respecto al cumplimiento de PCI DSS. • Necesidad de desarrollar una interfaz propia para mostrar los datos de la tarjeta. • Obligación por parte del socio de mantener la lógica de reintentos, estados y conciliación. |
Casos de uso idóneos para el modelo de API completa
La API completa es el modelo adecuado cuando se requiere que la tarjeta forme parte de un producto existente y no como un flujo independiente gestionado en un panel externo. Funciona de manera óptima en sistemas que ya disponen de sus propios usuarios, flujos de autorización, interfaces de usuario y lógica de negocio. En esta configuración, Sparados actúa exclusivamente como la capa de API de emisión, mientras que el socio retiene el control absoluto sobre la aplicación, la comunicación con el usuario y el proceso operativo.
