Cards

The Cards API contains all the endpoints needed to create nominate and innominate cards, activate them, run queries, retrieve information on a particular card, and more.

Create Card

The endpoint /cards/v1/ enables you to create a new physical or virtual card.

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 utilize 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 this attribute is sent, the new card will be treated as a replacement for the card provided.
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"
"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"
}
}

Search Cards

The endpoint /cards/v1/ enables searching for a group of cards based on the attributes specified.

You can filter and sort cards by following this documentation.

The possible sorting attributes 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 on 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} enables retrieving information about a particular card.

Considerations

  • The extend parameter is used to obtain additional data from a card, and to use it, you must have a valid and current PCI-DSS certification, backed by the ROC report. If you do not have the certification, follow the steps in [this documentation] (https://docs.pomelo.la/en/docs/cards/issuing/sensitive-information).
  • If you have contracted dynamic CVV, you will see the cvv_expiration_time field that determines the validity of the new code. Learn more about dynamic CVV.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Query Parameters
extendstring
It enables retrieving additional information such as PAN and CVC, which are not included by default in the response.
Enum: pancvvpinnameexpiration_date
Path Parameters
idstringrequired
Card Public ID
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"
"activated_at":
"2021-11-18"
}
"meta":{
"extend":[
...
]
}
}

Update Card

The endpoint /cards/v1/{id} enables updating a card’s status, affinity group, and PIN.

Considerations

You will need to specify a reason from the list below in order to update a card status:

New statusValid 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
Path Parameters
idstringrequired
Card Public ID
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"
}
Response examples
{
"data":{
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"status":
"ACTIVE"
"status_reason":
"CLIENT_INTERNAL_REASON"
"pin":
"1234"
}
}

Activate Card

The endpoint /cards/v1/activation enables you to activate a physical card and also set up 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
Cardholder’s public ID
Example: usr-5BERfwA0nyGFI4Wn8a5y3yv3IGW
pinstringrequired
New card PIN created by user
Example: 1475
previous_card_idstring
If this attribute is sent, the new card will be treated as a replacement for the card provided.
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 that we can communicate the latest news about your cards in real time.

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

Considerations

We expect a response in the 2XX range to ensure that you've received the notification. Otherwise, we'll resend it.

Types of Events

  • CREATION: we notify you each time we create a new card.
  • ACTIVATION: we notify you each time we activate a card.
  • EMBOSSMENT: we notify you each time we send a card for embossing.
  • BLOCK: we notify you each time we block a card.
  • UNBLOCK: we notify you each time we unblock a card.
  • DISABLEMENT: we notify you each time we deactivate a card.
Available parameters
Header Parameters
X-Api-Keystringrequired
This header allows you to identify which api-secret you have to use in case that 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 must be verified to ensure the integrity of the request. If the signature does not match, the order must be rejected.
Example: X-Signature: hmac-sha256 kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=
X-Timestampstringrequired
This header has the moment the order was signed in unix-epoch format so that you can verify the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint where the order is placed and used to create the signature. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm 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
Updated 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 creating the event.
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 enables updating the shipping address of a card.

Considerations

The card must be physical, nominate and have a CREATED status.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
addressobject
Path Parameters
idstringrequired
Card Public ID
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 /cards/{id}/cvv/refresh endpoint allows you to refresh the dynamic CVV of a card, invalidating the current CVV and generating a new one. You can retrieve the new CVV using the Get Card endpoint.

Considerations

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

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
idstringrequired
Card Public ID
Response details
dataobject

Was this section helpful to you?

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

Create Batch of Innominate Cards

The endpoint /cards/v1/batches enables you to create a batch of innominate cards.

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

Considerations

  • Each batch can contain a maximum of 1,000 cards.
  • The shipping address is mandatory when distribution type is CLIENT.
  • We will process the call asynchronously, i.e. 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 utilize 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 required when the distribution is CLIENT type
receiverobject
Receiver is required when the distribution is CLIENT type.
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 Innominates

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

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

Considerations

  • Each batch can contain a maximum of 1,000 cards.
  • The shipping address is mandatory when distribution type is CLIENT.
  • We will process the call asynchronously, i.e. 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 utilize 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 required when the distribution is CLIENT type
receiverobject
Receiver is required when the distribution is CLIENT type.
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 Card Batch Shipping

The endpoint /cards/v1/batches/shipments/{shipmentId} enables updating the shipping address of a batch of cards.

Considerations

The card batch must be physical, innominate and have a CREATED status.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
addressobject
receiverobject
Path Parameters
shipmentIdstringrequired
Public ID of 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 to obtain information about a particular affinity group.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
idstringrequired
Public affinity group ID
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
"country":{
...
}
}
"meta":{}
}