Cards

The Cards API contains all the endpoints necessary to create nominated and innominated cards, activate them, perform searches, obtain information about a particular card, and more.

Create Card

The endpoint /cards/v1/ allows you to create a new nominated card that can be physical or virtual.

We will validate that you meet the requirements detailed in the documentation.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
x-idempotency-keystringrequired
Unique ID in each request to use our idempotency scheme.
Example: fRwX12Dg3345AD
Body Parameters
user_idstringrequired
Example: usr-5BERfwA0nyGFI4Wn8a5y3yv3IGW
affinity_group_idstringrequired
Example: afg-20MpN8vmIPj77ujhb9cS8ctstN2
card_typestringrequired
Example: PHYSICAL
addressobject
companystring(maxLength: 30)
Example: Pomelo
previous_card_idstring
If you send this attribute, we will treat the new card as a replacement for this one.
Example: crd-20gRqyp809SvDzXzhSeG2w6UiO5
parent_idstring
Parent card ID.
Example: crd-20gRqyp809SvDzXzhSeG2w6UiO5
pinstring
Example: 2023
name_on_cardstring(maxLength: 19)
If you send this attribute, it is the name that will appear on the card instead of the user's first and last name. [Only available for Idemia, in Colombia and Peru]
Pattern: ^[A-Za-zÀ-ÿ ]+$
Example: Dieguito
Response details
dataobject

Was this section helpful to you?

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"
"parent_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"pin":
"2023"
"name_on_card":
"Dieguito"
}
Response examples
{
"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"
"parent_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
}
}

Search Cards

The endpoint /cards/v1/ allows you to search for a group of cards based on the attributes you specify.

You will be able to filter and sort the cards following this documentation.

The attributes for sorting are:

  • card_type
  • user_id
  • status
  • affinity_group_id
  • status_detail
  • shipment_id
  • innominate
  • start_date.
Available parameters
Header Parameters
Authorizationstringrequired
Example: 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
Page size.
page[number]number
Page number. The number of the first page is 0.
sortstring
Example: status,-card_type
Response details
dataarray
metaobject

Was this section helpful to you?

GET/cards/v1/
Response examples
{
"data":[
0:{
...
}
]
"meta":{
"pagination":{
...
}
"filter":[
...
]
}
}

Get Card.

The endpoint /cards/v1/{id} allows you to obtain information about a particular card.

Considerations

  • If you contracted dynamic CVV, you will see the cvv_expiration_time field that determines the validity of the new code. Learn more about dynamic CVV.

⚠️ Access to sensitive data through the extend parameter

This functionality allows access to sensitive card data such as the full number (PAN), security code (CVV), cardholder name, and expiration date.

By requirement of the PCI DSS standard, you may only use this functionality if:

  • PCI DSS certified accounts that include the processing and storage of card data.
  • You share your Attestation of Compliance (AOC) by email as formal proof of compliance.

If you do not meet these requirements, you may use our secure data Web.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Query Parameters
extendstring
Allows obtaining additional information such as the PAN and CVC, which are not included by default in the response.
Enum: pancvvpinnameexpiration_date
Path Parameters
idstringrequired
Public ID of the card.
Response details
dataobject
metaobject

Was this section helpful to you?

GET/cards/v1/{id}
Response examples
{
"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"
"parent_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
"activated_at":
"2021-11-18"
}
"meta":{
"extend":[
...
]
}
}

Update Card

The endpoint /cards/v1/{id} allows you to update the status of a card, its affinity group, and the PIN.

Considerations

You must specify a reason from the following list to update the status of a card:

New status.Valid reason
BLOCKED / DISABLEDCLIENT_INTERNAL_REASON
BLOCKED / DISABLEDUSER_INTERNAL_REASON
DISABLEDLOST
DISABLEDSTOLEN
DISABLEDBROKEN
DISABLEDUPGRADE
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
affinity_group_idstring
Example: afg-20MpN8vmIPj77ujhb9cS8ctstN2
statusstring
Enum: ACTIVEBLOCKEDDISABLED
status_reasonstring
Enum: CLIENT_INTERNAL_REASONUSER_INTERNAL_REASONPOMELO_INTERNAL_REASONPROVIDER_INTERNAL_REASONLOSTSTOLENBROKENUPGRADE
pinstring
Example: 1234
parent_idstring
Parent card ID.
Example: crd-20gRqyp809SvDzXzhSeG2w6UiO5
Path Parameters
idstringrequired
Public ID of the card.
Response details
dataobject

Was this section helpful to you?

PATCH/cards/v1/{id}
{
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"status":
"ACTIVE"
"status_reason":
"CLIENT_INTERNAL_REASON"
"pin":
"1234"
"parent_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
}
Response examples
{
"data":{
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"status":
"ACTIVE"
"status_reason":
"CLIENT_INTERNAL_REASON"
"pin":
"1234"
"parent_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
}
}

Activate Card

The endpoint /cards/v1/activation allows you to activate a physical card and also set a PIN.

We will validate that you meet the requirements detailed in the documentation..

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
user_idstring
Public ID of the cardholder.
Example: usr-5BERfwA0nyGFI4Wn8a5y3yv3IGW
pinstringrequired
New PIN of the card chosen by the user.
Example: 1475
previous_card_idstring
If you send this attribute, we will treat the new card as a replacement for this one.
Example: crd-20gRqyp809SvDzXzhSeG2w6UiO5
activation_codestring(minLength: 10, maxLength: 10)required
If you send this attribute, the card will be activated using its activation code.
Example: 0023456783
Response details
dataobject

Was this section helpful to you?

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

Card events

Add this endpoint to your service so we can communicate updates about your cards in real time.

If you have questions about how to set up a webhook, visit our documentation.

Considerations

We expect a response of type 2XX to ensure that you received the notification. Otherwise, we will resend it.

Event types.

  • CREATION: We will notify you each time a new card is created.
  • ACTIVATION: We will notify you each time a card is activated.
  • EMBOSSMENT: We will notify you each time we send a card for embossing.
  • BLOCK: We will notify you each time a card is blocked.
  • UNBLOCK: We will notify you each time a card is unlocked.
  • DISABLEMENT: We will notify you each time a card is deactivated.
Available parameters
Header Parameters
X-Api-Keystringrequired
This header will allow you to identify which api-secret to use in case multiple pairs of api-key and api-secret have been configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (timestamp + endpoint + body) that you must verify to ensure the integrity of the request. If the signature does not match, you must reject the order.
Example: X-Signature: hmac-sha256 kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=
X-Timestampstringrequired
This header contains the moment when the order was signed in unix-epoch format so you can verify that the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint to which the request is made and you used to generate the signature. Use this header to regenerate the signature to validate, compare it with your service endpoint, and verify that they match.
Example: X-Endpoint: {clientPath}/cards/events
Body Parameters
event_idstring
Event identifier.
Enum: card-notificationcard-activationcard-creationcard-embossmentcard-blockcard-unblockcard-disablement
idstring
Card ID.
Example: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
updated_atstring
Update date.
Example: 2023-09-21T14:15:31.186Z
user_idstring
User ID.
Example: usr-23hJL4bm94q9BFEd2sGhBjY6xbH
eventstring
Notification type.
Example: ACTIVATION
card_typestring
Card type.
Enum: VIRTUALPHYSICAL
related_card_idstring
Related card ID for MultiApp cards.
Example: crd-23hJL4bm94q9BFEd2sGhBjY6xbH
idempotency_keystring
Idempotent identifier for event creation.
Example: e42c0eb9-3986-4f01-9f4a-df8d02a9a92f

Was this section helpful to you?

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"
}
Response examples

Update Card Shipping

The endpoint /cards/v1/{id}/shipment allows you to update the shipping address of a card.

Considerations

The card must be a physical nominated card and have a status of CREATED.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
addressobject
Path Parameters
idstringrequired
Public ID of the card.
Response details
dataobject

Was this section helpful to you?

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"
}
}
Response examples
{
"data":{
"address":{
...
}
}
}

Refresh Card CVV

The endpoint /cards/{id}/cvv/refresh allows you to refresh the dynamic CVV of a card, invalidating the current CVV and generating a new one. You will be able to obtain the new CVV with the endpoint Get Card.

Considerations

This endpoint only applies to virtual cards of an affinity group with dynamic CVV functionality enabled.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
idstringrequired
Public ID of the card.
Response details
dataobject

Was this section helpful to you?

POST/cards/v1/{id}/cvv/refresh
Response examples
{
"data":{
"id":
"crd-23hJL4bm94q9BFEd2sGhBjY6xbH"
}
}

Create Batch of Innominated Cards

The endpoint /cards/v1/batches allows you to create a batch of innominated cards.

We will validate that you meet the requirements detailed in the documentation.

Considerations

  • Each batch has a maximum of 1,000 cards.
  • The shipping address is mandatory if the distribution type is CLIENT.
  • We will process the call asynchronously, meaning that the cards may not be available immediately.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
x-idempotency-keystringrequired
Unique ID in each request to use our idempotency scheme.
Example: fRwX12Dg3345AD
Body Parameters
affinity_group_idstringrequired
Example: afg-20MpN8vmIPj77ujhb9cS8ctstN2
quantitynumber(minimum: 1, maximum: 1000)required
Example: 100
distribution_typestringrequired
Enum: CLIENTWAREHOUSEEXTERNAL
addressobject
Address is mandatory when the distribution is of type CLIENT
receiverobject
Receiver is mandatory when the distribution is of type CLIENT.
Response details
dataobject

Was this section helpful to you?

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

Create Multiple Batches of Innominated Cards

The endpoint /cards/v1/batches/bulk allows you to create up to 15 batches of innominated cards at the same time.

We will validate that you meet the requirements detailed in the documentation.

Considerations

  • Each batch has a maximum of 1,000 cards.
  • The shipping address is mandatory if the distribution type is CLIENT.
  • We will process the call asynchronously, meaning that the cards may not be available immediately.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
x-idempotency-keystringrequired
Unique ID in each request to use our idempotency scheme.
Example: fRwX12Dg3345AD
Body Parameters
affinity_group_idstringrequired
Example: afg-20MpN8vmIPj77ujhb9cS8ctstN2
quantitynumber(minimum: 1, maximum: 15000)required
Example: 100
distribution_typestringrequired
Enum: CLIENTWAREHOUSEEXTERNAL
addressobject
Address is mandatory when the distribution is of type CLIENT
receiverobject
Receiver is mandatory when the distribution is of type CLIENT.
Response details
dataobject

Was this section helpful to you?

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

Update Shipping of a batch of cards

The endpoint /cards/v1/batches/shipments/{shipmentId} allows you to update the shipping address of a batch of cards.

Considerations

The batch of cards must be a physical innominated card and have a status of CREATED.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
addressobject
receiverobject
Path Parameters
shipmentIdstringrequired
Public ID of the shipment.
Response details
dataobject

Was this section helpful to you?

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"
}
}
Response examples
{
"data":{
"address":{
...
}
}
}

Get Affinity Group.

The endpoint /config/affinity-groups/{id} allows you to obtain information about a particular affinity group.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
idstringrequired
Public ID of the affinity group.
Response details
dataobject
metaobject

Was this section helpful to you?

GET/cards/v1/config/affinity-groups/{id}
Response examples
{
"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
"min_months_to_expiration":
36
"max_months_to_expiration":
48
"country":{
...
}
}
"meta":{}
}