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.

Crear Tarjeta

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

Validaremos que cumplas los requisitos que detallamos en la documentación.

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-5BERfwA0nyGFI4Wn8a5y3yv3IGW
affinity_group_idstringrequired
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
card_typestringrequired
Ejemplo: PHYSICAL
addressobject
companystring(maxLength: 30)
Ejemplo: Pomelo
previous_card_idstring
Si envías este atributo, trataremos la nueva tarjeta como un reemplazo de esta.
Ejemplo: crd-20gRqyp809SvDzXzhSeG2w6UiO5
pinstring
Ejemplo: 2023
name_on_cardstring(maxLength: 19)
Si envías este atributo, es el nombre que irá en la tarjeta en vez del nombre y apellido del usuario. [Solo disponible para Idemia, en Colombia y Perú]
Pattern: ^[A-Za-zÀ-ÿ ]+$
Ejemplo: Dieguito
Detalle de respuestas
dataobject

¿Te resultó útil esta sección?

POST/cards/v1/
{
"user_id":
"usr-5BERfwA0nyGFI4Wn8a5y3yv3IGW"
"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"
"additional_info":
"Torre 2. Casa amarilla"
}
"company":
"Pomelo"
"previous_card_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"pin":
"2023"
"name_on_card":
"Dieguito"
}
Ejemplo de respuestas
{
"data":{
"id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"VIRTUAL"
"product_type":
"PREPAID"
"status":
"ACTIVE"
"status_detail":
"CLIENT_INTERNAL_REASON"
"shipment_id":
"shi-2VOLbX1fAeWAn1rABlorxBqRyGF"
"user_id":
"usr-5BERfwA0nyGFI4Wn8a5y3yv3IGW"
"start_date":
"2021-11-08"
"last_four":
"1573"
"provider":
"MASTERCARD"
"affinity_group_name":
"VIRTUAL_TEST"
"company":
"Pomelo"
"name_on_card":
"Dieguito"
}
}

Buscar Tarjetas

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

Podrás filtrar y ordenar las tarjetas siguiendo esta documentación.

Los atributos para ordenar son:

  • card_type
  • user_id
  • status
  • affinity_group_id
  • status_detail
  • shipment_id
  • innominate
  • start_date.
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
filter[card_type]string
Enum: VIRTUALPHYSICAL
filter[id]string
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":[
...
]
}
}

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 por el reporte ROC. Si no tienes la certificación, sigue los pasos de esta documentación.
  • Si contrataste CVV dinámico, verás el campo cvv_expiration_time que determina la validez del nuevo código. Saber más sobre CVV dinámico.
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: pancvvpinnameexpiration_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"
"status_detail":
"CLIENT_INTERNAL_REASON"
"shipment_id":
"shi-2VOLbX1fAeWAn1rABlorxBqRyGF"
"user_id":
"usr-5BERfwA0nyGFI4Wn8a5y3yv3IGW"
"start_date":
"2021-11-08"
"last_four":
"1573"
"provider":
"MASTERCARD"
"affinity_group_name":
"VIRTUAL_TEST"
"company":
"Pomelo"
"name_on_card":
"Dieguito"
"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"
}
}

Activar Tarjeta

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

Validaremos que cumplas los requisitos que detallamos en la documentación.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
user_idstring
Id público del tarjetahabiente
Ejemplo: usr-5BERfwA0nyGFI4Wn8a5y3yv3IGW
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-5BERfwA0nyGFI4Wn8a5y3yv3IGW"
"pin":
"1475"
"previous_card_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"activation_code":
"0023456783"
}
Ejemplo de respuestas
{
"data":{
"id":
"crd-16262002575379UCMD2"
}
}

Eventos de tarjetas

Suma este endpoint en tu servicio para que podamos comunicarte las novedades de tus tarjetas en tiempo real.

Si tienes dudas sobre cómo configurar un webhook, visita nuestra documentación.

Consideraciones

Esperamos una respuesta del tipo 2XX para asegurarnos de que recibiste la notificación. Caso contrario, volveremos a enviarla.

Tipos de Eventos

  • CREATION: te notificaremos cada vez se cree una nueva tarjeta.
  • ACTIVATION: te notificaremos cada vez se active una tarjeta.
  • EMBOSSMENT: te notificaremos cada vez que enviemos a embozar una tarjeta.
  • BLOCK: te notificaremos cada vez que se bloquee una tarjeta.
  • UNBLOCK: te notificaremos cada vez que se desbloquee una tarjeta.
  • DISABLEMENT: te notificaremos cada vez que se desactive una tarjeta.
Parámetros disponibles
Header Parameters
X-Api-Keystringrequired
Este header te permitirá identificar qué api-secret usar en el caso que se hayan configurado múltiples pares de api-key y api-secret.
Ejemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este header contiene la firma digital (timestamp + endpoint + body) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.
Ejemplo: X-Signature: hmac-sha256 kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=
X-Timestampstringrequired
Este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.
Ejemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
El endpoint al que se realiza el pedido y usaste para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.
Ejemplo: X-Endpoint: {clientPath}/cards/events
Body Parameters
event_idstring
Identificador de evento.
Enum: card-notificationcard-activationcard-creationcard-embossmentcard-blockcard-unblockcard-disablement
idstring
ID de la tarjeta.
Ejemplo: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
updated_atstring
Fecha de actualización.
Ejemplo: 2023-09-21T14:15:31.186Z
user_idstring
ID del usuario.
Ejemplo: usr-23hJL4bm94q9BFEd2sGhBjY6xbH
eventstring
Tipo de notificación.
Ejemplo: ACTIVATION
card_typestring
Tipo de tarjeta.
Enum: VIRTUALPHYSICAL
related_card_idstring
ID de la tarjeta relacionada para tarjetas MultiApp.
Ejemplo: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
idempotency_keystring
Identificador idempotente de creación del evento.
Ejemplo: e42c0eb9-3986-4f01-9f4a-df8d02a9a92f

¿Te resultó útil esta sección?

POST/cards/v1/cards/events
{
"event_id":
"card-notification"
"id":
"crd-23hJL4bm94q9BFEd2sGhBjY6xbH"
"updated_at":
"2023-09-21T14:15:31.186Z"
"user_id":
"usr-23hJL4bm94q9BFEd2sGhBjY6xbH"
"event":
"ACTIVATION"
"card_type":
"VIRTUAL"
"related_card_id":
"crd-23hJL4bm94q9BFEd2sGhBjY6xbH"
"idempotency_key":
"e42c0eb9-3986-4f01-9f4a-df8d02a9a92f"
}
Ejemplo de respuestas

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"
"additional_info":
"Torre 2. Casa amarilla"
}
}
Ejemplo de respuestas
{
"data":{
"address":{
...
}
}
}

Refrescar CVV de Tarjeta

El endpoint /cards/{id}/cvv/refresh te permite refrescar el CVV dinámico de una tarjeta, invalidando el CVV actual y generando uno nuevo. Podrás obtener el nuevo CVV con el endpoint Obtener Tarjeta.

Consideraciones

Este endpoint solo aplica a tarjetas virtuales de un grupo de afinidad con la funcionalidad de CVV dinámico habilitada.

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

¿Te resultó útil esta sección?

POST/cards/v1/{id}/cvv/refresh
Ejemplo de respuestas
{
"data":{
"id":
"crd-23hJL4bm94q9BFEd2sGhBjY6xbH"
}
}

Crear Lote de Tarjetas Innominadas

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

Validaremos que cumplas los requisitos que detallamos en la documentación.

Consideraciones

  • Cada lote tiene un máximo de 1.000 tarjetas.
  • La dirección de envío es obligatoria si el tipo de distribución es CLIENT.
  • Procesaremos la llamada de forma asincrónica, es decir que es posible que las tarjetas no estén disponibles inmediatamente.
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
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"
"additional_info":
"Torre 2. Casa amarilla"
}
"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":
"shi-16281925351057V5BKK"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"PHYSICAL"
"quantity":
100
"distribution_type":
"CLIENT"
}
}

Crear Múltiples Lotes de Innominadas

El endpoint /cards/v1/batches/bulk te permite crear hasta 15 lotes de tarjetas innominadas al mismo tiempo.

Validaremos que cumplas los requisitos que detallamos en la documentación.

Consideraciones

  • Cada lote tiene un máximo de 1.000 tarjetas.
  • La dirección de envío es obligatoria si el tipo de distribución es CLIENT.
  • Procesaremos la llamada de forma asincrónica, es decir que es posible que las tarjetas no estén disponibles inmediatamente.
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
affinity_group_idstringrequired
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
quantitynumber(minimum: 1, maximum: 15000)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/bulk
{
"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"
"additional_info":
"Torre 2. Casa amarilla"
}
"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_ids":[
...
]
"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"
"additional_info":
"Torre 2. Casa amarilla"
}
"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":{
...
}
}
}

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
"total_non_usd_exchange_rate":
150.5
"exchange_currency_name":
"ARS"
"activation_code_enabled":
true
"dcvv_enabled":
true
"dcvv_expiration_in_seconds":
60
"start_date":
"2024-01-01"
"provider_algorithm":
"EMV_CSKD"
"custom_name_on_card_enabled":
false
"total_dcc_exchange_rate":
20.6
"dcc_exchange_rate_amount":
2
"non_usd_exchange_rate_amount":
100
"country":{
...
}
}
"meta":{}
}