Crear tarjetas
Te contamos cómo crear tarjetas nominadas e innominadas para tus clientes usando nuestras APIs.
Introducción
Te contamos cómo interactuar con nuestras APIs para crear y distribuir tarjetas nominadas e innominadas.
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_countrycon el código de 3 caracteres (estándar ISO 3166 alpha-3) del país en donde emitirás tu tarjeta. - Para el campo
nationalitytambié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,regionycountry. - Por una cuestión impositiva, te pediremos que informes el
tax_identification_typey eltax_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
regioncon 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-keycon 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).
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 tarjetas
Crea tu lote de hasta 1.000 tarjetas innominadas usando este endpoint. Si prefieres, puedes crear varios lotes juntos (hasta 15) usando este otro endpoint.
3. Crear usuario
Cada vez que definas a quien le asignarás una tarjeta, crea el usuario. Asegúrate de cumplir con los requisitos para cada país que contamos en Tarjetas nominadas.
4. Crear envío
Crea una solicitud de envío usando este endpoint asegurándote de cumplir los requisitos según el país donde operes:
- Tendrás que completar el campo
regioncon la provincia donde se encuentre tu cliente. - El campo
courier.tracking_urlde la respuesta, estará disponible una vez que el envío sea confirmado por el partner logístico correspondiente. Hasta entonces, tendrá valor nulo.
5. Activar tarjeta
Cuando tu cliente reciba la tarjeta, tendrás 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.
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.
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:
- Ir a un cajero automático, realizar una consulta de saldo o un retiro, e ingresar el nuevo PIN cuando se lo solicite.
- Realizar una compra en cualquier POS con el nuevo PIN.
Después de eso, el nuevo PIN queda activo para todas las operaciones ✅
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.
El PIN de las tarjetas es PIN Online: se almacena encriptado en nuestros sistemas y se valida de manera online cuando la operación lo requiere.
Cuando se cambia el PIN, todas las transacciones siguientes que lo requieran deben realizarse con el nuevo PIN para ser autorizadas.