Manejo de información sensible
Muestra información sensible, activa tarjetas y cambia el PIN cumpliendo con los requisitos PCI-DSS.
Introducción
Para operar en el mercado de medios pagos es necesario cumplir con los requisitos de PCI-DSS (Payment Card Industry Data Security Standard), un estándar de seguridad en medios de pago y una normativa global obligatoria establecida por las principales marcas de tarjetas de crédito y débito. PCI-DSS tiene como objetivo garantizar la integridad y confidencialidad de los datos.
A continuación, te contaremos sobre nuestra solución web de data segura que te permitirá mostrar la información sensible, activar las tarjetas y realizar cambios de PIN cumpliendo con los requisitos PCI-DSS.
Web de data segura
La web de data segura te permite mostrar la información sensible y activar una tarjeta. Para ambos casos, deberás embeber una página web mediante un iFrame HTML o un WebView enviando los parámetros necesarios.
La web de data segura te permite mostrar la información sensible sobre una tarjeta.
- El flujo comienza cuando tu cliente solicita ver los datos de su tarjeta en tu app.
- Entonces desde tu app, inicias el pedido solicitando los datos de la tarjeta.
- Con tu client token podrás solicitar un token de usuario final usando este endpoint.
- Nosotros te devolveremos un token que te servirá para ver las tarjetas que tu cliente tenga asociadas y manejar su información sensible. Ten en cuenta que el token dura 15 minutos y pasado ese tiempo rechazaremos tus intentos. Para seguir operando, tendrás que generar uno nuevo.
- Una vez que tengas el token para tu cliente, deberás incluirlo en la URL de nuestra página de información sensible como
query param. - Luego, tendrás que embeber nuestra página de información sensible en tu app. En la siguiente sección te explicamos cómo embeberla y cómo configurarla.
- Validaremos el token y devolveremos los datos de la tarjeta a la web de data segura.
- Tu app muestra los datos de la tarjeta en nuestra web.
- ¡Listo! Tu cliente puede ver los datos de su tarjeta.
Embeber la web de data segura
Desde tu frontend, tendrás que usar algún método embebido para mostrar nuestra página de información sensible. A continuación, te mostramos un ejemplo de cómo embeber en nuestra página en HTML usando un iFrame.
Este es otro ejemplo en react-native:
Para que funcione el botón de copiar tendrás que habilitar la escritura al portapapeles de la siguiente manera:
Configurar y personalizar la web de data segura
Nuestra página de información sensible soporta varios query param para que puedas configurarla a tu gusto y personalizarla con tu marca.
| Parámetros | Descripción | Valores posibles / Ejemplo |
|---|---|---|
| layout | Podrás definir si la tarjeta tiene diseño horizontal o vertical. | list, card |
| field_list | Usa estos valores para definir qué mostrar. Si no envías ningún valor mostraremos el PAN y el nombre del titular de la tarjeta. El PIN solo está disponible para tarjetas físicas de México. | pan, code, pin, name, expiration |
| locale | Código de idioma para traducir textos. | en, es, pt |
| styles | URL donde se encuentre tu página de estilos de las tarjetas. | Ejemplo de URL |
| styles_string | Estilos definidos directamente en la URL. El largo de la URL puede tener un máximo de 2048 caracteres y los colores tienen que ser en formato RGB/RGBA. | [Ejemplo de](https://secure-data-web.pomelo.la/v1/crd-20eGcc6HrA3TcOhkorbEZmNj6Fg?styles\_string=.card {border: 10px solid green; border-radius: 100%;} .pan {border: 1px solid red;}) [URL](https://secure-data-web.pomelo.la/v1/crd-20eGcc6HrA3TcOhkorbEZmNj6Fg?styles\_string=.card {border: 10px solid green; border-radius: 100%;} .pan {border: 1px solid red;}) |
Usando el parámetro styles o styles_string podrás configurar los siguientes estilos:
| .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 expiración |
| .card .security-code {} | Código de seguridad |
| .card .cvv_expiration_time {} | Tiempo de validez para dCVV |
| .card .pin {} | Número de PIN |
| .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 NAME |
| .list .expiration-date {} | Fecha de expiración |
| .list .expiration-date .label {} | Texto sobre Exp Date |
| .list .security-code {} | Código de seguridad |
| .list .security-code .label {} | Texto sobre código de seguridad |
| .list .cvv_expiration_time {} | Tiempo de validez para dCVV |
| .list .cvv_expiration_time .label {} | Texto sobre expiración de tiempo de validez |
| .list .pin {} | Número de PIN |
| .list .pin .label {} | Texto sobre PIN |
La hoja de estilos debería ser similar a este ejemplo:
Activación por PAN
Te daremos una web con un formulario para que tus clientes puedan activar su tarjeta ingresando los 16 dígitos (PAN) y el PIN de ser necesario.
- El flujo comienza cuando tu cliente quiere activar su tarjeta tu app.
- Entonces, desde tu app iniciarás el pedido solicitando activar una tarjeta.
- Con tu client token podrás solicitar un token de usuario final usando este endpoint.
- Nosotros te devolveremos el token de usuario final que solo servirá para activar la tarjeta para tu cliente. Ten en cuenta que el token dura 15 minutos y pasado ese tiempo rechazaremos tus intentos. Para seguir operando, tendrás que generar uno nuevo token.
- Una vez que tengas el token para tu usuario, debes incluirlo en la URL de nuestra página de activación como
query param. Si operas en México, además tendrás que enviarnos el parámetrocountry. - En tu app, embebes nuestra web de activación. En la siguiente sección te explicamos cómo embeberla y cómo configurarla.
- Tu cliente tendrá que ingresar algunos datos de su tarjeta para avanzar en la activación.
- La web solicitará la activación de la tarjeta utilizando el token de usuario final obtenido.
- Validaremos el token y la información enviada.
- Dependiendo del resultado, tu app mostrará la página de contrats o de error. Te explicamos al final como configurar estas respuestas.
Activación por código
Además de la activación por número de tarjeta (PAN), tienes disponible una página de activación por código de activación. Funciona igual que la página de PAN: se integra como iframe de la misma forma, usa los mismos query param (auth, country, success_link, styles/styles_string, locale) y el manejo del PIN es igual según el país o la configuración de tu cliente. La única diferencia es qué le pides a tu usuario para identificar la tarjeta.
| Activación por PAN | Activación por código | |
|---|---|---|
| URL | /v1/activate-card | /v1/activate-card-by-code |
| Qué ingresa el usuario | Número de tarjeta (16 dígitos) | Código de activación (alfanumérico, 10 a 20 caracteres) |
| Prellenado por URL | No | Sí, con el parámetro code |
code solo lo utiliza la página /v1/activate-card-by-code. La página de activación por PAN lo ignora por completo.
Prellenar el código desde un QR
La página de activación por código acepta el query param code. Si lo envías, el campo aparece completo con ese valor y tu cliente solo tiene que confirmarlo (e ingresar el PIN, si corresponde).
Un caso de uso frecuente es mostrar un QR con el código de activación: al leerlo, armas la URL con code=<código> y le evitas a tu cliente escribirlo a mano.
- El campo prellenado es editable: tu cliente puede corregirlo.
- Si no envías
code, el campo aparece vacío y funciona como una activación manual. - El código se valida igual, se haya tipeado o venga por QR: si es inválido, mostramos el error correspondiente y no se envía la activación.
Cómo integrarte
- Cambia la URL del iframe a
/v1/activate-card-by-code. - Mantén los mismos parámetros que ya usas hoy (
auth,country,success_link, etc.). - Opcional: si quieres el flujo por QR, agrega
code=<código>a la URL.
Con QR (código prellenado):
Sin QR (activación manual): misma integración, solo omites el parámetro code — tu cliente escribe el código a mano.
El manejo del resultado (éxito y error) es el mismo que en la página de activación por PAN: revisa Manejo de errores más abajo.
Embeber la web de data segura
Desde tu frontend, tendrás que usar algún método embebido para mostrar el formulario de activación de tarjeta.
Te mostramos un ejemplo en React Native. Ten en cuenta que tendrás que configurar las siguientes propiedades del WebView:
- Sobreescribir el método
onShouldStartLoadWithRequest - Sobreescribir el método
onNavigationStateChange - Habilitar la ejecución de código javascript.
Este es un ejemplo en Swift. Tendrás que configurar el NavigationDelegate para manejar la ejecución del link:
Configurar y personalizar la web de data segura
Nuestra página de activación soporta varios query param para que puedas configurarla a tu gusto y personalizarla con tu marca.
| Parámetros | Descripción | Valores posibles / Ejemplo |
|---|---|---|
| success_link | URL que llamaremos cuando la tarjeta esté activada. | URL |
| country | Código de país en formato ISO 3166-1 alpha-3 para definir comportamientos particulares. Si operas en México, no te mostraremos el campo de PIN ya que no es necesario. | ARG |
| locale | Código de idioma para traducir textos. | en, es, pt |
| styles | URL donde se encuentre tu página de estilos de tarjetas. Más adelante te contamos los estilos disponibles y su descripción. | Ejemplo de URL |
| styles_string | Estilos definidos directamente en la URL. | [Ejemplo de](https://secure-data-web.pomelo.la/v1/activate-card/?styles\_string=.card {border: 10px solid green; border-radius: 100%;} .pan {border: 1px solid red;}) [URL](https://secure-data-web.pomelo.la/v1/activate-card/?styles\_string=.card {border: 10px solid green; border-radius: 100%;} .pan {border: 1px solid red;}) |
Usando el parámetro styles o styles_string podrás configurar los siguientes estilos:
| .activation-form { ... } | Componente contenedor |
|---|---|
| .activation-form .pan-input {} | Número de tarjeta (solo si utilizas este método de activación) |
| .activation-form .pin-input {} | PIN de la tarjeta |
| .activation-form .code-input {} | Código de activación (solo si utilizas este método de activación) |
| .activation-form .error-field {} | Errores de activación |
| .activation-form .submit-button {} | Botón de enviar |
Ejemplo de activación con PAN:
Ejemplo de activación con código:
Configurar las respuestas del formulario
Activación exitosa
Si la activación es exitosa, redireccionaremos al link que nos hayas enviado por parámetro.
Si se trata de una aplicación móvil, podrás enviarnos un deep link para continuar el flujo de tu aplicación.
Manejo de errores
Cada vez que la activación falla —tanto en la página por PAN como en la de código—, el formulario emite un postMessage a la ventana contenedora:
En aplicaciones móviles con WebView, recibes el mismo payload mediante window.ReactNativeWebView.postMessage, como string JSON.
El formulario ya muestra un mensaje al usuario final en el idioma indicado por el parámetro locale, sin que necesites ninguna acción adicional. El postMessage está disponible para que además puedas reaccionar desde tu aplicación: analítica, reintentos, navegación o reemplazo del texto por uno propio.
error_code y nunca por status. El error_code es el contrato estable; el status es informativo y no alcanza para distinguir causas, ya que varios códigos comparten el mismo valor.
- Los errores de validación de formato se detectan antes de enviar el formulario, por lo que no tienen un
statusHTTP asociado (llega comoundefined). Verifica siempreerror_codeprimero. - Si recibes un
error_codeque no está en las tablas siguientes, trátalo como un error genérico y reintentable. No infieras una causa puntual a partir de un código desconocido. - Para
FORBIDDEN_ACCESSeINTERNAL_SERVER_ERROR, el formulario le muestra al usuario final un mensaje genérico de error inesperado. Si necesitas un texto específico para esos casos, manéjalo desde tu aplicación a través delpostMessage.
Errores de validación del formulario
Se producen antes de enviar los datos. Tu cliente puede corregirlos y reintentar en la misma pantalla. No incluyen status.
error_code | Causa | Acción sugerida |
|---|---|---|
CODE_REGEX_FAILED | El código de activación no cumple el formato esperado: alfanumérico, de 10 a 20 caracteres. | Solicita la revisión del código ingresado. |
CARD_REGEX_FAILED | El número de tarjeta no tiene 16 dígitos. Aplica únicamente a la página de activación por PAN. | Solicita el ingreso completo de los 16 dígitos. |
PIN_REGEX_FAILED | El PIN no tiene 4 dígitos. | Solicita un PIN de 4 dígitos. |
Errores de negocio y de autorización
Se producen durante el procesamiento de la activación. Esta es la lista completa de códigos que devolvemos actualmente.
error_code | Status HTTP | Causa | Reintentable |
|---|---|---|---|
INVALID_REQUEST | 400 | Rechazamos la activación. Es un error genérico que agrupa todas las validaciones de negocio: código o tarjeta inexistentes, falta de correspondencia con el usuario autenticado, tarjeta en un estado no activable, entre otras. | No, sin modificar los datos |
INVALID_PIN | 400 | El PIN cumple el formato requerido pero no cumple las reglas de seguridad: no admite dígitos repetidos ni secuencias ascendentes o descendentes. | Sí, con un PIN distinto |
NOT_AUTHORIZED | 401 | El token auth es inválido o está expirado. | Sí, con un token nuevo |
FORBIDDEN_ACCESS | 403 | El token es válido pero no habilita esta operación, o no contiene la identificación de usuario o de cliente requerida. | No |
INTERNAL_SERVER_ERROR | 500 | Error inesperado de nuestro servicio. | Sí, más adelante |
UNEXPECTED_ERROR | — | Lo emite el formulario cuando la falla no puede atribuirse a ninguno de los casos anteriores, por ejemplo ante un problema de red previo a recibir una respuesta. | Sí |
INVALID_REQUEST es el caso general de 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 esté en un estado activable, todo llega como INVALID_REQUEST con status 400.
Esta agrupación es deliberada y responde a un criterio de seguridad: devolver un código distinto según la causa permitiría inferir, mediante intentos sucesivos, si un código de activación determinado existe o a qué usuario corresponde. Una respuesta uniforme elimina esa posibilidad.
Mensajes que muestra el formulario
Estos son los textos que mostramos al usuario final por cada código, sin que tengas que hacer nada. Se muestran en el idioma indicado por locale; a continuación, los correspondientes a es.
error_code | Texto mostrado |
|---|---|
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 |
El campo message que acompaña a cada error internamente no se propaga a la ventana contenedora: el postMessage transporta exclusivamente error_code y status.
Ejemplo de mapeo propio
Si necesitas una redacción distinta a la que mostramos por defecto, usa el error_code recibido por postMessage para construir tu propio mapa:
El valor por defecto del final es importante: si en el futuro agregamos un código nuevo, tu integración lo degrada a un mensaje genérico en lugar de fallar.
Estilos del estado de error
Mientras un input tiene un error visible, agregamos la clase error-input además de su clase base, y el texto del mensaje se renderiza en .error-field. Ambas clases están disponibles para que las personalices desde tu hoja de estilos:
La clase error-input también se usa en el formulario de cambio de PIN (.pin-input.error-input), así que puedes reutilizar el mismo estilo.
Te daremos una web con un formulario para que tus clientes puedan cambiar el PIN de su tarjeta.
- El flujo comienza cuando tu cliente quiere cambiar el PIN de su tarjeta en tu app.
- Entonces, desde tu app iniciarás el pedido solicitando cambiar el PIN.
- Con tu client token podrás solicitar un token de usuario final usando este endpoint.
- Nosotros te devolveremos el token de usuario final que solo servirá para cambiar el PIN de la tarjeta para tu cliente. Ten en cuenta que el token dura 15 minutos y pasado ese tiempo rechazaremos tus intentos. Para seguir operando, tendrás que generar uno nuevo.
- Una vez que tengas el token para tu usuario, debes incluirlo en la URL de nuestra página de cambio de PIN como
query param. - En tu app, embebes nuestra web de activación. En la siguiente sección te explicamos cómo embeberla y cómo configurarla.
- Tu cliente tendrá que ingresar algunos datos de su tarjeta para avanzar con el cambio de PIN.
- La web solicitará el cambio de PIN de la tarjeta utilizando el token de usuario final obtenido.
- Validaremos el token y la información enviada. Dependiendo del resultado, tu app mostrará la página de congrat o de error. Te explicamos al final como configurar estas respuestas.
Embeber la web de data segura
Desde tu frontend, tendrás que usar algún método embebido para mostrar el formulario de activación de tarjeta.
Te mostramos un ejemplo en React Native.
Tendrás que configurar las siguientes propiedades del WebView:
- Sobreescribir el método
onShouldStartLoadWithRequest. - Sobreescribir el método
onNavigationStateChange. - Habilitar la ejecución de código javascript.
Snippet
Este es un ejemplo en Swift. Tendrás que configurar el NavigationDelegate para manejar la ejecución del link:
Snippet
Configurar y personalizar la web de data segura
Nuestra página de activación soporta varios query param para que puedas configurarla a tu gusto y personalizarla con tu marca.
| Parámetros | Descripción | Ejemplo |
|---|---|---|
| success_link | URL que llamaremos cuando la tarjeta esté activada. | URL |
| locale | Código de idioma para traducir textos. | en, es, pt |
| styles | URL donde se encuentre tu página de estilos de tarjetas. Más adelante te contamos los estilos disponibles y su descripción. | URL |
| styles_string | Estilos definidos directamente en la URL. | URL |
Usando el parámetro styles o `styles_string podrás configurar los siguientes estilos:
| Valores | Descripción |
|---|---|
| .change-pin-form { ... } | Componente contenedor |
| .change-pin-form .pin-input {} | PIN de la tarjeta |
| .change-pin-form .error-field {} | Errores de activación |
| .change-pin-form .submit-button {} | Botón de enviar |
Configurar las respuestas del formulario
Cambio de PIN exitoso
Si el cambio de PIN es exitoso, redireccionaremos al link que nos hayas enviado por parámetro.
Si se trata de una aplicación móvil, podrás enviarnos un deep link para continuar el flujo de tu aplicación.
Manejo de errores
Si al momento de cambiar el PIN algo sale mal, mostraremos el error correspondiente y le pediremos a tus clientes que vuelvan a intentarlo. Para capturar este error debes implementar un event listener como en este ejemplo:
Snippet
Los errores que devolveremos son los siguientes:
| Valores | Descripción |
|---|---|
| PIN_REGEX_FAILED | Formato de PIN incorrecto. |
| NOT_AUTHORIZED | No tienes permisos para realizar la acción. |
| INVALID_PIN | PIN inválido. |
| INVALID_REQUEST | Error en la solicitud. |