Cartões

A API de Cartões contém todos os endpoints necessários para criar cartões nomeados e não nomeados, ativá-los, realizar pesquisas, obter as informações de um determinado cartão e muito mais.

Criar cartão

O endpoint /cards/v1/ permite criar um novo cartão, tanto físico como virtual.

Validaremos se você atende aos requisitos detalhados na [documentação] (https://docs.pomelo.la/pt/docs/cards/issuing/cards#3-activar-tarjeta).

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID única em cada solicitação para utilizar nosso esquema de idempotência.
Exemplo: fRwX12Dg3345AD
Body Parameters
user_idstringrequired
Exemplo: usr-5BERfwA0nyGFI4Wn8a5y3yv3IGW
affinity_group_idstringrequired
Exemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
card_typestringrequired
Exemplo: PHYSICAL
addressobject
companystring(maxLength: 30)
Exemplo: Pomelo
previous_card_idstring
Se este atributo for enviado, o novo cartão será tratado como substituto do cartão fornecido.
Exemplo: crd-20gRqyp809SvDzXzhSeG2w6UiO5
pinstring
Sólo aplicable a tarjetas nominadas mexicanas.
Exemplo: 2023
name_on_cardstring(maxLength: 19)
Se você enviar este atributo, é o nome que aparecerá no cartão no lugar do nome e sobrenome do usuário. [Disponível apenas para Idemia, na Colômbia e no Peru]
Pattern: ^[A-Za-zÀ-ÿ ]+$
Exemplo: Dieguito
Detalhe de respostas
dataobject

Esta seção foi útil para você?

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"
}
Respostas de amostra
{
"data":{
"id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"VIRTUAL"
"product_type":
"PREPAID"
"status":
"ACTIVE"
"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 cartões

O endpoint /cards/v1/ permite buscar um grupo de cartões com base nos atributos especificados.

Você pode filtrar e classificar cartões seguindo esta documentação.

Os atributos que podem ser ordenados são:

  • card_type
  • user_id
  • status
  • affinity_group_id
  • status_detail
  • shipment_id
  • innominate
  • start_date.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: 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
Tamanho de página.
page[number]number
Número de página. O número da primeira página é 0.
sortstring
Exemplo: status,-card_type
Detalhe de respostas
dataarray
metaobject

Esta seção foi útil para você?

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

Obter cartão

O endpoint /cards/v1/{id} permite obter informações sobre um cartão específico.

Considerações

  • O parâmetro extend é utilizado para obter dados adicionais de um cartão e, para utilizá-lo, é necessário possuir uma certificação PCI-DSS válida e atualizada, respaldada pelo relatório ROC. Se você não possui a certificação, siga os passos nesta documentação.
  • Se você contratou o CVV dinâmico, verá o campo cvv_expiration_time, que determina a validade do novo código. Saiba mais sobre o CVV dinâmico.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Query Parameters
extendstring
Permite obter informações adicionais, como número e CVV do cartão, que não são incluídas por padrão na resposta.
Enum: pancvvnameexpiration_date
Path Parameters
idstringrequired
Id pública do cartão
Detalhe de respostas
dataobject
metaobject

Esta seção foi útil para você?

GET/cards/v1/{id}
Respostas de amostra
{
"data":{
"id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"VIRTUAL"
"product_type":
"PREPAID"
"status":
"ACTIVE"
"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":[
...
]
}
}

Atualizar cartão

O endpoint /cards/v1/{id} permite atualizar o status, o grupo de afinidade e o PIN de um cartão.

Considerações

Será necessário especificar um motivo da lista abaixo para atualizar o status de um cartão:

Novo statusMotivo válido
BLOCKED / DISABLEDCLIENT_INTERNAL_REASON
BLOCKED / DISABLEDUSER_INTERNAL_REASON
DISABLEDLOST
DISABLEDSTOLEN
DISABLEDBROKEN
DISABLEDUPGRADE
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
affinity_group_idstring
Exemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
statusstring
Enum: ACTIVEBLOCKEDDISABLED
status_reasonstring
Enum: CLIENT_INTERNAL_REASONUSER_INTERNAL_REASONPOMELO_INTERNAL_REASONPROVIDER_INTERNAL_REASONLOSTSTOLENBROKENUPGRADE
pinstring
Exemplo: 1234
Path Parameters
idstringrequired
Id pública do cartão
Detalhe de respostas
dataobject

Esta seção foi útil para você?

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

Ativar cartão

O endpoint /cards/v1/activation permite ativar um cartão físico e configurar um PIN.

Validaremos se você atende aos requisitos detalhados na [documentação] (https://docs.pomelo.la/pt/docs/cards/issuing/cards#4-activar-tarjeta).

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
user_idstring
Id pública do titular do cartão
Exemplo: usr-5BERfwA0nyGFI4Wn8a5y3yv3IGW
pinstringrequired
Nova senha do cartão escolhida pelo usuário
Exemplo: 1475
previous_card_idstring
Se este atributo for enviado, o novo cartão será tratado como substituto do cartão fornecido.
Exemplo: crd-20gRqyp809SvDzXzhSeG2w6UiO5
activation_codestring(minLength: 10, maxLength: 10)required
Se você enviar este atributo, o cartão será ativado usando seu código de ativação
Exemplo: 0023456783
Detalhe de respostas
dataobject

Esta seção foi útil para você?

POST/cards/v1/activation
{
"user_id":
"usr-5BERfwA0nyGFI4Wn8a5y3yv3IGW"
"pin":
"1475"
"previous_card_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"activation_code":
"0023456783"
}
Respostas de amostra
{
"data":{
"id":
"crd-16262002575379UCMD2"
}
}

Eventos de cartões

Adicione este endpoint ao seu serviço para que possamos comunicar as últimas novidades sobre seus cartões em tempo real.

Se tiver dúvidas sobre como configurar um webhook, visite nossa documentação.

Considerações

Esperamos uma resposta na faixa 2XX para garantir que você tenha recebido a notificação. Caso contrário, iremos reenviá-la.

Tipos de eventos

  • ACTIVATION: Notificaremos você sempre que um de seus clientes ativar seu cartão.
Parâmetros disponíveis
Header Parameters
X-Api-Keystringrequired
Este header permitirá identificar qual api-secret deve-se usar, caso vários pares de api-key e api-secret tenham sido configurados.
Exemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este cabeçalho contém a assinatura digital (timestamp + endpoint + body) que deve ser verificada para garantir a integridade da solicitação. Se a assinatura não corresponder, o pedido deve ser rejeitado.
Exemplo: X-Signature: hmac-sha256 kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=
X-Timestampstringrequired
Este header contém a hora em que a solicitação foi assinada, no formato unix-epoch, para que você possa verificar se a assinatura não expirou.
Exemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
O endpoint que você usou para gerar a assinatura, e para o qual é feita a solicitação. Use este header para gerar novamente a assinatura a ser validada, e compare-o com o endpoint do seu serviço para verificar se eles correspondem.
Exemplo: X-Endpoint: {clientPath}/cards/events
Body Parameters
event_idstring
Identificador de evento.
Exemplo: card-notification
idstring
ID de la tarjeta.
Exemplo: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
updated_atstring
Data de Atualização
Exemplo: 2023-09-21T14:15:31.186Z
user_idstring
ID del usuario.
Exemplo: usr-23hJL4bm94q9BFEd2sGhBjY6xbH
eventstring
Tipo de notificación.
Exemplo: ACTIVATION
idempotency_keystring
Identificador idempotente para criar o evento.
Exemplo: e42c0eb9-3986-4f01-9f4a-df8d02a9a92f

Esta seção foi útil para você?

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"
"idempotency_key":
"e42c0eb9-3986-4f01-9f4a-df8d02a9a92f"
}
Respostas de amostra

Atualizar envio de cartão

O endpoint /cards/v1/{id}/shipment permite atualizar o endereço de envio de um cartão.

Considerações

O cartão deverá ser nomeado fisicamente e possuir o status CREATED.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
addressobject
Path Parameters
idstringrequired
Id pública do cartão
Detalhe de respostas
dataobject

Esta seção foi útil para você?

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"
}
}
Respostas de amostra
{
"data":{
"address":{
...
}
}
}

Atualizar CVV do cartão

O endpoint /cards/{id}/cvv/refresh permite atualizar o CVV dinâmico de um cartão, invalidando o CVV atual e gerando um novo. Você pode obter o novo CVV com o endpoint Obter Cartão.

Considerações

Este endpoint se aplica apenas a cartões virtuais de um grupo de afinidade com a funcionalidade de CVV dinâmico habilitada.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
idstringrequired
Id pública do cartão
Detalhe de respostas
dataobject

Esta seção foi útil para você?

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

Criar lote de cartões não nomeados

O endpoint /cards/v1/batches permite criar um lote de cartões sem nome.

Validaremos se você atende aos requisitos detalhados na [documentação] (https://docs.pomelo.la/pt/docs/cards/issuing/cards).

Considerações

  • Cada lote pode conter um máximo de 1.000 cartões.
  • O endereço de entrega é obrigatório se o tipo de distribuição for CLIENT.
  • Processaremos a chamada de forma assíncrona, o que significa que os cartões podem não estar disponíveis imediatamente.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID única em cada solicitação para utilizar nosso esquema de idempotência.
Exemplo: fRwX12Dg3345AD
Body Parameters
affinity_group_idstringrequired
Exemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
quantitynumber(minimum: 1, maximum: 1000)required
Exemplo: 100
distribution_typestringrequired
Enum: CLIENTWAREHOUSEEXTERNAL
addressobject
O endereço é obrigatório quando a distribuição é do tipo CLIENT
receiverobject
O destinatário é obrigatório quando a distribuição é do tipo CLIENT.
Detalhe de respostas
dataobject

Esta seção foi útil para você?

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"
}
}
Respostas de amostra
{
"data":{
"shipment_id":
"shi-16281925351057V5BKK"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"PHYSICAL"
"quantity":
100
"distribution_type":
"CLIENT"
}
}

Criar vários lotes de cartões não nomeados

O endpoint /cards/v1/batches/bulk permite que você crie até 15 lotes de cartões sem nome ao mesmo tempo.

Validaremos se você atende aos requisitos detalhados na [documentação] (https://docs.pomelo.la/pt/docs/cards/issuing/cards).

Considerações

  • Cada lote pode conter um máximo de 1.000 cartões.
  • O endereço de entrega é obrigatório se o tipo de distribuição for CLIENT.
  • Processaremos a chamada de forma assíncrona, o que significa que os cartões podem não estar disponíveis imediatamente.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID única em cada solicitação para utilizar nosso esquema de idempotência.
Exemplo: fRwX12Dg3345AD
Body Parameters
affinity_group_idstringrequired
Exemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
quantitynumber(minimum: 1, maximum: 15000)required
Exemplo: 100
distribution_typestringrequired
Enum: CLIENTWAREHOUSEEXTERNAL
addressobject
O endereço é obrigatório quando a distribuição é do tipo CLIENT
receiverobject
O destinatário é obrigatório quando a distribuição é do tipo CLIENT.
Detalhe de respostas
dataobject

Esta seção foi útil para você?

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"
}
}
Respostas de amostra
{
"data":{
"shipment_ids":[
...
]
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"PHYSICAL"
"quantity":
100
"distribution_type":
"CLIENT"
}
}

Atualizar envio de lote de cartões

O endpoint /cards/v1/batches/shipments/{shipmentId} permite atualizar o endereço de envio de um lote de cartões.

Considerações

O lote de cartões deverá ser nomeado fisicamente e possuir status CREATED.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
addressobject
receiverobject
Path Parameters
shipmentIdstringrequired
Id pública do envio
Detalhe de respostas
dataobject

Esta seção foi útil para você?

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"
}
}
Respostas de amostra
{
"data":{
"address":{
...
}
}
}

Obter Grupo de Afinidade

O endpoint /config/affinity-groups/{id} permite obter informações sobre um grupo de afinidade específico.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
idstringrequired
ID público do grupo de afinidade
Detalhe de respostas
dataobject
metaobject

Esta seção foi útil para você?

GET/cards/v1/config/affinity-groups/{id}
Respostas de amostra
{
"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
}
"meta":{}
}