La API de Cards contiene todos los endpoints necesarios para crear tarjetas nominadas e innominadas, activarlas, hacer búsquedas, obtener la información de una tarjeta en particular y más.
El endpoint /cards/v1/{id}
te permite obtener información sobre una tarjeta en particular.
El parámetro extend
se usa para obtener datos adicionales de una tarjeta y para usarlo deberás contar con una certificación PCI-DSS válida y vigente, respaldada
En las tarjetas virtuales, puedes aumentar la seguridad en las compras digitales y limitar la posibilidad de fraude mediante el uso de CVV dinámico (o dCVV)
Para activarlo, deberás configurar el Grupo de Afinidad con el equipo de Operaciones. Luego nosotros nos encargaremos de la generación de los códigos de seguridad. Comenzarás a ver un nuevo campo cvv_expiration_time que determina la validez de tu nuevo código.
El endpoint /cards/v1/{id}
te permite actualizar el estado de una tarjeta, su grupo de afinidad y el PIN.
Deberás especificar una razón del siguiente listado para poder actualizar el estado de una tarjeta:
Nuevo estado | Razón válida |
---|---|
BLOCKED / DISABLED | CLIENT_INTERNAL_REASON |
BLOCKED / DISABLED | USER_INTERNAL_REASON |
DISABLED | LOST |
DISABLED | STOLEN |
DISABLED | BROKEN |
DISABLED | UPGRADE |
El endpoint /cards/v1/{id}/shipment
te permite actualizar el domicilio de envío de una tarjeta.
La tarjeta deberá ser física nominada y tener estado CREATED
.
El endpoint /cards/v1/
te permite buscar un grupo de tarjetas según los atributos que especifiques.
Tendrás que especificar tus filtros como parámetros siguiendo este patrón: filter[campo]=valor
. Por ejemplo: filter[status]=CREATED
.
Para filtrar un atributo con varios valores posibles, deberás separar los valores con comas.
Veamos un ejemplo: filter[status]=CREATED,ACTIVE
Los resultados serán paginados y podrás especificar la cantidad de datos por página y también qué página ver utilizando: page[number]=valor
y page[size]=valor
Podrás especificar el orden de los resultados con determinados parámetros que deberás enviar como una lista de strings en el filtro de tipo sort. Por ejemplo: /cards/v1/?sort=status,card_type
.
El ordenamiento por defecto será ascendente. Para especificar un orden descendente, deberás enviar el carácter '-' como prefijo del atributo. Por ejemplo: /cards/v1/?sort=status,-card_type
.
Los atributos para ordenar son:
card_type
user_id
status
affinity_group_id
status_detail
shipment_id
innominate
start_date
.Si un parámetro es incorrecto o está mal escrito, responderemos con un error.
El endpoint /cards/v1/
permite crear una nueva tarjeta nominada que puede ser física o virtual.
Para crear una nueva tarjeta física, deberás especificar el domicilio de envío.
Si usas un grupo de afinidad configurado con envíos que NO que manejamos desde Pomelo junto a nuestros socios, no es requerido el campo address
. En ese caso, te recomendamos almacenar en tu integración, el campo de respuesta shipment_id
ya que lo necesitarás para hacer el retiro.
Podrás usar el parámetro previous_card_id
, para especificar que una tarjeta es reemplazo de una anterior.
Para asegurar 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
El campo region
se corresponde con:
Si operas en Brasil, deberás completar el campo region
con el código UF de dos caracteres.
Ejemplo: SP
para São Paulo
Si operas en Colombia, el campo zip_code
es opcional, es decir que podrás no enviarlo.
Si operas en México, podrás proveer el pin al momento de crear la tarjeta. En caso de no hacerlo, se generará con un pin aleatorio que podrás consultar luego. Solo válido para tarjetas físicas nominadas.
La información que necesitamos de los usuarios para emitir una tarjeta varía según el país:
Los siguientes campos son obligatorios:
name
surname
birthdate
email
identification_type
identification_value
gender
street_name
zip_code
city
region
country
Los siguientes campos son obligatorios:
tax_identification_type
tax_identification_value
Los siguientes campos son obligatorios:
tax_identification_type
tax_identification_value
Además, para el caso de tarjetas de crédito validaremos el flujo de verificación de Identity por el que haya pasado el usuario.
Los flujos de Identity válidos para estos casos son:
kyc-cards
: Validación OK para usuarios finales de tarjetas de crédito.
kyc-cards-lite
: Validación exitosa para usuarios de tarjetas de crédito corporativas.
En los casos donde el flujo de Identity no coincida con nuestras validaciones, devolveremos un error.
Tip: Encuentra más información en la documentación de Identity.
Únicamente son obligatorios los siguientes campos:
name
surname
birthdate
email
identification_type
identification_value
region
country
El endpoint /cards/v1/batches
te permite crear un lote de tarjetas innominadas.
Un lote puede tener un máximo de 1000 tarjetas.
La dirección de envío es obligatoria si el tipo de distribución es CLIENT
.
Si decides que la distribución de las tarjetas no será con Pomelo o nuestros socios, el tipo de distribución deberá ser EXTERNAL
. En ese caso, te recomendamos almacenar en tu integración, el campo de respuesta shipment_id
ya que lo necesitarás para hacer el retiro.
Procesaremos la llamada de forma asincrónica, es decir que es posible que las tarjetas no estén disponibles inmediatamente.
El campo region
se corresponde con:
Si operas en Brasil, deberás completar el campo region
con el código UF de dos caracteres.
Ejemplo: SP
para São Paulo
Si operas en Colombia, el campo zip_code
es opcional, es decir que podrás no enviarlo.
El endpoint /cards/v1/batches/shipments/{shipmentId}
te permite actualizar el domicilio de envío de un lote de tarjetas.
El lote de tarjetas deberá ser física innominada y tener estado CREATED
.
El endpoint /cards/v1/activation
te permite activar una tarjeta física y también configurar un PIN.
El usuario deberá estar activo y la tarjeta deberá tener estado EMBOSSED
.
El PIN a configurar:
Podrás usar el parámetro previous_card_id
, para especificar que una tarjeta es reemplazo de una anterior.
Contarán con este tipo de activación las tarjetas que lo tengan previamente configurado en su affinity group (esto se debe indicar en la creación del mismo).
Para activar una tarjeta utilizando el PAN deberás contar con una certificación PCI-DSS válida y vigente, respaldada
La información que necesitamos de los usuarios para activar una tarjeta varía según el país:
Los siguientes campos son obligatorios:
name
surname
birthdate
email
identification_type
identification_value
gender
street_name
zip_code
city
region
country
Los siguientes campos son obligatorios:
tax_identification_type
tax_identification_value
Los siguientes campos son obligatorios:
tax_identification_type
tax_identification_value
Además, para el caso de tarjetas de crédito validaremos el flujo de verificación de Identity por el que haya pasado el usuario.
Los flujos de Identity válidos para estos casos son:
kyc-cards
: Validación OK para usuarios finales de tarjetas de crédito.
kyc-cards-lite
: Validación exitosa para usuarios de tarjetas de crédito corporativas.
En los casos donde el flujo de Identity no coincida con nuestras validaciones, devolveremos un error.
Tip: Encuentra más información en la documentación de Identity.
Únicamente son obligatorios los siguientes campos:
name
surname
birthdate
email
identification_type
identification_value
region
country
/config/affinity-groups/{id}
te permite obtener información sobre un grupo de afinidad en particular.