Manejo de información sensible
Muestra los datos de la tarjeta, activa tarjetas y cambia el PIN cumpliendo con los requisitos de PCI-DSS.
Introducción
Para operar en el mercado de medios de pago, necesitas cumplir con PCI-DSS (Payment Card Industry Data Security Standard): un estándar de seguridad global y obligatorio, definido por las principales marcas de tarjetas de crédito y débito para proteger los datos de las tarjetas. Mostrarle a tu cliente el número de su tarjeta, activarla o cambiarle el PIN implica manejar esos datos.
En Pomelo, te damos la web de data segura: páginas que embebes en tu app para que tus clientes vean los datos de su tarjeta, la activen y cambien su PIN, cumpliendo con los requisitos de PCI-DSS.
Funcionamiento
La web de data segura tiene una página para cada operación. En los tres casos, la embebes en tu app con un iFrame HTML o un WebView y le envías los parámetros necesarios en la URL:
| Operación | URL |
|---|---|
| Mostrar los datos de la tarjeta | /v1/crd-id |
| Activar una tarjeta por PAN | /v1/activate-card |
| Activar una tarjeta por código | /v1/activate-card-by-code |
| Cambiar el PIN | /v1/change-pin/crd-id |
Token de usuario final
Para cargar cualquiera de estas páginas, necesitas un token de usuario final. Lo pides con tu client token usando el endpoint Crear token de usuario y lo incluyes en la URL como query param.
El token dura 15 minutos. Pasado ese tiempo, rechazamos los intentos y tienes que generar uno nuevo.
Parámetros comunes
Las tres páginas aceptan estos query param para configurarlas y personalizarlas con tu marca:
| Parámetro | Descripción | Valores posibles / Ejemplo |
|---|---|---|
locale | Idioma de los textos. | en, es, pt |
styles | URL de tu hoja de estilos. | ?styles=https://my-style-page.com/styles.css |
styles_string | Estilos definidos directamente en la URL. La URL puede tener hasta 2048 caracteres y los colores tienen que estar en formato RGB/RGBA. | ?styles_string=.card {border: 10px solid green;} .pan {border: 1px solid red;} |
styles, tienes que habilitar CORS para que podamos leer tu hoja de estilos.
Integración
Flujo
- Tu cliente pide ver los datos de su tarjeta en tu app.
- Desde tu app, inicias el pedido.
- Con tu client token, pides un token de usuario final con el endpoint Crear token de usuario.
- Te devolvemos el token, que te permite ver las tarjetas asociadas a tu cliente y manejar su información sensible. Dura 15 minutos.
- Incluyes el token en la URL de nuestra página de información sensible como
query param. - Embebes la página en tu app (te explicamos cómo en la sección siguiente).
- Validamos el token y enviamos los datos de la tarjeta a la web de data segura.
- La web de data segura muestra los datos dentro de tu app.
- ¡Listo! Tu cliente ve los datos de su tarjeta.
Embeber la página
Desde tu frontend, embebe la página con un iFrame o un WebView. Este es un ejemplo en HTML:
Este es un ejemplo en React Native:
Para que funcione el botón de copiar, habilita la escritura en el portapapeles:
Configurar la página
Además de los parámetros comunes, esta página acepta:
| Parámetro | Descripción | Valores posibles |
|---|---|---|
layout | Diseño de la tarjeta: horizontal (card) o vertical (list). | card, list |
field_list | Qué datos mostrar. Si no envías ningún valor, mostramos el PAN y el nombre del titular. El PIN solo está disponible para tarjetas físicas de 🇲🇽 México. | pan, code, pin, name, expiration |
Estilos
Con styles o styles_string puedes personalizar estos elementos, según el layout:
Diseño horizontal (card)

| Selector | Qué estiliza |
|---|---|
.card { ... } | Componente contenedor |
.card .pan {} | Número de tarjeta |
.card .pan .copy-icon {} | Botón para copiar |
.card .name {} | Titular de la tarjeta |
.card .expiration-date {} | Fecha de vencimiento |
.card .security-code {} | Código de seguridad |
.card .cvv_expiration_time {} | Tiempo de validez del CVV dinámico |
.card .pin {} | PIN |
Diseño vertical (list)

| Selector | Qué estiliza |
|---|---|
.list { ... } | Componente contenedor |
.list .pan {} | Número de tarjeta |
.list .pan .label {} | Texto sobre el número de tarjeta |
.list .pan .copy-icon {} | Botón para copiar |
.list .name {} | Titular de la tarjeta |
.list .name .label {} | Texto sobre el titular |
.list .expiration-date {} | Fecha de vencimiento |
.list .expiration-date .label {} | Texto sobre la fecha de vencimiento |
.list .security-code {} | Código de seguridad |
.list .security-code .label {} | Texto sobre el código de seguridad |
.list .cvv_expiration_time {} | Tiempo de validez del CVV dinámico |
.list .cvv_expiration_time .label {} | Texto sobre el tiempo de validez |
.list .pin {} | PIN |
.list .pin .label {} | Texto sobre el PIN |
Tu hoja de estilos debería verse así:
Tu cliente activa su tarjeta en un formulario de la web de data segura. Puede identificar la tarjeta con su número (PAN) o con un código de activación, y en ambos casos ingresa el PIN si corresponde.
Flujo
- Tu cliente quiere activar su tarjeta en tu app.
- Desde tu app, inicias el pedido.
- Con tu client token, pides un token de usuario final con el endpoint Crear token de usuario.
- Te devolvemos el token, que solo sirve para activar la tarjeta de tu cliente. Dura 15 minutos.
- Incluyes el token en la URL de nuestra página de activación como
query param. Si operas en 🇲🇽 México, también tienes que enviar el parámetrocountry. - Embebes la página en tu app (te explicamos cómo más abajo).
- Tu cliente ingresa los datos de su tarjeta.
- La web de data segura pide la activación con el token de usuario final.
- Validamos el token y la información enviada.
- Según el resultado, tu app muestra la página de éxito o de error (te explicamos cómo configurarlas en Respuestas del formulario).
Activación por PAN o por código
Las dos páginas funcionan igual: se embeben de la misma forma, usan los mismos query param (auth, country, success_link, styles, styles_string y locale) y manejan el PIN de la misma manera según el país o la configuración de tu cliente. Solo cambia el dato que tu cliente ingresa para identificar la tarjeta:
| Activación por PAN | Activación por código | |
|---|---|---|
| URL | /v1/activate-card | /v1/activate-card-by-code |
| Qué ingresa tu cliente | Número de tarjeta (16 dígitos). | Código de activación (alfanumérico, de 10 a 20 caracteres). |
| Prellenado por URL | No. | Sí, con el parámetro code. |
Para usar la activación por código:
- Cambia la URL del iFrame a
/v1/activate-card-by-code. - Mantén los mismos parámetros que ya usas (
auth,country,success_link, etc.). - Opcional: si quieres prellenar el código, agrega
code=<código>a la URL.
Prellenar el código desde un QR
Si envías el parámetro code, el campo aparece completo y tu cliente solo tiene que confirmarlo (e ingresar el PIN, si corresponde). Por ejemplo, puedes mostrar un QR con el código de activación: al leerlo, armas la URL con code=<código> y tu cliente no tiene que escribirlo a mano.
- El campo prellenado es editable: tu cliente puede corregirlo.
- Si no envías
code, el campo aparece vacío y tu cliente lo completa a mano. - Validamos el código de la misma forma, se haya escrito o venga del QR: si es inválido, mostramos el error y no enviamos la activación.
- La página de activación por PAN ignora el parámetro
code.
Así se ve la URL con el código:
Con QR (código prellenado):
Sin QR (activación manual), solo omites el parámetro code:
Embeber la página
Desde tu frontend, embebe el formulario con un iFrame o un WebView. Este es un ejemplo en React Native. Tienes que configurar estas propiedades del WebView:
- Sobrescribir el método
onShouldStartLoadWithRequest. - Sobrescribir el método
onNavigationStateChange. - Habilitar la ejecución de código JavaScript.
Este es un ejemplo en Swift. Tienes que configurar el NavigationDelegate para manejar la ejecución del link:
Configurar la página
Además de los parámetros comunes, las páginas de activación aceptan:
| Parámetro | Descripción | Ejemplo |
|---|---|---|
success_link | URL a la que redirigimos cuando la tarjeta queda activada. | ?success_link=https://my-success-link.com |
country | Código de país en formato ISO 3166-1 alfa-3, para comportamientos particulares de cada país. En 🇲🇽 México no mostramos el campo de PIN porque no es necesario. | ARG |
code | Solo para la activación por código: prellena el código de activación. | ?code=<código> |
Estilos
Con styles o styles_string puedes personalizar estos elementos:
| Selector | Qué estiliza |
|---|---|
.activation-form { ... } | Componente contenedor |
.activation-form .pan-input {} | Número de tarjeta (solo en la activación por PAN) |
.activation-form .code-input {} | Código de activación (solo en la activación por código) |
.activation-form .pin-input {} | PIN de la tarjeta |
.activation-form .error-field {} | Mensaje de error |
.activation-form .submit-button {} | Botón de enviar |
Mientras un campo muestra un error, le agregamos la clase error-input además de su clase base, y el mensaje se muestra en .error-field. Puedes personalizar ambas desde tu hoja de estilos:
Así se ve el formulario de activación por PAN:

Y así se ve el de activación por código:

Respuestas del formulario
Activación exitosa
Si la activación es exitosa, redirigimos al success_link que nos enviaste. Si tienes una app móvil, puedes enviarnos un deep link para continuar el flujo en tu app.
Activación con error
Cada vez que la activación falla, en la página por PAN o en la de código, el formulario muestra un mensaje a tu cliente en el idioma de locale y además emite un postMessage a la ventana contenedora. Así puedes reaccionar desde tu app: registrar el error, reintentar, navegar o mostrar tu propio texto.
En apps móviles con WebView, recibes el mismo payload como string JSON mediante window.ReactNativeWebView.postMessage.
error_code, nunca por status. El error_code es estable; el status es informativo y varios códigos comparten el mismo valor.
- Los errores de formato se detectan antes de enviar el formulario, así que no tienen
statusHTTP (llega comoundefined). - Si recibes un
error_codeque no está en estas tablas, trátalo como un error genérico que se puede reintentar. - Para
FORBIDDEN_ACCESSeINTERNAL_SERVER_ERROR, el formulario muestra un mensaje genérico. Si necesitas un texto específico, manéjalo desde tu app con elpostMessage. - El
postMessagesolo traeerror_codeystatus: el campomessageinterno no se envía.
Errores de formato
Ocurren antes de enviar los datos. Tu cliente puede corregirlos y reintentar en la misma pantalla.
error_code | Causa | Acción sugerida |
|---|---|---|
CODE_REGEX_FAILED | El código de activación no cumple el formato: alfanumérico, de 10 a 20 caracteres. | Pídele a tu cliente que revise el código. |
CARD_REGEX_FAILED | El número de tarjeta no tiene 16 dígitos. Solo en la activación por PAN. | Pídele a tu cliente que ingrese los 16 dígitos. |
PIN_REGEX_FAILED | El PIN no tiene 4 dígitos. | Pídele a tu cliente un PIN de 4 dígitos. |
Errores de negocio y de autorización
Ocurren mientras procesamos la activación. Esta es la lista completa de los códigos que devolvemos hoy:
error_code | Status HTTP | Causa | ¿Se puede reintentar? |
|---|---|---|---|
INVALID_REQUEST | 400 | Rechazamos la activación. Es un error genérico que agrupa todas las validaciones de negocio (ver abajo). | No, sin cambiar los datos. |
INVALID_PIN | 400 | El PIN tiene el formato correcto, pero no cumple las reglas de seguridad: no admite dígitos repetidos ni secuencias ascendentes o descendentes. | Sí, con otro PIN. |
NOT_AUTHORIZED | 401 | El token auth es inválido o venció. | Sí, con un token nuevo. |
FORBIDDEN_ACCESS | 403 | El token es válido, pero no habilita esta operación o no tiene la identificación de usuario o de cliente necesaria. | No. |
INTERNAL_SERVER_ERROR | 500 | Error inesperado de nuestro servicio. | Sí, más tarde. |
UNEXPECTED_ERROR | — | El formulario no puede atribuir la falla a ninguno de los casos anteriores, por ejemplo, ante un problema de red antes de recibir la respuesta. | Sí. |
INVALID_REQUEST agrupa todos los rechazos de negocio: que el código de activación no exista, que no corresponda a la tarjeta o al usuario autenticado, o que la tarjeta no se pueda activar en su estado actual. Lo agrupamos a propósito, por seguridad: si cada causa tuviera su propio código, alguien podría averiguar con intentos sucesivos si un código de activación existe o a qué usuario corresponde.
Mensajes que muestra el formulario
Estos son los textos que mostramos a tu cliente para cada código, sin que tengas que hacer nada. Se muestran en el idioma de locale; estos son los de es:
error_code | Texto que mostramos |
|---|---|
CODE_REGEX_FAILED | Ingresa un código de activación válido |
CARD_REGEX_FAILED | Ingresa los 16 números de tu tarjeta de forma completa |
PIN_REGEX_FAILED | Ingresa un pin de 4 digitos |
INVALID_PIN | El pin no debe contener dígitos repetidos, una secuencia ascendente o una secuencia descendente |
INVALID_REQUEST | La tarjeta no puede ser activada |
NOT_AUTHORIZED | Error activando tarjeta |
FORBIDDEN_ACCESS | Ocurrió un error inesperado |
INTERNAL_SERVER_ERROR | Ocurrió un error inesperado |
UNEXPECTED_ERROR | Ocurrió un error inesperado |
Mostrar tus propios mensajes
Si quieres otros textos, usa el error_code que recibes por postMessage para armar tu propio mapa:
Incluye siempre un valor por defecto al final: si en el futuro agregamos un código nuevo, tu integración muestra un mensaje genérico en lugar de fallar.
Tu cliente cambia el PIN de su tarjeta en un formulario de la web de data segura.
Flujo
- Tu cliente quiere cambiar el PIN de su tarjeta en tu app.
- Desde tu app, inicias el pedido.
- Con tu client token, pides un token de usuario final con el endpoint Crear token de usuario.
- Te devolvemos el token, que solo sirve para cambiar el PIN de la tarjeta de tu cliente. Dura 15 minutos.
- Incluyes el token en la URL de nuestra página de cambio de PIN como
query param. - Embebes la página en tu app (te explicamos cómo más abajo).
- Tu cliente ingresa los datos de su tarjeta.
- La web de data segura pide el cambio de PIN con el token de usuario final.
- Validamos el token y la información enviada. Según el resultado, tu app muestra la página de éxito o de error.
Embeber la página
Desde tu frontend, embebe el formulario con un iFrame o un WebView. Este es un ejemplo en React Native. Tienes que configurar estas propiedades del WebView:
- Sobrescribir el método
onShouldStartLoadWithRequest. - Sobrescribir el método
onNavigationStateChange. - Habilitar la ejecución de código JavaScript.
Este es un ejemplo en Swift. Tienes que configurar el NavigationDelegate para manejar la ejecución del link:
Configurar la página
Además de los parámetros comunes, esta página acepta:
| Parámetro | Descripción | Ejemplo |
|---|---|---|
success_link | URL a la que redirigimos cuando el PIN se cambia correctamente. | ?success_link=https://my-success-link.com |
Estilos
Con styles o styles_string puedes personalizar estos elementos:
| Selector | Qué estiliza |
|---|---|
.change-pin-form { ... } | Componente contenedor |
.change-pin-form .pin-input {} | PIN de la tarjeta |
.change-pin-form .error-field {} | Mensaje de error |
.change-pin-form .submit-button {} | Botón de enviar |
Mientras el campo de PIN muestra un error, también le agregamos la clase error-input (.pin-input.error-input), así que puedes reutilizar los estilos de error del formulario de activación.

Respuestas del formulario
Cambio de PIN exitoso
Si el cambio de PIN es exitoso, redirigimos al success_link que nos enviaste. Si tienes una app móvil, puedes enviarnos un deep link para continuar el flujo en tu app.
Cambio de PIN con error
Si algo falla, mostramos el error y le pedimos a tu cliente que vuelva a intentarlo. Para capturar el error en tu app, implementa un event listener como este:
Estos son los errores que devolvemos:
error_code | Qué pasó |
|---|---|
PIN_REGEX_FAILED | El formato del PIN es incorrecto. |
INVALID_PIN | El PIN no cumple las reglas de seguridad. |
NOT_AUTHORIZED | No tienes permisos para realizar la acción. |
INVALID_REQUEST | Hay un error en la solicitud. |
Preguntas frecuentes
¿Cuánto dura el token de usuario final?
15 minutos. Pasado ese tiempo, rechazamos los intentos y tienes que generar un token nuevo.
¿Puedo mostrar el PIN de cualquier tarjeta?
No. El PIN solo está disponible para tarjetas físicas de 🇲🇽 México.
¿Por qué recibo INVALID_REQUEST sin más detalle?
Porque agrupamos todos los rechazos de negocio en un solo código, por seguridad: así nadie puede averiguar con intentos sucesivos si un código de activación existe o a quién pertenece.
¿Tengo que mostrar yo los mensajes de error?
No. El formulario ya los muestra en el idioma de locale. El postMessage está disponible si además quieres reaccionar desde tu app o usar tus propios textos.