Servicio para emisores con core propio que quieran usar nuestra tokenización manteniendo el control de datos sensibles y validaciones. Disponible solo para Visa.

Tokenización Standalone

Tokeniza tus tarjetas en Apple Pay y Google Pay manteniendo el control de los datos sensibles y las validaciones en tu propia plataforma.

Introducción

En el flujo de tokenización tradicional, nosotros administramos el ciclo de vida completo de la tarjeta: la información sensible vive en nuestros sistemas y nos encargamos de validarla cuando una billetera digital pide tokenizarla.

La tokenización standalone es una variante para clientes que ya tienen su propio sistema de tarjetas y prefieren mantener la fuente de verdad de sus tarjetas en su plataforma. En este modo:

Nosotros orquestamos la comunicación con la marca y las billeteras (Apple Pay, Google Pay).
Tu plataforma conserva el PAN, el CVV y la información operativa de la tarjeta.
Para cada operación que requiera datos sensibles, te enviamos un pedido cifrado y nos devuelves la información que necesitamos para tomar la decisión.

El servicio de tokenización se configura por BIN. Puedes tener BINs en modo tradicional y otros en modo standalone conviviendo dentro de la misma cuenta de Pomelo.

Beneficios

Beneficio	Descripción
Compatible con tu emisión	Suma tokenización sin migrar tu core de tarjetas. Tu plataforma sigue siendo la fuente de verdad del PAN y las reglas de uso; nosotros solo agregamos la capa de tokenización.
Una sola integración	Un único set de webhooks habilita Apple Pay, Google Pay y tokens de comercio (card-on-file). No necesitas integrarte por separado con cada marca ni con cada billetera.
Datos sensibles bajo tu control	El PAN y el CVV nunca salen de tu perímetro en texto plano. Toda la comunicación entre tu plataforma y nosotros viaja cifrada en JWE y firmada con HMAC.
Time-to-market	Nosotros ya estamos certificados con la marca y las billeteras. Ahorrarás tiempo en las certificaciones, las ceremonias de claves criptográficas y el mantenimiento contra cada actor del ecosistema.

Funcionamiento

A diferencia del flujo tradicional, en Tokenización Standalone nosotros te consultamos durante el momento clave de la tokenización. Para hacerlo posible, tendrás que exponer un conjunto chico de endpoints en tu plataforma y nosotros los invocamos como webhooks firmados.

Veamos el camino más común:

Tu cliente guarda su tarjeta en un comercio para futuras compras (un token de tipo MERCHANT o card-on-file). En este flujo tu app no participa — la tokenización la inicia el comercio contra la marca, y tu plataforma solo entra en juego cuando nosotros te consultamos.

Tu cliente ingresa los datos de su tarjeta en el checkout o sección de tarjetas guardadas de un comercio.
El comercio inicia la tokenización contra la marca Visa.
La marca identifica al emisor por el BIN y nos pide que procesemos la tokenización.
Identificamos que el BIN está en modo Tokenización Standalone, desciframos los datos y armamos un pedido de verificación.
Invocamos el webhook de verificación que expusiste. Te llegan el PAN y el CVV cifrados con tu clave pública (tú tienes que descifrarlos), más los metadatos del token requestor (en este caso, el comercio).
Tu plataforma chequea la tarjeta y nos devuelve la información que necesitamos para decidir: el estado de la tarjeta y los resultados de la validación de CVV y de fecha de expiración. Con esa información — y según el tipo de token (MERCHANT en este flujo) — aplicamos las reglas de la red y tomamos la decisión final.

Si la marca requiere step-up con OTP (como sucede para tokenizaciones manuales en billeteras como Google Pay y Apple Wallet), te notificamos por el webhook de lifecycle o disparamos el webhook de envío de OTP.

A medida que el token cambia de estado — por ejemplo, si tu cliente elimina su tarjeta del comercio — te avisamos por el webhook de lifecycle.

Toda la comunicación de webhooks viaja firmada con HMAC-SHA256, y los datos sensibles siempre viajan cifrados en JWE. Nunca exponemos PAN ni CVV en texto plano.

APIs que tienes que exponer

Para integrarte en modo Tokenización Standalone, necesitas exponer tres endpoints en tu plataforma. Nosotros los invocaremos a lo largo del flujo y tu plataforma debe responderlos a tiempo.

La conexión hacia tus endpoints se establece mediante mTLS (Mutual TLS). Puedes revisar el detalle del setup y el intercambio de certificados en nuestra documentación.

1. Webhook de verificación de tokenización

Lo invocamos cada vez que una billetera pide tokenizar una tarjeta cuyo BIN está configurado como Standalone. El endpoint no aprueba ni rechaza la operación: aporta la información que necesitamos para tomar la decisión evaluando, además, las reglas de la marca y el tipo de token.

Tu endpoint recibe:

request_id y correlation_id para trazabilidad.
encrypted_pan y encrypted_cvc: PAN y CVV cifrados como JWE con tu clave pública. Al descifrar obtienes el valor como string plano.
expiry_month y expiry_year.
token: metadatos del token requestor (requestor, type, provisioning_method, external_token_id).

Tu endpoint debe responder con:

card_status: estado de la tarjeta (ACTIVE, BLOCKED, DISABLED, NOT_FOUND).
cvv_validation_status y expiry_date_validation_status: VALID, NOT_VALID o NOT_CHECKED.
external_card_id: el identificador de la tarjeta en tu sistema.
phone_number y email: para que la billetera ofrezca métodos de activación (OTP) a tu cliente.
token_profile_id: identificador del perfil de token asociado.

Aplicamos reglas distintas sobre el resultado según el token.type. Por ejemplo, un token de tipo DEVICE (Apple/Google Pay) puede tolerar un cvv_validation_status con valor NOT_CHECKED cuando la marca ya validó el CVV en un paso previo. En cambio, un token de tipo MERCHANT (card-on-file de un comercio) requiere VALID para continuar. Por eso, es importante que reportes el estado real del intento de validación, sin asumir un default.

Si no puedes evaluar el pedido por un error transitorio, responde con un 5XX y reintentaremos. Cualquier respuesta no 2XX aborta la tokenización en curso.

2. Webhook de envío de OTP

Lo invocamos cuando Apple o Google activan el flujo de verificación adicional (yellow path) y la red genera un código OTP para confirmar la identidad del cliente.

Durante el flujo de la billetera, tu cliente elige el método por el que espera recibir el OTP (SMS o email). Tu endpoint recibe el OTP junto con el método seleccionado y los datos del token. Tú decides cómo entregárselo respetando esa elección:

Enviando el OTP directamente por el canal seleccionado (por ejemplo, un SMS desde tu shortcode bancario o un mail transaccional propio).
Enviando por ese mismo canal una comunicación que redirija a la app del banco emisor, donde el OTP se muestra al cliente ya autenticado. Así el OTP no viaja por el canal abierto, pero se respeta la opción que eligió.

Si prefieres no manejar el envío, también podemos enviarlo nosotros por el canal seleccionado, utilizando los métodos de contacto phone_number y email compartidos previamente en el webhook de verificación.

3. Webhook de cambios de estado del token

Este webhook es opcional: puedes suscribirte solo a las transiciones que te interesen y dejar el resto sin notificación. Te lo enviamos cada vez que un token cambia de estado a lo largo de su vida útil:

Estado	Descripción
`OTP_PENDING`	La marca pidió OTP, esperamos que tu cliente lo ingrese.
`OTP_SENT`	El OTP fue enviado al cliente.
`ACTIVATED`	El token quedó activo y se puede usar.
`SUSPENDED`	El token fue suspendido (temporal, reversible).
`DISABLED`	El token fue dado de baja definitivamente.

Las transiciones a las que te suscribes se acuerdan durante el onboarding y se pueden ajustar luego. Reintentamos hasta recibir una respuesta 2XX. Cualquier 4XX o 5XX provoca un reintento con backoff exponencial.

Ciclo de vida de tokens

Además de los webhooks, expondremos un conjunto de endpoints HTTP para que consultes y administres los tokens emitidos. Son útiles para reconciliación, soporte al cliente y reacciones a eventos que detectas del lado del emisor.

Hay dos formas de operar: a nivel token individual usando su external_token_id, o a nivel tarjeta usando su external_card_id.

Operaciones por token external_token_id

Cada token tiene un external_token_id que viaja en el webhook de verificación inicial y se mantiene estable a lo largo de toda la vida del token.

Endpoint	Acción
`POST /tokens/{external_token_id}/suspension`	Suspende un token activo. Queda inactivo hasta una reactivación explícita.
`POST /tokens/{external_token_id}/unsuspension`	Reactiva un token suspendido.
`POST /tokens/{external_token_id}/deletion`	Da de baja un token de manera definitiva.
`GET /tokens/{external_token_id}`	Devuelve el detalle del token (estado actual, billetera asociada, fecha de creación, último cambio).

Suspender, reactivar y deshabilitar tokens dispara automáticamente el webhook de lifecycle hacia tu plataforma, manteniendo ambos lados consistentes.

Operaciones por tarjeta external_card_id

Como una misma tarjeta puede tener múltiples tokens (por ejemplo, uno por dispositivo y otro por comercio), cuando requieras operar sobre todos los tokens de una tarjeta a la vez, usa el external_card_id informado en el webhook de verificación.

Endpoint	Acción
`GET /cards/{external_card_id}/tokens`	Lista todos los tokens emitidos para una tarjeta, con su estado actual. Útil para conocer en qué dispositivos y comercios se tokenizó una tarjeta.
`PATCH /tokens/cards/{external_card_id}`	Actualiza el estado de todos los tokens de una tarjeta a la vez. Pensado para reacciones masivas, por ejemplo deshabilitar todos los tokens cuando la tarjeta se reporta como robada.

Estas operaciones también disparan el webhook de lifecycle por cada token afectado.

Reemplazo de PAN

Cuando una tarjeta cambia de PAN (por renovación, reemplazo por fraude o cambio de producto), el cliente no necesita re-tokenizar desde cero. Usa POST /tokens/visa/card-replacements enviando el external_card_id junto con el encrypted_pan viejo y nuevo y sus fechas de expiración. Nosotros migramos los tokens activos al PAN nuevo manteniendo el external_card_id estable, lo que evita que tu cliente tenga que re-agregar la tarjeta en sus billeteras y comercios.

Cada token migrado dispara el webhook de lifecycle correspondiente.

Seguridad

Datos sensibles	El PAN y el CVV viajan siempre como tokens JWE cifrados con la clave pública de la contraparte. Ningún sistema intermedio puede leerlos.
Firma de webhooks	Cada request lleva firma HMAC-SHA256 sobre `timestamp + endpoint + body` en el header `X-Signature`. Valida la firma antes de procesar el pedido.
Timestamp	El header `X-Timestamp` te permite rechazar requests con firma vieja y prevenir replay attacks.
Identificación	El header `X-Api-Key` te permite resolver el api-secret correcto si tienes más de un par configurado.

Contratación

Si contratas Tokenización Standalone, tendremos que coordinar:

La configuración inicial del o los BINs en modo standalone.
El intercambio de claves públicas para cifrar el PAN/CVV en ambas direcciones, y la generación de los pares api-key / api-secret para firmar y validar webhooks. El procedimiento detallado está en Intercambio de Llaves.
El setup de mTLS para que podamos invocar tus webhooks y puedas realizar llamadas para el manejo de ciclo de vida. Revisa la documentación de Métodos de Conexión para los certificados requeridos.
El alta de las URLs de tus webhooks en cada ambiente.

Para los contratos detallados de cada API, consulta nuestra referencia técnica y los swaggers que entregamos como parte del onboarding de la integración.