Creación de tarjetas

Emite tarjetas nominadas e innominadas para tus clientes vía API o Dashboard.

Crear tarjetas vía API

Te contamos cómo interactuar con nuestras APIs para crear y distribuir tarjetas nominadas e innominadas.

Flujo tarjeta nominada

1. Solicitar token

Para empezar, tendrás que solicitar un token de autorización para comunicarte con nuestras APIs siguiendo esta documentación.

2. Crear un usuario

Tendrás que crear el usuario. Si usas nuestra solución de Identity, tan solo tendrás que completar su email y el operation_country. Si verificas la identidad de tus usuarios con un proveedor externo, entonces tendrás que asegurarte de cumplir estos requisitos según el país donde operes:

  • Completa el campo operation_country con el código de 3 caracteres (estándar ISO 3166 alpha-3) del país en donde emitirás tu tarjeta.
  • Para el campo nationality también esperamos un código estándar ISO 3166 alpha-3.
  • Por seguridad, necesitamos que completes los siguientes campos: name, surname, birthdate, email, identification_type, identification_value, gender, street_name, zip_code, city, region y country.
  • Por una cuestión impositiva, te pediremos que informes el tax_identification_type y el tax_identification_value.
  • Cada usuario debe tener un email único; también debe ser única la combinación de tipo de documento de identidad y valor.
  • Los tipos de documento que aceptamos son DNI (validaremos que su extensión sea de 7 u 8 caracteres), LE, LC, CI y PASSPORT.
  • El tipo de documento fiscal que aceptamos es el CUIL. Validaremos que los primeros dos dígitos sean 20, 23, 24, 27, 30, 33 o 34 y que su extensión sea de exactamente 11 caracteres.

3. Crear tarjetas

Usa este endpoint para crear tarjetas nominadas físicas o virtuales. Podrás indicar el tipo de tarjeta en el campo card_type.

Si eliges crear una tarjeta física y decides usar nuestro servicio de distribución, deberás especificar el domicilio de envío para que le llegue a tu cliente.

Además, validaremos que cumplas los siguientes requisitios según el país:

  • Tendrás que completar el campo region con la provincia donde se encuentre tu cliente.
  • Para asegurarnos de que una solicitud no se ejecute más de una vez, te pediremos que envíes el header x-idempotency-key con un ID único para usar nuestro esquema de idempotencia. Si dos solicitudes tienen el header con el mismo ID, solo crearemos una tarjeta y las dos solicitudes tendrán la misma respuesta positiva.

4. Activar tarjeta

Si elegiste que la tarjeta sea física, cuando tu cliente la reciba, tendrás que activarla. Puedes utilizar cualquiera de estos métodos:

  • Activar con PAN: Si tienes certificación PCI-DSS válida y vigente (ROC) usa el endpoint de Activación de tarjeta. Si no tienes, usa nuestra web de data segura.
  • Activar con código o QR: Para activar una tarjeta usando el código tendrás que configurarlo previamente en el grupo de afinidad.
  • Activar con ID de tarjeta: tendrás que ingresar el Card ID proporcionado en la creación.

Para activar la tarjeta validaremos:

  • Que el usuario esté activo y la tarjeta tenga estado EMBOSSED.
  • Que configures un PIN que sea de 4 dígitos, no sea una secuencia ascendente ni descendente (como por ejemplo: 1234) y no que sea una repetición de números (como por ejemplo: 1111).

Conoce toda la información sobre el estado de las tarjetas en esta documentación.

Crear tarjetas desde Dashboard

La emisión desde el Dashboard aplica a tarjetas físicas y virtuales, para cualquier grupo de afinidad (AFG) que tengas configurado en tu cuenta.

Funcionamiento

  1. Accede a la sección "Tarjetas emitidas" del Dashboard y haz clic en el botón "Emitir tarjeta".
  2. Define si la tarjeta será física o virtual.
  3. Elige el grupo de afinidad (AFG) que vas a usar. Si tu cuenta tiene más de un producto, ves todos los AFGs disponibles para elegir el que corresponda.
  4. Completa los datos del titular. Si elegiste una tarjeta física, además tendrás que informar el domicilio de entrega.
  5. Confirma la creación.
  6. ¡Listo! Si todo salió bien, puedes ver la tarjeta al instante o volver al listado para seguir operando.

Física vs. virtual

Tarjeta física Tarjeta virtual
Domicilio de entrega Requerido No aplica
Disponibilidad Llega en los próximos días hábiles Queda activa y lista para usar al instante
Datos necesarios Domicilio + datos del titular Solo los datos mínimos del titular

Cambio de PIN

Tu cliente puede cambiar su PIN en cualquier momento después de la activación.

El comportamiento del cambio varía según el país de operación:

En 🇲🇽México, las tarjetas usan PIN Offline para compras en POS —es decir, el PIN está grabado en el chip de la tarjeta— y PIN Online para operaciones en cajeros automáticos (ATM).

Al cambiar el PIN, solo se actualiza el PIN Online. Esto deja ambos PINes temporalmente desincronizados.

Para sincronizar el PIN Offline, tu cliente tiene que completar estos dos pasos en orden:

  1. Ir a un cajero automático, realizar una consulta de saldo o un retiro, e ingresar el nuevo PIN cuando se lo solicite.
  2. Realizar una compra en cualquier POS con el nuevo PIN.

Después de eso, el nuevo PIN queda activo para todas las operaciones ✅

Consultar estado de tarjeta

Ingresa al detalle de una tarjeta para ver en qué estado está, de qué marca (Visa o Mastercard) y tipo es (Débito, Crédito o Prepago), cuál es su ID, quién es el titular y a qué grupo de afinidad pertenece. Toca el botón “Ver más detalles” para encontrar aún más información. También puedes obtener el estado de una tarjeta vía API.

Estado de las tarjetas

Los diferentes estados por los que puede pasar una tarjeta son:

CREATED Indica que la tarjeta aún no está activa y por eso, no se puede usar. Este estado es exclusivo de tarjetas físicas.
EMBOSSED La tarjeta está en proceso de personalización. Este estado es exclusivo de tarjetas físicas.
ACTIVE Este estado indica que la tarjeta ya se puede usar para hacer transacciones. Las tarjetas virtuales nacen en este estado.
BLOCKED No se puede usar la tarjeta hasta que se vuelva a habilitar.
DISABLED La tarjeta fue desactivada y no se puede volver a usar. Es un estado final.
EXPIRED La tarjeta superó su fecha de vencimiento y no se puede volver a usar. Es un estado final.

En este gráfico podemos ver los estados de una tarjeta y a cuáles puede transicionar:

Estados de una tarjeta

Motivos de bloqueo o desactivación

Para pasar una tarjeta a BLOCKED o DISABLED, tienes que indicar un motivo válido en el campo status_reason:

Nuevo estado Motivo (status_reason) Descripción
BLOCKED / DISABLED CLIENT_INTERNAL_REASON Decisión de tu empresa.
BLOCKED / DISABLED USER_INTERNAL_REASON Pedido del usuario final.
DISABLED PROVIDER_INTERNAL_REASON Problema con el embozado.
DISABLED LOST Tarjeta perdida.
DISABLED STOLEN Tarjeta robada.
DISABLED BROKEN Tarjeta dañada.
DISABLED UPGRADE Fue reemplazada por otra tarjeta de mayor categoría.
BLOCKED / DISABLED ACQUIRER_ALERT Recomendación del adquirente.
BLOCKED / DISABLED FRAUD_SUSPECTED Sospecha de fraude.
BLOCKED / DISABLED ADC_ALERT Recomendación de la marca.
DISABLED CLIENT_FRAUD_DETECTION Filtración de datos.
BLOCKED / DISABLED BIN_ATTACK Ataque de BIN.
BLOCKED / DISABLED CHARGEBACK_ABUSE Abuso de contracargos.
BLOCKED / DISABLED DATA_LEAK Se filtró información del PAN.
BLOCKED / DISABLED SUSPECTED_MONEY_LAUNDERING Sospecha de lavado de dinero.
BLOCKED / DISABLED ACCOUNT_CANCELED Cancelaron la cuenta o línea de crédito asociada.
BLOCKED / DISABLED PIN_LIMIT_EXCEEDED Superó los intentos de PIN.

Verifica en qué etapa del ciclo de vida se encuentra cada tarjeta desde el Dashboard.
Consideraciones:

  • Las tarjetas virtuales no tienen ciclo de vida ni detalle de envío. Nacen activas y listas para usar.
  • Las tarjetas innominadas tendrán información recién cuando tu cliente las active.
  • Si la tarjeta es de crédito, podrás ver datos generales de la línea de crédito asociada.
  • Si la tarjeta es de débito verás los datos de la cuenta asociada.
  • Si la tarjeta está bloqueada o desactivada, no se podrá usar para operar. Te lo informaremos con una alerta.

Últimas transacciones

Desde el Detalle de tarjeta de Dashboard también podrás ver rápidamente las últimas operaciones realizadas con cada tarjeta.

Preguntas frecuentes

Mientras queden “desincronizados” los PINes, ¿cuál debe usar mi cliente para hacer una compra?
Debe usar el PIN anterior. Como las compras en POS usan PIN Offline (que aún no se actualizó), el nuevo PIN no va a funcionar hasta que el cliente complete el paso en el cajero.

Las tarjetas de mi usuario se bloquearon, ¿por qué puede ser?
Las tarjetas tienen un límite de intentos de PIN Offline en el chip. Si ese límite se supera, la tarjeta se bloquea automáticamente.

¿Qué pasa si la tarjeta se bloquea por superar la cantidad de intentos máximos de PIN offline?
El cliente debe realizar un cambio de PIN.. Esto resetea el contador de intentos y desbloquea la tarjeta.

Pomelo AI

Asistente de inteligencia artificial para consultas sobre la API de Pomelo
¡Hola!¿Cómo puedo ayudarte hoy?
Creación de tarjetas