Tarjetas

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.

Obtener Tarjeta

El endpoint /cards/v1/{id} te permite obtener información sobre una tarjeta en particular.

Consideraciones

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

CVV Dinámico

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.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
extendstring
Permite obtener información adicional como el pan y cvc, que no están incluidos por defecto en la respuesta.
Enum: pancvvnameexpiration_date
Path Parameters
idstringrequired
Id público de la tarjeta
Detalle de respuestas
dataobject
metaobject

¿Te resultó útil esta sección?

GET/cards/v1/{id}
Ejemplo de respuestas
{
"data":{
"id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"VIRTUAL"
"product_type":
"PREPAID"
"status":
"ACTIVE"
"shipment_id":
"shi-16281925351057V5BKK"
"user_id":
"usr-1625506260864NAS060"
"start_date":
"2021-11-08"
"last_four":
"1573"
"provider":
"MASTERCARD"
"affinity_group_name":
"VIRTUAL_TEST"
"activated_at":
"2021-11-18"
}
"meta":{
"extend":[
...
]
}
}

Actualizar Tarjeta

El endpoint /cards/v1/{id} te permite actualizar el estado de una tarjeta, su grupo de afinidad y el PIN.

Consideraciones

Deberás especificar una razón del siguiente listado para poder actualizar el estado de una tarjeta:

Nuevo estadoRazón válida
BLOCKED / DISABLEDCLIENT_INTERNAL_REASON
BLOCKED / DISABLEDUSER_INTERNAL_REASON
DISABLEDLOST
DISABLEDSTOLEN
DISABLEDBROKEN
DISABLEDUPGRADE
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
affinity_group_idstring
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
statusstring
Enum: ACTIVEBLOCKEDDISABLED
status_reasonstring
Enum: CLIENT_INTERNAL_REASONUSER_INTERNAL_REASONPOMELO_INTERNAL_REASONPROVIDER_INTERNAL_REASONLOSTSTOLENBROKENUPGRADE
pinstring
Ejemplo: 1234
Path Parameters
idstringrequired
Id público de la tarjeta
Detalle de respuestas
dataobject

¿Te resultó útil esta sección?

PATCH/cards/v1/{id}
{
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"status":
"ACTIVE"
"status_reason":
"CLIENT_INTERNAL_REASON"
"pin":
"1234"
}
Ejemplo de respuestas
{
"data":{
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"status":
"ACTIVE"
"status_reason":
"CLIENT_INTERNAL_REASON"
"pin":
"1234"
}
}

Actualizar Envío de Tarjeta

El endpoint /cards/v1/{id}/shipment te permite actualizar el domicilio de envío de una tarjeta.

Consideraciones

La tarjeta deberá ser física nominada y tener estado CREATED.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
addressobject
Path Parameters
idstringrequired
Id público de la tarjeta
Detalle de respuestas
dataobject

¿Te resultó útil esta sección?

PUT/cards/v1/{id}/shipment
{
"address":{
"street_name":
"Street"
"street_number":
"123"
"floor":
"5"
"apartment":
"A"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5653"
"neighborhood":
"Palermo"
}
}
Ejemplo de respuestas
{
"data":{
"address":{
...
}
}
}

Buscar Tarjetas

El endpoint /cards/v1/ te permite buscar un grupo de tarjetas según los atributos que especifiques.

Consideraciones

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

Ordenamiento

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.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
filter[card_type]string
Enum: VIRTUALPHYSICAL
filter[user_id]string
filter[status]string
filter[status_detail]string
Enum: CLIENT_INTERNAL_REASONUSER_INTERNAL_REASONPOMELO_INTERNAL_REASONPROVIDER_INTERNAL_REASONLOSTSTOLENBROKENUPGRADE
filter[affinity_group_id]string
filter[shipment_id]string
filter[innominate]boolean
filter[product_type]string
Enum: PREPAIDCREDITDEBIT
filter[product_provider]string
Enum: MASTERCARDVISA
filter[country_code]string
ISO 3166-1 alpha-3
page[size]number
Tamaño de página.
page[number]number
Número de página. El número de la primer página es 0.
sortstring
Ejemplo: status,-card_type
Detalle de respuestas
dataarray
metaobject

¿Te resultó útil esta sección?

GET/cards/v1/
Ejemplo de respuestas
{
"data":[
0:{
...
}
]
"meta":{
"pagination":{
...
}
"filter":[
...
]
}
}

Crear Tarjeta

El endpoint /cards/v1/ permite crear una nueva tarjeta nominada que puede ser física o virtual.

Consideraciones generales

Para crear una nueva tarjeta física, deberás especificar el domicilio de envío.

Envíos externos

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:

  • Provincia en Argentina
  • Estado en Brasil
  • Estado en Colombia
  • Estado en México
  • Departamento en Perú

Para Brasil

Si operas en Brasil, deberás completar el campo region con el código UF de dos caracteres.
Ejemplo: SP para São Paulo

  • Rondônia (RO)
  • Acre (AC)
  • Amazonas (AM)
  • Roraima (RR)
  • Pará (PA)
  • Amapá (AP)
  • Tocantins (TO)
  • Maranhão (MA)
  • Piauí (PI)
  • Ceará (CE)
  • Rio Grande do Norte (RN)
  • Paraíba (PB)
  • Pernambuco (PE)
  • Alagoas (AL)
  • Sergipe (SE)
  • Bahia (BA)
  • Minas Gerais (MG)
  • Espírito Santo (ES)
  • Rio de Janeiro (RJ)
  • São Paulo (SP)
  • Paraná (PR)
  • Santa Catarina (SC)
  • Rio Grande do Sul (RS)
  • Mato Grosso do Sul (MS)
  • Mato Grosso (MT)
  • Goiás (GO)
  • Distrito Federal (DF)

Para Colombia

Si operas en Colombia, el campo zip_code es opcional, es decir que podrás no enviarlo.

Para México

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.

Consideraciones sobre los usuarios a la hora de emitir una tarjeta

La información que necesitamos de los usuarios para emitir una tarjeta varía según el país:

Para todos los países:

Los siguientes campos son obligatorios:

  • name
  • surname
  • birthdate
  • email
  • identification_type
  • identification_value
  • gender
  • street_name
  • zip_code
  • city
  • region
  • country

Para Argentina

Los siguientes campos son obligatorios:

  • tax_identification_type
  • tax_identification_value

Para Brasil

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.

Para Perú

Únicamente son obligatorios los siguientes campos:

  • name
  • surname
  • birthdate
  • email
  • identification_type
  • identification_value
  • region
  • country
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID único en cada request para usar nuestro esquema de idempotencia.
Ejemplo: fRwX12Dg3345AD
Body Parameters
user_idstringrequired
Ejemplo: usr-1625758043579BAR6D4
affinity_group_idstringrequired
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
card_typestringrequired
Ejemplo: PHYSICAL
addressobject
previous_card_idstring
Si envías este atributo, trataremos la nueva tarjeta como un reemplazo de esta.
Ejemplo: crd-20gRqyp809SvDzXzhSeG2w6UiO5
pinstring
Sólo aplicable a tarjetas nominadas mexicanas.
Ejemplo: 2023
Detalle de respuestas
dataobject

¿Te resultó útil esta sección?

POST/cards/v1/
{
"user_id":
"usr-1625758043579BAR6D4"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"PHYSICAL"
"address":{
"street_name":
"Street"
"street_number":
"123"
"floor":
"5"
"apartment":
"A"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5653"
"neighborhood":
"Palermo"
}
"previous_card_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"pin":
"2023"
}
Ejemplo de respuestas
{
"data":{
"id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"VIRTUAL"
"product_type":
"PREPAID"
"status":
"ACTIVE"
"shipment_id":
"shi-16281925351057V5BKK"
"user_id":
"usr-1625506260864NAS060"
"start_date":
"2021-11-08"
"last_four":
"1573"
"provider":
"MASTERCARD"
"affinity_group_name":
"VIRTUAL_TEST"
}
}

Crear Lote de Tarjetas Innominadas

El endpoint /cards/v1/batches te permite crear un lote de tarjetas innominadas.

Consideraciones

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.

Envíos externos

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:

  • Provincia en Argentina
  • Estado en Brasil
  • Estado en Colombia
  • Estado en México
  • Departamento en Perú

Para Brasil

Si operas en Brasil, deberás completar el campo region con el código UF de dos caracteres.
Ejemplo: SP para São Paulo

  • Rondônia (RO)
  • Acre (AC)
  • Amazonas (AM)
  • Roraima (RR)
  • Pará (PA)
  • Amapá (AP)
  • Tocantins (TO)
  • Maranhão (MA)
  • Piauí (PI)
  • Ceará (CE)
  • Rio Grande do Norte (RN)
  • Paraíba (PB)
  • Pernambuco (PE)
  • Alagoas (AL)
  • Sergipe (SE)
  • Bahia (BA)
  • Minas Gerais (MG)
  • Espírito Santo (ES)
  • Rio de Janeiro (RJ)
  • São Paulo (SP)
  • Paraná (PR)
  • Santa Catarina (SC)
  • Rio Grande do Sul (RS)
  • Mato Grosso do Sul (MS)
  • Mato Grosso (MT)
  • Goiás (GO)
  • Distrito Federal (DF)

Para Colombia

Si operas en Colombia, el campo zip_code es opcional, es decir que podrás no enviarlo.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
affinity_group_idstringrequired
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
quantitynumber(minimum: 1, maximum: 1000)required
Ejemplo: 100
distribution_typestringrequired
Enum: CLIENTWAREHOUSEEXTERNAL
addressobject
Address es obligatorio cuando la distribución es de tipo CLIENT
receiverobject
Receiver es obligatorio cuando la distribución es de tipo CLIENT.
Detalle de respuestas
dataobject

¿Te resultó útil esta sección?

POST/cards/v1/batches
{
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"quantity":
100
"distribution_type":
"CLIENT"
"address":{
"street_name":
"Street"
"street_number":
"123"
"floor":
"5"
"apartment":
"A"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5653"
"neighborhood":
"Palermo"
}
"receiver":{
"full_name":
"Gonzalo Iglesias"
"email":
"document_type":
"enum - DNI - LE - LC - CI - PASSPORT - I ..."
"document_number":
"35354896"
"telephone_number":
"1132421452"
}
}
Ejemplo de respuestas
{
"data":{
"shipment_id":
"number"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"PHYSICAL"
"quantity":
100
"distribution_type":
"CLIENT"
}
}

Actualizar Envío de un lote de tarjetas

El endpoint /cards/v1/batches/shipments/{shipmentId} te permite actualizar el domicilio de envío de un lote de tarjetas.

Consideraciones

El lote de tarjetas deberá ser física innominada y tener estado CREATED.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
addressobject
receiverobject
Path Parameters
shipmentIdstringrequired
Id público del envío
Detalle de respuestas
dataobject

¿Te resultó útil esta sección?

PUT/cards/v1/batches/shipments/{shipmentId}
{
"address":{
"street_name":
"Street"
"street_number":
"123"
"floor":
"5"
"apartment":
"A"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5653"
"neighborhood":
"Palermo"
}
"receiver":{
"full_name":
"Gonzalo Iglesias"
"email":
"document_type":
"enum - DNI - LE - LC - CI - PASSPORT - I ..."
"document_number":
"35354896"
"telephone_number":
"1132421452"
}
}
Ejemplo de respuestas
{
"data":{
"address":{
...
}
}
}

Activar Tarjeta

El endpoint /cards/v1/activation te permite activar una tarjeta física y también configurar un PIN.

Consideraciones generales

El usuario deberá estar activo y la tarjeta deberá tener estado EMBOSSED.

El PIN a configurar:

  • Debe ser de 4 dígitos
  • No puede ser una secuencia ascendente. Por ejemplo: 1234
  • No puede ser una secuencia descendente. Por ejemplo: 4321
  • No puede ser una repetición de números. Por ejemplo: 1111

Podrás usar el parámetro previous_card_id, para especificar que una tarjeta es reemplazo de una anterior.

Tipos de activación:

  1. Activación por código

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).

  1. Activación por PAN

Para activar una tarjeta utilizando el PAN deberás contar con una certificación PCI-DSS válida y vigente, respaldada

Consideraciones sobre los usuarios a la hora de activar una tarjeta

La información que necesitamos de los usuarios para activar una tarjeta varía según el país:

Para todos los países:

Los siguientes campos son obligatorios:

  • name
  • surname
  • birthdate
  • email
  • identification_type
  • identification_value
  • gender
  • street_name
  • zip_code
  • city
  • region
  • country

Para Argentina

Los siguientes campos son obligatorios:

  • tax_identification_type
  • tax_identification_value

Para Brasil

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.

Para Perú

Únicamente son obligatorios los siguientes campos:

  • name
  • surname
  • birthdate
  • email
  • identification_type
  • identification_value
  • region
  • country
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
user_idstring
Id público del tarjetahabiente
Ejemplo: usr-1625758043579BAR6D4
pinstringrequired
Nuevo PIN de la tarjeta elegido por el usuario
Ejemplo: 1475
previous_card_idstring
Si envías este atributo, trataremos la nueva tarjeta como un reemplazo de esta.
Ejemplo: crd-20gRqyp809SvDzXzhSeG2w6UiO5
activation_codestring(minLength: 10, maxLength: 10)required
Si envías este atributo se activará la tarjeta usando el código de activación de la misma
Ejemplo: 0023456783
Detalle de respuestas
dataobject

¿Te resultó útil esta sección?

POST/cards/v1/activation
{
"user_id":
"usr-1625758043579BAR6D4"
"pin":
"1475"
"previous_card_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"activation_code":
"0023456783"
}
Ejemplo de respuestas
{
"data":{
"id":
"crd-16262002575379UCMD2"
}
}

Obtener Grupo de Afinidad

El endpoint /config/affinity-groups/{id} te permite obtener información sobre un grupo de afinidad en particular.
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
idstringrequired
ID público del grupo de afinidad
Detalle de respuestas
dataobject
metaobject

¿Te resultó útil esta sección?

GET/cards/v1/config/affinity-groups/{id}
Ejemplo de respuestas
{
"data":{
"name":
"Pomelo Innominate"
"card_type_supported":[
...
]
"innominate":
true
"months_to_expiration":
96
"issued_account":
9
"fee_account":
36
"exchange_rate_type":
"none"
"exchange_rate_amount":
100
"local_withdrawal_allowed":
true
"international_withdrawal_allowed":
true
"local_ecommerce_allowed":
true
"international_ecommerce_allowed":
true
"local_purchases_allowed":
true
"international_purchases_allowed":
true
"product_id":
"prd-20MpN8vmIPj77ujhb9cS8ctstN2"
"local_extracash_allowed":
false
"international_extracash_allowed":
true
"plastic_model":
388
"provider":
"MASTERCARD"
"kit_model":
122323
"embossing_company":
"THALES"
"courier_company":
"ANDREANI"
"id":
"string"
"status":
"ACTIVE"
"total_exchange_rate":
150.5
"exchange_currency_name":
"ARS"
"activation_code_enabled":
true
"dcvv_enabled":
true
}
"meta":{}
}