ACTIVE, por lo que no necesitas activarlas. Esta guía aplica solo a tarjetas físicas.Activación de tarjetas físicas
Elige cómo tus clientes activan su tarjeta física, desde el PAN hasta un código con el formato que ya usas en tu operación.
Introducción
Cuando tu cliente recibe su tarjeta física, tiene que activarla para poder usarla.
Dependiendo de tu certificación, de tu experiencia de usuario y del tipo de tarjeta, puedes elegir entre varios métodos de activación.
En Pomelo, puedes activar tarjetas con el PAN, con el ID de tarjeta o con un código de activación que personalizas desde el grupo de afinidad: eliges el tipo de caracteres, el prefijo y la longitud.
Alcance
| Criterio | Condiciones |
|---|---|
| Tipo de tarjeta | Tarjetas físicas, nominadas e innominadas. |
| Estado requerido | La tarjeta debe estar EMBOSSED. En una reimpresión, la tarjeta original está ACTIVE. |
| Usuario | El usuario asociado debe estar activo. |
Métodos de activación
| Método | Qué necesitas | Nominadas | Innominadas |
|---|---|---|---|
| Con PAN | Si tienes certificación PCI-DSS vigente (ROC), usa el endpoint de Activación de tarjeta. Si no la tienes, usa nuestra web de data segura. | Sí | Sí |
| Con ID de tarjeta | El card_id que te devolvemos al crear la tarjeta. | Sí | No |
| Con código de activación | Deberás habilitar esta funcionalidad el código en el grupo de afinidad. Si tienes certificación PCI-DSS vigente (ROC), usa el endpoint de Activación de tarjeta. Si no la tienes, usa nuestra web de data segura. | Sí | Sí |
Validaciones al activar
Antes de activar la tarjeta, validamos lo siguiente:
| Validación | Detalle |
|---|---|
| Usuario | El usuario debe estar activo. |
| Estado de la tarjeta | La tarjeta debe estar EMBOSSED. |
| PIN | Debe tener 4 dígitos, no ser una secuencia ascendente o descendente (por ejemplo, 1234) ni una repetición de números (por ejemplo, 1111). |
Si operas en 🇲🇽 México, no pedimos el PIN para activar la tarjeta.
Código de activación
El código de activación viaja en el sobre de la tarjeta. Cuando tu cliente lo ingresa, ubicamos su tarjeta y la activamos, sin que tenga que conocer el PAN. El código es único entre las tarjetas EMBOSSED de tu operación.
Configuración en el grupo de afinidad
Defines el código al crear el grupo de afinidad desde el Dashboard: activa la opción "¿Quieres incluir el código en la impresión?" y elige cómo se genera.
| Opción | Descripción |
|---|---|
| Código predeterminado | Generamos un código numérico de 10 dígitos. |
| Personalizar código | Defines el formato del código con las opciones de abajo. |
Con "Personalizar código", puedes configurar:
| Campo | Descripción | Valores |
|---|---|---|
| Tipo | Caracteres que puede tener el código. | Numérico (solo dígitos) o alfanumérico (letras mayúsculas y números). |
| Prefijo (opcional) | Texto que va al inicio de todos tus códigos (por ejemplo, AA). | Solo letras en mayúscula sin caracteres especiales. |
| Longitud | Largo total del código, incluido el prefijo. | Entre 10 y 20 caracteres. |
Usa la vista previa para ver cómo quedan tus códigos antes de crear el grupo. Por ejemplo, con prefijo AA, tipo numérico y longitud 12, generamos códigos como AA0000000000.
Cómo generamos el código
Cuando creas una tarjeta física en un grupo con código habilitado, generamos el código con el formato que configuraste: el prefijo, seguido de caracteres aleatorios hasta completar la longitud. Verificamos que no coincida con el código de otra tarjeta EMBOSSED de tu operación (ni con una tarjeta ACTIVE en proceso de reimpresión).
El prefijo cuenta para la longitud. Si tu prefijo ocupa toda la longitud configurada, no queda espacio para generar el código y rechazamos la creación de la tarjeta con INVALID_ACTIVATION_CODE_CONFIG. Para corregirlo, crea un nuevo grupo de afinidad con un prefijo más corto o una longitud mayor.
La respuesta de creación de tarjeta no devuelve el código.
Reimpresión
Cuando creas una reimpresión con este endpoint, generamos un nuevo código de 10 dígitos (no usamos la configuración de tu grupo de afinidad) y lo devolvemos en la respuesta para que lo incluyas en el nuevo sobre. Tu cliente activa el nuevo plástico con ese código y te notificamos con el evento REPRINT_ACTIVATION.
Errores al activar con código
| Error | Cuándo ocurre |
|---|---|
CARD_NOT_FOUND | No existe una tarjeta con ese código. |
CARD_ALREADY_ACTIVATED | La tarjeta ya está ACTIVE y no corresponde a una reimpresión. |
Preguntas frecuentes
¿Necesito activar las tarjetas virtuales?
No. Las tarjetas virtuales nacen ACTIVE y listas para usar.
¿Puedo activar una tarjeta innominada con el ID de tarjeta?
No. Para tarjetas innominadas puedes activar con el PAN o con el código de activación.
¿Piden el PIN para activar la tarjeta?
Sí, salvo en 🇲🇽 México. El PIN debe tener 4 dígitos, no ser una secuencia ni una repetición de números.
¿Puedo cambiar el formato del código después de crear el grupo de afinidad?
No. Define el formato al crear el grupo. Si necesitas otro, crea un nuevo grupo de afinidad.
¿Qué pasa si mi grupo de afinidad no tiene el código habilitado?
No generamos ningún código. La tarjeta solo se puede activar con su PAN o su ID de tarjeta.
¿Puedo usar guiones u otros símbolos en mi código?
No. El código solo puede contener letras y números. Si necesitas un separador visual, agrégalo en el empaque de la tarjeta, no en el código.
¿Puedo ver el código en la respuesta de creación de la tarjeta?
No. La respuesta de creación de tarjeta nunca devuelve el código. La única respuesta pública que lo devuelve es la creación de una reimpresión.
¿Puedo usar el mismo código para activar más de una vez?
No. Una tarjeta ACTIVE rechaza la activación con CARD_ALREADY_ACTIVATED. La única excepción es la reimpresión: aceptamos el código nuevo y te notificamos con REPRINT_ACTIVATION.