Pomelo

Authorization

We implemented the OAuth 2.0 standard so you can communicate with our APIs with a single Bearer token.

Using the token

Once you receive the access token, you must include it as an authorization header every time you communicate with our APIs.

Example in Curl:

curl https://api.pomelo.la -H 'Authorization: Bearer eyJhbGciOiJSUzI1Ni'

Each API validates the access token and verifies that the scope matches the required permissions.

For the requests to be valid, communicate with our APIs only via HTTPS and include the authorization header indicating that it is a Bearer type.

Request token

The endpoint /oauth/v1/token is used to obtain an access token. When performing a successful authentication, be sure to save it as you will need it to communicate with our APIs.

Each token is a JWT that contains an expiration time. Request a new token only when the token you have has expired.

Available parameters
Header Parameters
content-typestringrequired
Enum: application/json
Body Parameters
client_idstringrequired
client_secretstringrequired
audiencestringrequired
Audiencia de API
grant_typestringrequired
Enum: client_credentials
Response details
access_tokenstring
Example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IloyTmZOUTQwWVVrNXh0WnNRRDlHYSJ9.eyJodHRwczovL3BvbWVsby5sYS9jbGllbnRfaWQiOiIyZmYxMjM0MTY3MzRmMjI5MmUxMTE0ODdiZWRlZmMxZTI1NDkxY2E4YzI1ZTEyMjAzM2E5MGE3NjM2ZDllNDI0IiwiaXNzIjoiaHR0cHM6Ly9wb21lbG8tZGV2ZWxvcC51cy5hdXRoMC5jb20vIiwic3ViIjoiMWNxdXBVM0U0bFpIY2U2ZFdVbHpuU29nZU1rR3ozelFAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vYXV0aC1kZXYucG9tZWxvLmxhIiwiaWF0IjoxNjMxMDM1MDQzLCJleHAiOjE2MzExMjE0NDMsImF6cCI6IjFjcXVwVTNFNGxaSGNlNmRXVWx6blNvZ2VNa0d6M3pRIiwic2NvcGUiOiJhcmc6Y2FyZHM6Z2V0LWNhcmQgYXJnOmNhcmRzOmdldC11c2VyLWNhcmQgYXJnOmNhcmRzOmNyZWF0ZS1iYXRjaCBhcmc6Y2FyZHM6YWN0aXZhdGUtY2FyZCBhcmc6Y2FyZHM6Y3JlYXRlLWNhcmQgYXJnOmNhcmRzOmNyZWF0ZS1jYXJkIGFyZzpjYXJkczp1cGRhdGUtYnVsay1jYXJkcyBhcmc6Y2FyZHM6c2VhcmNoLWNhcmQgYXJnOnVzZXJzOmdldC11c2VyIGFyZzp1c2VyczpjcmVhdGUtdXNlciBhcmc6dXNlcnM6c2VhcmNoLXVzZXIgYXJnOnVzZXJzOnVwZGF0ZS11c2VyIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.DkNi4BtLVdq1YMN5UFrtqvm2p-3DExt1X90janSfRWLbZHo2dtPtXkGfRF9kpdD3ZDA98euB68pt5nxZAGThaqm5g59pKkRz0nFzsDGUCH-Mfd6vYKGksO-dlyTeOwHyF189zYSvOMHcdaEOY2QybCWheOQnUgpFB7WaIPk6M8ZWI9SHSPtUjt6ePY7jsvDmVTtpXQM3ttB-0OarKN0qPi-A7WeD13Q7FuZHgQBxMipMlxeOfsz-RDOMwX7zTBhVNFp-Eu1Jtx1vFHVhDbG7tDW5N2np7kZvYXS5-wSP-fZMc57I1NmXrjbCACMWFhsnqTuHRJiHn3l-kG6nb7_EIw
scopestring
Example: arg:cards:get-card arg:cards:get-user-card
expires_ininteger
Example: 86400
token_typestring
Example: Bearer
Was this section helpful to you?
POST/oauth/token
{
"client_id":
"3LBFuOiEHrl4BailkRlsnIMmSctMLb7A"
"client_secret":
"s5u3oYK0-A9CV6TkszPQThUa_qxMfr2yyd3-eJwQ ..."
"audience":
"https://auth-dev.pomelo.la"
"grant_type":
"client_credentials"
}
Response examples

Users

The Users API contains all the endpoints needed to manage the user bases. You can use it to create, update or even search for users within certain parameters.

Create user

The /users/v1/ endpoint allows you to create a new user in our database.

The number of parameters required to create a user varies depending on the product you have signed up for, but we will always ask you for email and operation_country.

Consideraciones sobre usuarios repetidos

Cada usuario debe tener un email único, También debe ser única la combinación de tipo de documento de identidad y valor.

Considerations on the identity documents

For Argentina

The types of identity documents accepted are the following:

  • DNI
  • LE
  • LC
  • CI
  • PASSPORT

In the case of the DNI, we will validate that its extension is 7 or 8 characters.

The type of fiscal document accepted is the CUIL.

For Brazil

The types of identity documents accepted are the following:

  • RG
  • CNH

The type of fiscal document accepted is the CPF. We will validate that its extension is 11 characters.

For Mexico

The types of identity documents accepted are the following:

  • INE
  • PASSPORT

The type of tax document accepted is the RFC, but it will not be mandatory to include it.

For Argentina

If you operate in Argentina, the user’s legal address must be from one of these provinces:

  • Buenos Aires
  • Catamarca
  • Chaco
  • Chubut
  • Ciudad Autónoma de Buenos Aires
  • Corrientes
  • Córdoba
  • Entre Ríos
  • Formosa
  • Jujuy
  • La Pampa
  • La Rioja
  • Mendoza
  • Misiones
  • Neuquén
  • Río Negro
  • Salta
  • San Juan
  • San Luis
  • Santa Cruz
  • Santa Fe
  • Santiago del Estero
  • Tierra del Fuego
  • Tucumán

For Brazil

Si operas en Brasil, deberás completar el campo zipcode con un dato válido, ya que lo usaremos para determinar la dirección legal del usuario.

For Mexico

If you operate in Mexico, there are no special requirements regarding the user's legal address fields.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
x-idempotency-keystringrequired
Unique ID on each request to use our idempotency schema.
Example: fRwX12Dg3345AD
Body Parameters
namestring
Example: Diego
surnamestring
Example: Pomelo
identification_typestring
Enum: DNILELCCIPASSPORT
identification_valuestring
Example: 42345678
birthdatestring
ISO 8601
Example: 1998-08-20
genderstring
Example: MALE
emailstringrequired
phonestring
Example: 1123456789
tax_identification_typestring
Example: CUIL
Enum: CUIL
tax_identification_valuestring
Example: 20423456789
legal_addressobject
operation_countrystringrequired
ISO 3166 alpha-3
Example: ARG
Response details
dataobject
Was this section helpful to you?
POST/users/v1/
{
"name":
"Diego"
"surname":
"Pomelo"
"identification_type":
"DNI"
"identification_value":
42345678
"birthdate":
"1998-08-20"
"gender":
"MALE"
"phone":
"1123456789"
"tax_identification_type":
"CUIL"
"tax_identification_value":
20423456789
"legal_address":{
"street_name":
"Av. Corrientes"
"street_number":
300
"floor":
1
"apartment":
"A"
"zip_code":
1414
"neighborhood":
"Villa Crespo"
"city":
"CABA"
"region":
"Buenos Aires"
"additional_info":
"Torre 2"
"country":
"ARG"
}
"operation_country":
"ARG"
}
Response examples

Search user

The /users/v1/ endpoint allows you to search for a group of users and receive a list sorted according to the parameters specified.

Considerations

Filters must be specified as parameters following this pattern: filter[campo]=valor. For example: /users/v1/?filter[status]=ACTIVE To filter an attribute for several possible values, separate the values with commas. Let's look at an example: filter[status]=ACTIVE,BLOCKED

The results are paginated and you can specify the amount of data per page and also which page to view using: page[number]=value and page[size]=value

Sorting

You can specify the order of the results with certain parameters that you must send as list of strings in the sort filter type. For example: ?filter[status]=ACTIVE&sort=status,gender

The default sorting will be ascending. To specify a descending sorting, you must send the character '-' as a prefix of the attribute. For example: /users/v1/?filter[status]=ACTIVE&sort=status,-gender

The possible sorting attributes are:

  • id
  • gender
  • identification_type
  • identification_value
  • status

If a parameter is incorrect or misspelled, it will return an error.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Query Parameters
filter[identification_value]string
filter[identification_type]string
Enum: DNILELCCIPASSPORTRGCNHINE
filter[gender]string
Enum: MALEFEMALE
filter[birthdate]string
ISO 8601
Example: 1998-08-20
filter[name]string
Example: Juan
filter[surname]string
Example: Rodriguez
filter[email]string
filter[status]string
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: id,-name
Response details
dataarray
metaobject
Was this section helpful to you?
GET/users/v1/
Response examples

Get user

The /users/v1/{id} endpoint allows you to query a user’s information through their user_id.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
idstringrequired
User ID
Response details
dataobject
Was this section helpful to you?
GET/users/v1/{id}
Response examples

Modify user

The endpoint /users/v1/{id} allows you to update a user’s information with their ID.

Considerations

To block a user you must send the status with the value BLOCKED and the value CLIENT_INTERNAL_REASON in the status_reason field.

To reactivate a user you have blocked, you will need to send status with value ACTIVE.

Consideraciones sobre usuarios repetidos

Cada usuario debe tener un email único. También debe ser única la combinación de tipo de documento de identidad y valor.

Considerations on the identity documents

For Argentina

The types of identity documents accepted are the following:

  • DNI
  • LE
  • LC
  • CI
  • PASSPORT

In the case of the DNI, we will validate that its extension is 7 or 8 characters.

The type of fiscal document accepted is the CUIL.

For Brazil

The types of identity documents accepted are the following:

  • RG
  • CNH

The type of fiscal document accepted is the CPF. We will validate that its extension is 11 characters.

For Mexico

The types of identity documents accepted are the following:

  • INE
  • PASSPORT

The type of tax document accepted is the RFC, but it will not be mandatory to include it.

For Argentina

If you operate in Argentina, the user’s legal address must be from one of these provinces:

  • Buenos Aires
  • Catamarca
  • Chaco
  • Chubut
  • Ciudad Autónoma de Buenos Aires
  • Corrientes
  • Córdoba
  • Entre Ríos
  • Formosa
  • Jujuy
  • La Pampa
  • La Rioja
  • Mendoza
  • Misiones
  • Neuquén
  • Río Negro
  • Salta
  • San Juan
  • San Luis
  • Santa Cruz
  • Santa Fe
  • Santiago del Estero
  • Tierra del Fuego
  • Tucumán

For Brazil

Si operas en Brasil, deberás completar el campo zipcode con un dato válido, ya que lo usaremos para determinar la dirección legal del usuario.

For Mexico

If you operate in Mexico, there are no special requirements regarding the user's legal address fields.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
namestring
Example: Diego
surnamestring
Example: Pomelo
identification_typestring
Enum: DNILELCCIPASSPORT
identification_valuestring
Example: 42345678
birthdatestring
ISO 8601
Example: 1998-08-20
genderstring
Example: MALE
emailstring
phonestring
Example: 1123456789
tax_identification_typestring
Example: CUIL
Enum: CUIL
tax_identification_valuestring
Example: 20423456789
statusstring
Enum: ACTIVEBLOCKED
status_reasonstring
Enum: CLIENT_INTERNAL_REASON
legal_addressobject
Path Parameters
idstringrequired
User ID
Response details
dataobject
Was this section helpful to you?
PATCH/users/v1/{id}
{
"name":
"Diego"
"surname":
"Pomelo"
"identification_type":
"DNI"
"identification_value":
42345678
"birthdate":
"1998-08-20"
"gender":
"MALE"
"phone":
"1123456789"
"tax_identification_type":
"CUIL"
"tax_identification_value":
20423456789
"status":
"ACTIVE"
"status_reason":
"CLIENT_INTERNAL_REASON"
"legal_address":{
"street_name":
"Av. Corrientes"
"street_number":
300
"floor":
1
"apartment":
"A"
"zip_code":
1414
"neighborhood":
"Villa Crespo"
"city":
"CABA"
"region":
"Buenos Aires"
"additional_info":
"Torre 2"
"country":
"ARG"
}
}
Response examples

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.

Get Card

The endpoint /cards/v1/{id} enables retrieving information about a particular card.

Considerations

The parameter extend is used to retrieve additional data on a card.

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: pancvvnameexpiration_date
Path Parameters
idstringrequired
Card Public ID
Response details
dataobject
metaobject
Was this section helpful to you?
GET/cards/v1/{id}
Response examples

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
DISABLEDFRAUDULENT
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_REASONFRAUDULENTLOSTSTOLENBROKENUPGRADE
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

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

Search Cards

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

Considerations

You will need to specify your filters as parameters following this pattern: filter[campo]=valor. For example: filter[status]=CREATED. To filter an attribute for several possible values, separate the values with commas. Let's look at an example: filter[status]=CREATED,ACTIVE

The results are paginated and you can specify the amount of data per page and also which page to view using: page[number]=value and page[size]=value

Sorting

You can specify the order of the results with certain parameters that you must send as list of strings in the sort filter type. For example: /cards/v1/?sort=status,card_type.

The default sorting will be ascending. To specify a descending sorting, you must send the character '-' as a prefix of the attribute. For example: /cards/v1/?sort=status,-card_type.

The possible sorting attributes are:

  • card_type
  • user_id
  • status
  • affinity_group_id
  • status_detail
  • shipment_id
  • innominate.

If a parameter is incorrect or misspelled, it will return an error.

Available parameters
Header Parameters
Authorizationstringrequired
Example: 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_REASONFRAUDULENTLOSTSTOLENBROKENUPGRADE
filter[affinity_group_id]string
filter[shipment_id]string
filter[innominate]boolean
filter[product_type]string
Enum: PREPAIDCREDITDEBIT
filter[product_brand]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

Create Card

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

Considerations

To create a new physical card, you will need to specify the shipping address.

You can use the previous_card_id parameter to specify that a card is a replacement for a previous card.

To make sure that a request is not run more than once, please send the header: x-idempotency-key with a unique ID to use our idempotency schema. If two requests have the header with the same ID, we only create one card and the two requests have the same positive response

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
x-idempotency-keystringrequired
Unique ID on each request to use our idempotency scheme.
Example: fRwX12Dg3345AD
Body Parameters
user_idstringrequired
Example: usr-1625758043579BAR6D4
affinity_group_idstringrequired
Example: afg-20MpN8vmIPj77ujhb9cS8ctstN2
card_typestringrequired
Example: PHYSICAL
addressobject
previous_card_idstring
If this attribute is sent, the new card will be treated as a replacement for the card provided.
Example: crd-20gRqyp809SvDzXzhSeG2w6UiO5
Response details
dataobject
Was this section helpful to you?
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"
}
Response examples

Create Batch of Innominate Cards

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

Considerations

A batch can have a maximum of 1000 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}
Body Parameters
affinity_group_idstringrequired
Example: afg-20MpN8vmIPj77ujhb9cS8ctstN2
quantitynumber(minimum: 1, maximum: 1000)required
Example: 100
distribution_typestringrequired
Enum: CLIENTWAREHOUSE
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"
}
"receiver":{
"full_name":
"Gonzalo Iglesias"
"document_type":
"enum - DNI - LE - LC - CI - PASSPORT - I ..."
"document_number":
"35354896"
"telephone_number":
"1132421452"
}
}
Response examples

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"
}
"receiver":{
"full_name":
"Gonzalo Iglesias"
"document_type":
"enum - DNI - LE - LC - CI - PASSPORT - I ..."
"document_number":
"35354896"
"telephone_number":
"1132421452"
}
}
Response examples

Activate Card

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

Considerations

The user must be active and the card must have a EMBOSSEDstatus.

The PIN to set up:

  • Must be 4 digits
  • Can not be an ascending sequence. For example: 1234
  • Can not be a descending sequence. For example: 4321
  • Can not be a repetition of numbers. For example: 1111

You can use the previous_card_id parameter to specify that a card is a replacement for a previous card.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
user_idstringrequired
Cardholder’s public ID
Example: usr-1625758043579BAR6D4
panstringrequired
The PAN of the card being activated
Example: 4242424242424242
pinstringrequired
New card PIN created by user
Example: 1234
previous_card_idstring
If this attribute is sent, the new card will be treated as a replacement for the card provided.
Example: crd-20gRqyp809SvDzXzhSeG2w6UiO5
Response details
dataobject
Was this section helpful to you?
POST/cards/v1/activation
{
"user_id":
"usr-1625758043579BAR6D4"
"pan":
"4242424242424242"
"pin":
"1234"
"previous_card_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
}
Response examples

Shipments

The Shipping API contains all the endpoints and webhooks needed to create a shipment, get information about a shipment and stay up-to-date on events that affect a shipment.

Webhooks

You need a public endpoint so we can communicate about what’s new in shipments in real time.

Considerations

Your endpoint should end in /shipping/updates

We will notify you there if there are updates about a shipment. You are responsible for searching for the resource to get the updated status.

Sample url

POST https://api.current-customer.com/whatever/shipping/updates

Body

{
  'shipment_id': 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
  'meta': {
    'resource_url': 'http://localhost:8080/v1/{shipment_id}'
  }
}

Example in Curl

curl --request POST \
--url https://api.current-customer.com/whatever/shipping/updates \
--header 'Content-Type: application/json' \
--data '{
    'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
    'meta' : {
        'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
    }
}'

Security

As a security measure, all update notifications will include a hmac-sha256 signature, but the reply does not need to be signed by customers.

hmac-sha256 Order Signature

To ensure that the only participants in the communication are our backends (Pomelo and the Client), we provide you with an api-key and api-secret during onboarding to digitally sign the content of the communication.

Below we explain the key-exchange and order- signing processes in more depth.

Key exchange process

During the onboarding process, we create an api-key and api-secret specific to you.

It is also possible to use gpg or an email plugin (such as https://flowcrypt.com/).

Let’s look at an example using openssl on the command line.

  1. We create the api-key and api-secret:
$ echo -e 'api-key=$(openssl rand -base64 32)\napi-secret=$(openssl rand -base64 32)' > api-credentials.txt

$ cat api-credentials.txt
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=
  1. You create your public-private key:
$ openssl genrsa -out private.pem 2048
$ openssl rsa -in private.pem -pubout -out public.pem
  1. Send us your public.pem public key by email or Slack.

  2. We encrypt the credential file with the public key you gave us:

$ openssl rsautl -encrypt -in api-credentials.txt -out api-credentials.txt.enc -inkey public.pem -pubin
  1. We send the api-credentials.txt.enc file by email or Slack

  2. Decrypt the api-credentials.txt.enc file with your private.pem private key:

$ openssl rsautl -decrypt -in api-credentials.txt.enc -inkey private.pem
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=
  1. Keep the api-secret in a safe place that is accessible only through the “Authorize payments” application, associated with the api-key.

Request signature process

Along with the authorization or adjustment request we’ll send you HTTP headers with the signature, timestamp and the api-key so that you can verify the signature is correct.

The HTTP headers we send are:

  • x-api-key : this header allows you to identify which api-secret you have to use in the event that multiple api-key and api-secret pairs have been configured.

  • x-signature : this header contains the digital signature (body + timestamp + endpoint) that you must verify to ensure request integrity. If the signature does not match, the order must be rejected.

  • x-timestamp : this header contains the moment the order was signed in unix-epoch format so that you can verify that the signature has not expired.

  • x-endpoint : the endpoint to which the request is made and used to generate the signature. Use this header to regenerate the signature to be validated, compare it with the endpoint of your service and verify that they match.

Let’s look at a sample curl indicating how this information is sent within the request:

curl --location --request POST 'localhost:9090/shipping/updates' \
--header 'x-api-key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=' \
--header 'x-signature: hmac-sha256 kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=' \
--header 'x-timestamp: 1637117179' \
--header 'x-endpoint: {clientPath}/shipping/updates'
--header 'Content-Type: application/json' \
--data-raw '{
    'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
    'meta' : {
        'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
    }
}'

To set up a signature you can use the following code snippet (in python 3) such as:

import hmac, hashlib, base64, time

############# Pomelo's side ################
############################################

# pomelo's secret key
pomelo_secret_key = base64.b64decode('kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=')

# the update data pomelo is gonna use to make the signature
pomelo_update_body = '{
    'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
    'meta' : {
        'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
    }
}'
client_req_endpoint = '/shipping/updates'
pomelo_timestamp = str(int(time.time()))

# the request data signed out by pomelo
pomelo_signature = hmac.new(pomelo_secret_key, bytes(pomelo_timestamp + client_req_endpoint + pomelo_update_body, 'utf-8'), hashlib.sha256).digest()


############# Client's side ################
############################################

# client's secret key
client_secret_key = base64.b64decode('kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=')

# client's api endpoint
client_api_endpoint = '/transactions/authorizations'

# signature expiration offset
signature_expiration_offset = 60 #A minute of expiration

# the authorizacion data the client needs to use to recreate the signature
client_request_data = bytes(pomelo_timestamp + client_req_endpoint + pomelo_update_body, 'utf-8')

# the signature the client has recreated
signature = hmac.new(client_secret_key, client_request_data, hashlib.sha256).digest()

# if signature is not expired and they match you can trust the request, otherwise reject it
now = int(time.time()) - signature_expiration_offset

signatureExpired = int(pomelo_timestamp) < now
signaturesMatch = hmac.compare_digest(signature, pomelo_signature)
endpointsMatch = client_api_endpoint in client_req_endpoint

requestIsValid = not signatureExpired and signaturesMatch


################ Results ###################
############################################

print('pomelo' signature = {0}'.format(base64.b64encode(pomelo_signature)))
print('client's signature = {0}'.format(base64.b64encode(signature)))
print('signature expired = {0}'.format(signatureExpired))
print('signatures match = {0}'.format(signaturesMatch))
print('endpoints match = {0}'.format(endpointsMatch))
print('request is valid = {0}'.format(requestIsValid))

Create Shipment

The /shipments/v1/ endpoint is used to create a new shipment.

For Brazil

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

Para Brasil el taxIdentificationNumber es obligatorio.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
x-idempotency-keystringrequired
Unique ID on each request to use our idempotency scheme.
Example: fRwX12Dg3345AD
Body Parameters
shipment_typestringrequired
Enum: CARD_FROM_WAREHOUSE
affinity_group_idstringrequired
Example: afg-20MpN8vmIPj77ujhb9cS8ctstN2
countrystringrequired
Example: ARG
addressobject
receiverobject
Response details
dataobject
Was this section helpful to you?
POST/shipping/v1/
{
"shipment_type":
"CARD_FROM_WAREHOUSE"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"country":
"ARG"
"address":{
"street_name":
"Libertador"
"street_number":
"539"
"floor":
"2"
"apartment":
"B"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5346"
"neighborhood":
"string"
}
"receiver":{
"full_name":
"Gonzalo Iglesias"
"document_type":
"dni"
"document_number":
"243432423"
"tax_identification_number":
"38912151888"
"telephone_number":
"53454342"
}
}
Response examples

Search shipment

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

Considerations

Filters must be specified as parameters following this pattern: filter[campo]=valor. For example: filter[shipment_type]=BOX. To filter an attribute for several possible values, separate the values with commas. Let's look at an example: filter[shipment_type]=BOX,WAREHOUSE

The results are paginated and you can specify the amount of data per page and also which page to view using: page[1]=value and page[2]=value

Sorting

You can specify the order of the results with certain parameters that you must send as list of strings in the sort filter type. For example: /shipping/v1/?sort=status,shipment_type.

The default sorting will be ascending. To specify a descending sorting, you must send the character '-' as a prefix of the attribute. For example: /shipping/v1/?sort=status,-shipment_type.

The possible sorting attributes are:

  • shipment_type
  • status
  • status_detail

If a parameter is incorrect or misspelled, it will return an error.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Query Parameters
filter[shipment_type]string
Enum: SINGLE_CARDBOXCARD_FROM_WAREHOUSEWAREHOUSE_BOX
filter[batch_id]string
filter[email]string
filter[status]string
filter[batch_status]string
filter[document_number]string
filter[start_date]string
filter[end_date]string
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: pid, shipment_type, status, status_detail
Response details
idstring
Example: shi-23hJL4bm94q9BFEd2sGhBjY6xbH
external_tracking_idstring
Example: f923da123
statusstring
Enum: CREATEDPENDINGTRACKEDREJECTEDIN_WAREHOUSEIN_TRANSITDISTRIBUTIONDELIVEREDNOT_DELIVEREDSTART_OF_CUSTODYEND_OF_CUSTODYDESTRUCTIONACCIDENT
status_detailstring
Example: IN_TRANSIT
shipment_typestring
Enum: SINGLE_CARDBOXWAREHOUSE_BOXCARD_FROM_WAREHOUSEEXTERNAL_SINGLE_CARDEXTERNAL_BOX
affinity_group_idstring
Example: afg-20MpN8vmIPj77ujhb9cS8ctstN2
created_atstring
Example: 2020-07-10 15:00:00.000
batchobject
addressobject
receiverobject
Was this section helpful to you?
GET/shipping/v1/
Response examples

Get Shipping

The /shipping/v1/{shipment_id} endpoint allows you to get information about a particular shipment.

Considerations

You will need to specify the shipment_id to perform the query.

Envíos hacia un warehouse y en territorio mexicano:

Para los envíos hacia un warehouse y también para los que se realizan en México, no devolveremos un ID externo de seguimiento, ¡pero descuida! Te mantendremos informado sobre el estado del envío desde el Dashboard y también vía webhooks.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
shipment_idstringrequired
Shipment ID
Response details
dataobject
Was this section helpful to you?
GET/shipping/v1/{shipment_id}
Response examples

Transactions

You must implement and expose the “Authorization” and “ Adjustments” endpoints on your backend so that we can communicate.

Payment processor flow:

Flujo Online / Offline

We consume the endpoints in the following moments:

During the online flow

Every time a user uses their card in any online or physical store.

During reconciliation

When the network (Mastercard, Visa, etc.) requests reconciliation of all payments presented by merchants.

Considerations

If there is a discrepancy in the reconciliation, we will request a correction to your API. We expect a quick response to ensure a good experience. If the response is delayed, reject the transaction.

Idempotency

Since an HTTP request can time out, make sure that it is processed only once when retrying. We’ll send you an x-idempotency-key header with a unique ID with each request for that purpose. Process with a cache in memory (for example: redis).

At the beginning of each transaction, check if the idempotency key we sent you is already in the in-memory cache and do the following:

There is no idempotency header in the cache

Cache in memory the idempotency key → request with a in-transit status with a TTL of 3 minutes.

When you approve or reject the transaction, you’ll need to cache the result and update the idempotency key status to ‘finished’.

The idempotency header is in the cache

In case of a duplicate request, you will need to check the transaction status in the cache.

  • If it is in a finished status, respond with an HTTP code 200 with the expected body for the endpoint and complete it with the cache result.
  • If it is in a in-transit status you will need to respond with an HTTP code 425 (Too Early: RFC 8470) with the expected body for the endpoint. We’ll look for the response to this request again a few milliseconds later.

Security

The communication between our backends must be strictly secure since the endpoints will allow crediting and deducting funds.

For this purpose, we require you to implement three measures:

  • Expose HTTPS endpoint
  • Pomelo IPs whitelist
  • Hmac-sha256 signature for the request and reply

Expose HTTPS endpoint

All communication with us must be via HTTPS, regardless of who issues the certificate.

These are some of the most recognized providers

Pomelo IPs whitelist

We always communicate with your backend from specific IPs. We recommend that you only accept requests from the following IPs and reject any others:

Pomelo IPs:

  • Testing/Staging Environment:
34.226.254.178            
44.198.3.59
  • Production Environment:
34.206.159.176            
52.0.20.124

Hmac-sha256 signature for the request and reply

To ensure that the only participants in the communication are our backends (Pomelo and the Client), we provide you with an api-key and api-secret during onboarding to digitally sign the content of the communication.

The process looks something like this:

1. During onboarding we exchange the api-key and api-secret keys.

2.

During a payment authorization, Pomelo signs each authorization request with hmac-sha256 using the api-secret.

4. You validate the hmac-sha256 signature with your api-secret corresponding to the request api-key.

5. Authorize the order, debit the user’s funds and sign the response with hmac-sha256 using the api-secret.

6. We verify the hmac-sha256 signature and finish processing the payment.

Key exchange process

During the onboarding process, we create an api-key and api-secret specific to you.

It is also possible to use gpg or an email plugin (such as https://flowcrypt.com/).

Let’s look at an example using openssl on the command line.

1. We create the api-key and api-secret:

$ echo -e 'api-key=$(openssl rand -base64 32)\napi-secret=$(openssl rand -base64 32)' > api-credentials.txt

$ cat api-credentials.txt
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=

2. You create your public-private key:

$ openssl genrsa -out private.pem 2048
$ openssl rsa -in private.pem -pubout -out public.pem

3. Send us your public.pem public key by email or Slack.

4. We encrypt the credential file with the public key you gave us:

$ openssl rsautl -encrypt -in api-credentials.txt -out api-credentials.txt.enc -inkey public.pem -pubin

5. We send the api-credentials.txt.enc file by email or Slack

6. Decrypt the api-credentials.txt.enc file with your private.pem private key:

$ openssl rsautl -decrypt -in api-credentials.txt.enc -inkey private.pem
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=

7. Keep the api-secret in a safe place that is accessible only through the “Authorize payments” application, associated with the api-key.

Request signature process

Along with the authorization or adjustment request we’ll send you HTTP headers with the signature, timestamp and the api-key so that you can verify the signature is correct.

The HTTP headers we send are:

  • x-api-key : this header allows you to identify which api-secret you have to use in the event that multiple api-key and api-secret pairs have been configured.

  • x-signature : this header contains the digital signature (body + timestamp + endpoint) that you must verify to ensure request integrity. If the signature does not match, the order must be rejected.

  • x-timestamp : this header contains the moment the order was signed in unix-epoch format so that you can verify that the signature has not expired.

  • x-endpoint : the endpoint to which the request is made. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.

Let’s look at a sample curl indicating how this information is sent within the request:

curl --location --request POST 'localhost:9090/shipping/updates' \
--header 'x-api-key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=' \
--header 'x-signature: hmac-sha256 kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=' \
--header 'x-timestamp: 1637117179' \
--header 'x-endpoint: {clientPath}/shipping/updates'
--header 'Content-Type: application/json' \
--data-raw '{
    'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
    'meta' : {
        'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
    }
}'

To set up a signature you can use the following code snippet (in python 3) such as:

import hmac, hashlib, base64, time

############# Pomelo's side ################
############################################

# pomelo's secret key
pomelo_secret_key = base64.b64decode('kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=')

# the update data pomelo is gonna use to make the signature
pomelo_update_body = '{
    'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
    'meta' : {
        'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
    }
}'
client_req_endpoint = '/shipping/updates'
pomelo_timestamp = str(int(time.time()))

# the request data signed out by pomelo
pomelo_signature = hmac.new(pomelo_secret_key, bytes(pomelo_timestamp + client_req_endpoint + pomelo_update_body, 'utf-8'), hashlib.sha256).digest()


############# Client's side ################
############################################

# client's secret key
client_secret_key = base64.b64decode('kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=')

# client's api endpoint
client_api_endpoint = '/transactions/authorizations'

# signature expiration offset
signature_expiration_offset = 60 #A minute of expiration

# the authorizacion data the client needs to use to recreate the signature
client_request_data = bytes(pomelo_timestamp + client_req_endpoint + pomelo_update_body, 'utf-8')

# the signature the client has recreated
signature = hmac.new(client_secret_key, client_request_data, hashlib.sha256).digest()

# if signature is not expired and they match you can trust the request, otherwise reject it
now = int(time.time()) - signature_expiration_offset

signatureExpired = int(pomelo_timestamp) < now
signaturesMatch = hmac.compare_digest(signature, pomelo_signature)
endpointsMatch = client_api_endpoint in client_req_endpoint

requestIsValid = not signatureExpired and signaturesMatch


################ Results ###################
############################################

print('pomelo' signature = {0}'.format(base64.b64encode(pomelo_signature)))
print('client's signature = {0}'.format(base64.b64encode(signature)))
print('signature expired = {0}'.format(signatureExpired))
print('signatures match = {0}'.format(signaturesMatch))
print('endpoints match = {0}'.format(endpointsMatch))
print('request is valid = {0}'.format(requestIsValid))

Important: you will need to sign your body along with the timestamp and response endpoint with your api-secret after impacting the operation. Please note that the signature will be validated and the transaction rejected if the signature does not match or has expired.

Settlement

This is an optional process, but we recommend running it daily.

You will find these files in an S3 bucket that will be made available to you:

  • Transaction file
  • Presentation file

Transaction file

Contains the details of each transaction from the previous day. The file name has this format: presentationsyyyy_mm_dd.csv

Transaction file structure

{Atributo}DescriptionAllowed values
TRANSACTION_IDUnique ID to identify the transaction.
LOCAL_TRANSACTION_DATE_TIME
TRANSACTION_TYPEIndicates the transaction type.PURCHASE
WITHDRAWAL
EXTRACASH
REFUND
PAYMENT
REVERSAL_PURCHASE
REVERSAL_WITHDRAWAL
REVERSAL_EXTRACASH
REVERSAL_REFUND
REVERSAL_PAYMENT
PRODUCT_TYPEThis is the product typePREPAID
CREDIT
DEBIT
PROVIDERIt is the brand of the issued card.VISA
MASTERCARD
AFFINITY_GROUP_ID
USER_IDPomelo cardholder’s user ID.
CARD_ID
BINThe first six or eight digits of the PAN.
LAST_FOURThe last four digits of the PAN.
ORIGINDOMESTIC: The transaction occurred in the issuer’s country.
INTERNATIONAL: The transaction was not made in the issuer’s country.
MERCHANT_ID
MERCHANT_MCCThe merchant category code as defined in ISO-18245.
MERCHANT_NAME
LOCAL_AMOUNTThis is the total transaction amount that must be deducted from the user's balance, with taxes and fees added (where applicable). Always converted to the card's local currency.
LOCAL_CURRENCYThe LOCAL_TOTAL currency code in ISO_4217 ALPHA-3 format.
TRANSACTION_AMOUNTThe transaction value before taxes and in the original currency sent by the merchant.
TRANSACTION_CURRENCYThe TRANSACTION_TOTAL currency code in [ISO_4217] (https://en.wikipedia.org/wiki/ISO_4217#Active_codes) formato ALPHA-3.
SETTLEMENT_AMOUNTThe transaction amount in USD, as sent by the network. Domestic transactions also have this field in USD.
SETTLEMENT_CURRENCYThe SETTLEMENT_TOTAL currency code in ISO_4217 ALPHA-3 format is always USD.
ENTRY_MODEHow the card was used at the merchant's point of sale.UNKNOWN
MANUAL
CHIP
CONTACTLESS
CREDENTIAL_ON_FILE
MAG_STRIPE
OTHERS
STATUSTransaction status.APPROVED
REJECTED
HELD
STATUS_DETAILAdditional reason why the transaction is approved or rejected.See table below
SOURCEIndicates which flow/process triggered the transaction, as seen from Pomelo.ONLINE: Originated during transactional flow from real-time transactions sent over the network
CLEARING: Originated during the agreement process between Pomelo and the network when managing the settlement file
PURGE: Transactions that were not presented in the network settlement file.
ORIGINAL_TRANSACTION_IDThis value may be empty if the transaction is not related to another.
COUNTRY_CODEThis is the country code in [ISO-3166] format (https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).
POINT_TYPEPOS
ECOMMERCE
ATM
MOTO
CLIENT_NAMEEl nombre del cliente que aprueba o rechaza la transacción, dado que el reporte se segmenta por cliente, va a tener el mismo valor para todas las filas
CLIENT_COUNTRY_CODEEl coódigo de país del cliente en formato ISO-3166
INSTALLMENTS_GRACE_PERIOD[OPCIONAL*] El período de gracia refiere a la cantidad de meses previo a que comiencen los pagos en cuotas. Puede ir de 0 a 99.
INSTALLMENTS_QUANTITY[OPCIONAL*] La cantidad de cuotas
INSTALLMENTS_CREDIT_TYPE[OPCIONAL*] El tipo de crédito otorgadoNO_PROMOTION
WITHOUT_INTEREST
WITH_INTEREST
BUY_TODAY_PAY_LATER

*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.

STATUS_DETAIL table

Status detailDescription
CARD_BLOCKEDThe card status is BLOCKED.
CARD_DISABLEDThe card status is DISABLED
CARD_NOT_ACTIVEThe card status is EMBOSSED or CREATED
CARD_NOT_CONFIGUREDThe card is missing configurations.
CARD_NOT_FOUNDWe cannot find the card’s PAN.
CRYPTO_ERRORThere is a cryptogram error (EMV).
DUPLICATE_TRANSMISSION_DETECTEDWe received a repeated transaction from the network.
EXPIRED_CARDThe card status is EXPIRED.
EXTRA_FIELDSMessaging from the network comes with unexpected fields.
INSUFFICIENT_FUNDSThe client replies that the account has no funds.
INVALID_AMOUNTThe affinity group’s limits are exceeded.
INVALID_CVVThe CVV does not match.
INVALID_EXPIRATION_DATEThe expiration date received does not match the card.
INVALID_MERCHANTThe customer rejects the merchant for a specific reason.
INVALID_PINThe PIN is incorrect
INVALID_TRANSACTIONThe transaction is invalid.
LOST_CARDThe card status is LOST.
MISSING_FIELDSMessaging from the network comes without the required fields.
NOT_DECLINEDA transaction has a value of 0, verifying the account is active.
ORIGINAL_NOT_FOUNDAn attempt is made to reverse a transaction that we did not find.
OTHERThe case is not recognized.
RESTRICTED_USERThe user's status is not ACTIVE.
SECURITY_VIOLATIONExceeds a fraud threshold.
SERVICE_UNAVAILABLEThe client or a Pomelo service is down.
STOLEN_CARDThe card’s status is STOLEN.
SYSTEM_ERRORUnforeseen system error.
APPROVEDThe client approves a transaction.
TRANSACTION_NOT_PERMITTEDThe transaction type is not allowed in the affinity group.

Transaction file reconciliation

Is it at Pomelo?Is it at the client?Does it have the same status?Action
YYYDo nothing / Mark as matching
YYN1) Register an adjustment that debits/credits the end user if applicable.
2) Mark as matching.
YNN1) IF STATUS == APPROVED: Register an adjustment that debits/credits the end user if applicable.
2) Mark as matching.
NYNIt is not a possible use case.

If you are trying to adjust a credit to an end user who does not have sufficient funds in their account, keep trying to get the funds from that user.

It becomes a debt between the customer and the end user.

Presentation file

Contains the details for each transaction that traders submitted the previous day. The file name has this format: presentationsyyyy_mm_dd.csv

Presentation file structure

AttributeDescriptionAllowed values
PRESENTMENT_ID
TRANSACTION_IDThe original transaction ID the presentation generated.
LOCAL_TRANSACTION_DATE_TIME
TRANSACTION_TYPEIndicates the transaction type.PURCHASE
WITHDRAWAL
EXTRACASH
REFUND
PAYMENT
PRODUCT_TYPEThis is the product type.PREPAID
CREDIT
DEBIT
PROVIDERIt is the brand of the issued card.VISA
MASTERCARD
AFFINITY_GROUP_ID
USER_IDPomelo cardholder’s user ID
CARD_ID
BINThe first six or eight digits of the PAN.
LAST_FOURThe last four digits of the PAN.
ORIGINDOMESTIC: The transaction occurred in the issuer’s country.
INTERNATIONAL: The transaction was not made in the issuer’s country.
MERCHANT_ID
MERCHANT_MCCThe merchant category code as defined in ISO-18245.
MERCHANT_NAME
TRANSACTION_AMOUNTThe transaction value before taxes and in the original currency sent by the merchant.
TRANSACTION_CURRENCYThe TRANSACTION_TOTAL currency code in [ISO_4217] (https://en.wikipedia.org/wiki/ISO_4217#Active_codes) formato ALPHA-3.
SETTLEMENT_AMOUNTThe transaction value presented by the brand.
SETTLEMENT_CURRENCYThe SETTLEMENT_AMOUNT currency code in ISO_4217 ALPHA-3 format. If it is a domestic transaction it will be presented in local currency, otherwise in USD.
DEBT_AMOUNTThe transaction value in the currency to be paid to Pomelo. If the sum is to be paid to Pomelo, it is always a positive value; otherwise, it will be negative.
DEBT_CURRENCYThe DEBT_AMOUNT currency code in ISO_4217 ALPHA-3 format. If it is a domestic transaction it must be paid in local currency, otherwise in USD.
RECONCILIATION_DATE
INTERCHANGE_FEETransaction commission to be applied to the exchange.
INTERCHANGE_RATEAlphanumeric value that identifies the transaction exchange rate presented by the purchaser.
TAXThis is the exchange rate tax in accordance with local regulations. These values must have VAT calculated.
FUNCTION_CODEThis is the presentation type.FIRST_PRESENTMENT
SECOND_PRESENTMENT_FULL
SECOND_PRESENTMENT_PARTIAL
REVERSE_PRESENTMENTThis means that the presentation was reverted from the network.TRUE
FALSE
REASON_CODEReason for the second presentation.
ICA_ACQUIRER
TAX_IDID asociado a los impuestos de la transacción
INSTALLMENTS_GRACE_PERIOD[OPCIONAL*] El período de gracia refiere a la cantidad de meses previo a que comiencen los pagos en cuotas. Puede ir de 0 a 99.
INSTALLMENTS_QUANTITY[OPCIONAL*] La cantidad de cuotas
INSTALLMENTS_CREDIT_TYPE[OPCIONAL*] El tipo de crédito otorgadoNO_PROMOTION
WITHOUT_INTEREST
WITH_INTEREST
BUY_TODAY_PAY_LATER

*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.

Reconciling the presentation file

Our finance team will send daily notifications for the debt owed. This will include all presentations we receive in the presentation file.

Obtaining Transaction and Presentation files

There is an SFTP server from which you can download Transaction and Presentation files.

Pomelo has two environments for SFTP servers, production and development.

To connect to the SFTP servers, first send a public key to create a user.

Here is the data to connect to each environment:

Production Environment:

Host: sftp.pomelo.la
Port: 22
User: <tu_usuario> # the one created from your public keys.

Development:

Host: sftp-dev.pomelo.la
{Puerto}: 22
User: <tu_usuario> # the one created from your public keys.

To create a public key, use the command applicable to your operating system:

Linux / MacOs:

1. Create an RSA Key Pair, changing the variable $Cliente to the proper name

ssh-keygen -t rsa -b 2048 -C $Cliente

The command will create a 2048-bit RSA key pair by default. ​You can also create a larger 4096-bit key by entering -b 4096.

The command produces this output:

Generating public/prive rsa key pair.
Enter a file to save the key (/your_home/.ssh/id_rsa):

Press Enter to save the key pair in .ssh /, or specify another location.

2. Create a passphrase for your SSH key

Press Enter to leave it blank and use the key only to establish SSH connections. Enter a password for an additional layer of security.

3. Get the public key by reading the public file

cat ~/.ssh/id_rsa.pub

The key generated will start with ssh-rsa.

You can now copy and paste your public SSH key into your Shell console, or any server, to establish a secure connection.

Windows

Create SSH keys using PuTTY. Install PuTTY from the developer page: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

1. Create SSH keys using PuTTY

Install PuTTY from the developer page: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

2. Run the PuTTY SSH key generator

  • Press the Windows key.
  • Write puttygen.
  • Right-click on PuTTYgen.
  • Click Run as administrator.
  • Click Yes if the system asks you Do you want to allow this app to make changes to your device?

3. Use PuTTY to create an SSH key pair

While the PuTTY keygen tool offers several other algorithms, here is how to create RSA keys, one of the most often used:

  • In the PuTTY Key Generator window, click Build.
  • Move the cursor in the gray box to fill the green bar.
  • Generating an SSH key pair in Putty.
  • Save the public key by clicking the Save Public Key button. Then choose a location to save the key and assign a name to it.
  • Save the private key:
    • Click the Conversions menu at the top.
    • Click Export OpenSSH Key.
    • The system will ask you if you want to save a key without a password. Click Yes.
    • Choose a location to save the key (usually the same folder as the public key).
    • Name the key (for example, putty_key).

Authorize transaction

The /transactions/authorizations endpoint allows you to authorize transactions.

A request to authorize or reject the transaction will be sent.

Considerations

We expect a quick response to ensure a good experience. If the response is delayed, reject the transaction.

Available parameters
Body Parameters
transactionobjectrequired
Transaction-related information
merchantobjectrequired
Merchant-related information.
cardobjectrequired
Non-sensitive card information.
installmentsobject
Information related to transaction fees. This parameter for purchase authorizations will only be received with credit card fees.
userobjectrequired
Information related to the user who made the transaction.
amountobjectrequired
Information related to the transaction amounts.
Response details
statusstring
A status telling us whether to approve or reject the transaction
Enum: APPROVEDREJECTED
messagestring
Descriptive message with the result of this operation
status_detailstring
Allows you to track the reason why the transaction was not approved
Enum: APPROVEDINSUFFICIENT_FUNDSINVALID_MERCHANTINVALID_AMOUNTSYSTEM_ERROROTHER
Was this section helpful to you?
POST/transactions/authorizations
{
"transaction":{
"id":
"ctx-200kXoaEJLNzcsvNxY1pmBO7fEx"
"type":
"PURCHASE"
"point_type":
"POS"
"entry_mode":
"MANUAL"
"country_code":
"ARG"
"origin":
"DOMESTIC"
"original_transaction_id":
"ctx-200kirg6qicg1qHSCbgaStrEHjI"
"local_date_time":
"2019-08-24T14:15:22"
}
"merchant":{
"id":
"string"
"mcc":
"string"
"address":
"string"
"name":
"string"
}
"card":{
"id":
"c-1625519392748E6XZBK"
"product_type":
"PREPAID"
"provider":
"MASTERCARD"
"last_four":
"1573"
}
"installments":{
"quantity":
"12"
"credit_type":
"NO_PROMOTION"
"grace_period":
"0"
}
"user":{
"id":
"u-1625758043579BAR6D4"
}
"amount":{
"local":{
...
}
"settlement":{
...
}
"transaction":{
...
}
"details":[
...
]
}
}
Response examples

Adjustments

The /transactions/adjustments/{type} endpoint allows you to make credit and debit adjustments to transactions.

A request informing you that the network (MC, VISA) forced an authorization will be sent.

Considerations

This endpoint is used during reconciliation and online flows, mainly to make adjustments during the settlement process and also in the event of returns.

Available parameters
Body Parameters
transactionobjectrequired
Transaction-related information
merchantobjectrequired
Merchant-related information.
cardobjectrequired
Non-sensitive card information.
installmentsobject
Information related to transaction fees. This parameter for purchase authorizations will only be received with credit card fees.
userobjectrequired
Information related to the user who made the transaction.
amountobjectrequired
Information related to the transaction amounts.
Path Parameters
typestringrequired
The type of operation to be executed on the user's balance. If it is a debit, the value must be deducted from the user's balance. If it is a credit, funds must be added to the user's balance. NOTE: Adjustments with very small values may be received. It is up to the customer whether they are shown in the user’s balance or not.
Enum: debitcredit
Response details
Was this section helpful to you?
POST/transactions/adjustments/{type}
{
"transaction":{
"id":
"ctx-200kXoaEJLNzcsvNxY1pmBO7fEx"
"type":
"PURCHASE"
"point_type":
"POS"
"entry_mode":
"MANUAL"
"country_code":
"ARG"
"origin":
"DOMESTIC"
"original_transaction_id":
"ctx-200kirg6qicg1qHSCbgaStrEHjI"
"local_date_time":
"2019-08-24T14:15:22"
}
"merchant":{
"id":
"string"
"mcc":
"string"
"address":
"string"
"name":
"string"
}
"card":{
"id":
"c-1625519392748E6XZBK"
"product_type":
"PREPAID"
"provider":
"MASTERCARD"
"last_four":
"1573"
}
"installments":{
"quantity":
"12"
"credit_type":
"NO_PROMOTION"
"grace_period":
"0"
}
"user":{
"id":
"u-1625758043579BAR6D4"
}
"amount":{
"local":{
...
}
"settlement":{
...
}
"transaction":{
...
}
"details":[
...
]
}
}
Response examples

Core

The Core service lets you create and manage your users' digital accounts.

Requirements for creating an account

To have an account your users must:

  • Be registered with Pomelo.
  • Be in the “Active“ state.
  • Have their identity verified. We only perform this verification if you have purchased our Identity product.

Account lifecycle

The accounts status is one of the following:

  • ACTIVE: The account is active and can be used to make transactions normally. When an account is created its initial status will be ACTIVE.
  • FROZEN: The account can receive money but debit transactions are blocked.
  • DISABLED: No transactions are permitted for the account.
  • DELETED: The account is deleted and may not be reactivated.

To change an account status from ACTIVE to FREEZED, and DISABLED, use the PATCH endpoint.

To change an account status to DELETED, use the DELETE endpoint.

Possible error responses

If an operation fails, an error is returned with a list of possible associated operations:

  • ACCOUNT_VALIDATION_ERROR: The account could not be successfully validated. For example, when the idempotency key used in the request is already in use by another user.
    • CREATE
  • USER_VALIDATION_ERROR: The user’s identity could not be validated or does not exist.
    • CREATE
  • CLIENT_VALIDATION_ERROR: The customer belonging to the user you're trying to create an account for could not be identified.
    • CREATE
  • USER_ACCOUNT_LIMIT_REACHED: The user reached the limit of accounts that he can have, so a new one cannot be created.
    • CREATE
  • ACCOUNT_NOT_FOUND: The account ID does not exist.
    • UPDATE
    • DELETE
  • ACCOUNT_DELETED: The account ID was deleted.
    • UPDATE
    • DELETE
  • INVALID_ACCOUNT_STATUS: The account update status is invalid.
    • UPDATE
    • DELETE
  • LOCKED_ACCOUNT_STATUS: It is not possible to update an account modified from Pomelo.
    • UPDATE
    • DELETE
  • INVALID_UPDATE_STATUS_MOTIVE: The reason for updating the account status you entered is invalid. For DELETE the valid reasons are OTHER, INTERNAL_REASON, USER_REQUEST and FRAUD. For DISABLED are OTHER, LOST, INTERNAL_REASON, STOLEN, FRAUD and INHIBITION. For FROZEN are OTHER and SEIZURE
    • UPDATE
    • DELETE
  • ACCOUNT_HAS_FUNDS: It is not possible to delete an account that is not completely empty.
    • DELETE

Create account

The /core/accounts/v1 endpoint lets you create a digital account for a Pomelo user. If the account is created correctly, you will see status 201.
Available parameters
Header Parameters
X-Idempotency-Keystringrequired

Idempotent account creation identifier. This number is needed for each account you want to create. If two identical requests have the same idempotency id, only one account will be created, even if both receive a successful response.

Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
countrystringrequired
Account country.
Enum: ARGBRA
currencystringrequired
Account currency.
Enum: ARSBRL
metadataobject
This is an optional field to add any extra data you want.
Example: {"extra_property_1":"My value"}
user_idstringrequired
ID for the user who owns the account.
Example: usr-20I2tIqG3buTsvHKKORrtY2MkFH
Response details
dataobjectrequired
Was this section helpful to you?
POST/core/accounts/v1
{
"country":
"ARG"
"currency":
"ARS"
"metadata":{
"extra_property_1":
"My value"
}
"user_id":
"usr-20I2tIqG3buTsvHKKORrtY2MkFH"
}
Response examples

Delete Account

The /core/accounts/v1/{id} endpoint lets you delete a specific account. Its status will be changed to DELETED and can no longer be used to make transactions.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
status_update_motivestringrequired
Enum: OTHERINTERNAL_REASONUSER_REQUESTFRAUD
status_update_commentstring
This field is required when the status_update_motive is OTHER.
Example: Reason for updating the account status.
Path Parameters
idstringrequired
Example: acc-20I4qJinTCudWvJULZygeC257wy
Response details
dataobjectrequired
Was this section helpful to you?
DELETE/core/accounts/v1/{id}
{
"status_update_motive":
"OTHER"
"status_update_comment":
"Reason for updating the account status."
}
Response examples

Update account

The /core/accounts/v1/{id} endpoint helps you change an account status. Account status may be changed to ACTIVE, FROZEN, or DISABLED. For the last two, the reason for the change must be given, using the status_update_motive property.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
statusstringrequired
Enum: ACTIVEDISABLEDFROZEN
status_update_motivestring
This field is required when the status is not ACTIVE.
Enum: OTHERLOSTINTERNAL_REASONSTOLENFRAUDINHIBITIONSEIZURE
status_update_commentstring
This field is required when the status_update_motive is OTHER.
Example: Reason for updating the account status.
Path Parameters
idstringrequired
Example: acc-20I4qJinTCudWvJULZygeC257wy
Response details
dataobjectrequired
Was this section helpful to you?
PATCH/core/accounts/v1/{id}
{
"status":
"ACTIVE"
"status_update_motive":
"OTHER"
"status_update_comment":
"Reason for updating the account status."
}
Response examples

Queries

Accounts Query API is a service that groups all Pomelo digital account information and makes it available for consultation.

You can consult:

  • Account information. This information includes bank identifiers such as CVU and alias for Argentina or PIX for Brazil.
  • The balance for each account.
  • Activities for all your accounts.

What is an activity?

An activity is any operation that was intended to modify the account balance. In other words:

  • Transactions that changed an account balance.
  • Transactions that were processed but rejected. For example, debit transactions that could not be processed due to insufficient balance.
  • Transactions not processed because they do not meet some requirement. For example, card payment attempts that could not be processed because the CVV entered is incorrect.

Query API capabilities

  • List accounts with their respective balances.
  • Get information and balance for an account.
  • List activities for all accounts.
  • List activities for an account.
  • Get information about an activity.

List activities

The core/activities/v1 endpoint returns a paginated list of all activities. You can use filters to specify that only activities for a particular account are returned.
Available parameters
Header Parameters
Accept-Languagestring

Languages sorted according to your preference. Technical specification

Example: Accept-Language: en-US;q=1.0,en-*;q=0.5
Authorizationstringrequired
Example: Bearer {access_token}
Query Parameters
page[number]integer(format: int32)
Page number
page[size]integer(format: int32)
Page size
Example: 5
filter[country]string
Country of origin of the account.
Example: ARG
Enum: ARGBRAMEX
filter[account_id]string
ID of the account for which you want an activities list.
Example: acc-20I5vMjljS3VEyafcX8lA3T3g0c
filter[result]array
List of results of transactions associated with activities.
Example: APPROVED,PENDING,REJECTED
Enum: APPROVEDREJECTEDPENDING
filter[type]array
List of types of transactions associated with the activities you want to obtain in the list.
Example: CARD_PURCHASE,EXTRACASH
Enum: CARD_PURCHASEEXTRACASHCASHOUT_STORECASHOUT_ATMBANK_TRANSFER_INBANK_TRANSFER_OUTCASHOUTCASHINMANUAL_MOVEMENTCLIENT_PAYMENT
filter[created_from]string(format: date-time)
Base creation date for the activities you want in the list.
Example: 2021-12-30T14:47:30.969Z
filter[created_until]string(format: date-time)
Base creation date for the activities you want in the list.
Example: 2021-12-31T14:47:30.969Z
filter[updated_from]string(format: date-time)
Base update date for the activities you want in the list.
Example: 2021-12-30T14:47:30.969Z
filter[updated_until]string(format: date-time)
End update date for the activities you want in the list.
Example: 2021-12-31T14:47:30.969Z
filter[upsert_from]string(format: date-time)
Creation or base update date for the activities you want in the list.
Example: 2021-12-30T14:47:30.969Z
filter[upsert_until]string(format: date-time)
End creation or update date for the activities you want in the list.
Example: 2021-12-31T14:47:30.969Z
sortstring
Order you wish to apply to the list.
Example: -created_at,total_amount
Response details
metaobject
dataarray
Was this section helpful to you?
GET/core/activities/v1
Response examples

Get activity

The '/core/activities/v1/{id}' endpoint enables you to get information about any activity specified.
Available parameters
Header Parameters
Accept-Languagestring

Languages sorted according to your preference. Technical specification

Example: Accept-Language: en-US;q=1.0,en-*;q=0.5
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
idstringrequired
Response details
dataobjectrequired
Was this section helpful to you?
GET/core/activities/v1/{id}
Response examples

List Accounts

The '/core/accounts/v1' endpoint returns a paginated listing of digital accounts along with their balances.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Query Parameters
page[number]integer(format: int32)
Page number
page[size]integer(format: int32)
Page size
Example: 5
filter[country]string
Country of origin of the account.
Example: ARG
Enum: ARGBRAMEX
filter[status]array
State of the accounts that you want to obtain in the list.
Example: ACTIVE,DISABLED,DELETED,FROZEN
Enum: ACTIVEDISABLEDDELETEDFROZEN
filter[user_id]string
User ID for accounts you wish to view.
Example: usr-20I2tIqG3buTsvHKKORrtY2MkFH
filter[created_from]string(format: date-time)
Base creation date for the activities you want in the list.
Example: 2021-12-30T14:47:30.969Z
filter[created_until]string(format: date-time)
Base creation date for the activities you want in the list.
Example: 2021-12-31T14:47:30.969Z
sortstring
Order you wish to apply to the list.
Example: -created_at,balance
Response details
metaobject
dataarrayrequired
Was this section helpful to you?
GET/core/accounts/v1
Response examples

Get account

The '/core/accounts/v1/{id}' endpoint returns the account information requested, along with the balance.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
idstring(maxLength: 256, minLength: 0)required
Response details
dataobject
Was this section helpful to you?
GET/core/accounts/v1/{id}
Response examples

Transactions

This service allows you to authorize transactions.

There are two possibilities for the state of transactions created:

  • APPROVED: If the transaction is approved.
  • REJETED: If the transaction is rejected.

All transactions that are approved modify the account balance by the amount specified.

Todos los montos de las transacciones están expresados en la moneda de la cuenta y con signo positivo. Para distinguir si la intención de la transacción es ingresar o retirar dinero de una cuenta utiliza el parámetro entry_type. Este parámetro puede tomar estos valores:

  • DEBIT: for transactions withdrawing money from the account.
  • CREDIT: for transactions depositing money into the account.

All transactions have a type, indicated with the type parameter. Each type has different data sent along with the transaction in the tx_properties object.

You can request extra data from all transactions using the metadata object.

The details property may be used to break down the total transaction sum into its constituent parts. For example, suppose you are processing a transaction in a digital store totaling $149.99. Let us further suppose that this total is composed of:

  • $119.00 purchase
  • $40.00 taxes
  • -$10.00 discounts

This breakdown may be reported by adding multiple items to the details list. Each detail must have a type associated with it:

  • BASE: transaction base expense.
  • FEE: commission expenses.
  • TAX: Taxes.
  • EXTRACASH: money withdrawals.
  • DISCOUNT: Discounts.

More than one detail may be added with the same type. The only restriction is that the details total is equal to the transaction total.

Processing types

Each transaction has a process_type field that can take any of these values:

  • ORIGINAL: New transaction.
  • ADJUSTMENT: Settings.
  • REFUND: refund or return.
  • REVERSAL: Reversal.

For REFUND or REVERSAL transactions that are or can specify the original transaction they are based on. This transaction is known as a “parent transaction“, indicated by the parent_tx_id field.

Idempotency

Transaction authorization requests have an idempotency mechanism to prevent duplicate processing.

For the transaction to be processed you must accompany each authorization request with an X-Idempotency-Key header that has a unique identifier. If you do not get a response or receive one with status code type 5xx, repeat the request with the same idempotency key until you get a successful response (code 201).

Repeated requests using the same idempotency key will only result in a transaction being created. The first request creates the transaction and the next one gives the same response but does not create a new transaction.

If an authorization request has an idempotency key already used in another transaction, an error is returned.

Answers

Correctly processed transactions are reported with a status code 201. This status does not indicate whether the transaction was approved or not. Read the answer 'result' field and note if it is APPROVED or REJECTED.

Any other status code indicates that something went wrong and the reason for rejection is given in the rejection_reason field. This field may be filled out as follows:

  • INSUFFICIENT_FUNDS: The account does not have sufficient funds.
  • ACCOUNT_DISABLED: the account has been disabled.
  • ACCOUNT_FROZEN: The account cannot process debit transactions.
  • CLIENT_MONTHLY_AMOUNT_LIMIT_REACHED: exceeded the monthly movement limit it had.
  • CLIENT_DAILY_AMOUNT_LIMIT_REACHED: exceeded the limit of daily movements it had.
  • PROCESS_TIME_EXPIRED: The transaction did not start processing before the time indicated in the process_before field, which is optional.

When a transaction cannot be processed an error response is returned with the error_code field indicating the reason:

  • ACCOUNT_NOT_FOUND: account could not be found.
  • INVALID_AUTHORIZATION_REQUEST: The transaction authorization request is not valid.
  • INVALID_PARENT_TX_ID: The parent transaction specified is invalid.
  • DUPLICATED_IDEMPOTENCY_KEY: You already used the idempotency key in another transaction.

Authorize transaction

The /core/transactions/v1 endpoint allows you to authorize inbound and outbound money transactions from digital accounts. Successfully processed transactions will return status code 201, whether approved or rejected. Check the result field to see the result.
Available parameters
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
account_idrequired
ID de una cuenta de Pomelo
Example: acc-23GMRyaPjVbczjGtLfQ6zgUJmLv
typestringrequired
Transaction type.
Enum: CARD_PURCHASEEXTRACASHCASHOUT_STORECASHOUT_ATMBANK_TRANSFER_INBANK_TRANSFER_OUTCASHINCASHOUTMANUAL_MOVEMENTCLIENT_PAYMENT
process_typestringrequired
Used to indicate if the transaction is original, refund, reversal or adjustment.
Example: REFUND
Enum: ORIGINALADJUSTMENTREFUNDREVERSAL
parent_tx_id
ID de una transacción.
Example: atx-23GMkfOa7V1MqUlvEic4Dp7XhTT
dataobject
entry_typestringrequired
Indicates whether the transaction deposits or debits money from an account. CREDIT must be used to deposit money, and CREDIT to debit money.
Example: DEBIT
Enum: CREDITDEBIT
total_amountstringrequired
Total transaction amount.
Example: 999.99
process_beforestring(format: date-time)
This field is optional and gives a deadline for processing the transaction. It is useful for asynchronous flows.
Response details
idstringrequired
Example: atx-230ReKOtS2lv0yUi2FKG98ycdXZ
resultstringrequired
Example: REJECTED
Enum: APPROVEDREJECTED
rejection_reasonstring
Example: INSUFFICIENT_FUNDS
Enum: INSUFFICIENT_FUNDSACCOUNT_DISABLEDACCOUNT_FROZENMONTHLY_AMOUNT_LIMIT_REACHEDDAILY_AMOUNT_LIMIT_REACHEDCLIENT_MONTHLY_AMOUNT_LIMIT_REACHEDCLIENT_DAILY_AMOUNT_LIMIT_REACHEDPROCESS_TIME_EXPIREDSOURCE_ACCOUNT_TX_REJECTEDDESTINATION_ACCOUNT_TX_REJECTED
created_atstring(format: date-time)required
Was this section helpful to you?
POST/core/transactions/v1
{
"account_id":
"acc-23GMRyaPjVbczjGtLfQ6zgUJmLv"
"type":
"CARD_PURCHASE"
"process_type":
"REFUND"
"parent_tx_id":
"atx-23GMkfOa7V1MqUlvEic4Dp7XhTT"
"data":{
"description":
"{'es-AR':'Alguna descripción.','en-US':' ..."
"details":[
...
]
"metadata":
"{'custom-property': 'value'}"
}
"entry_type":
"DEBIT"
"total_amount":
"999.99"
"process_before":
"2022-05-20T13:02:35.147Z"
}
Response examples

Webhooks

This service notifies you of all account activities.

A notification may be an activity creation or modification. To determine which case it is, read the 'type' field, which will have one of the following:

  • ACTIVITY_CREATED: We notify you when a new activity is created.
  • ACTIVITY_UPDATED: We notify you when an activity is modified. Activities may have their status changed from 'PENDING' to 'APPROVED' or from 'PENDING' to 'REJECTED'.

Digital signature request verification process

Along with the notification, we will send a set of HTTP headers to verify its authenticity.

The HTTP headers we send are:

  • x-api-key : this header allows you to identify which api-secret you have to use in the event that multiple api-key and api-secret pairs have been configured.

  • x-signature : this header contains the digital signature that you must verify to ensure request integrity. If the signature does not match, the order must be rejected.

  • x-timestamp : this header contains the moment the order was signed in unix-epoch format so that you can verify that the signature has not expired.

  • x-endpoint : the endpoint to which the request is made. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.

The digital signature is an HMAC-SHA256 code constructed using the 'api-secret' and a series of bytes, composed of a concatenation of the timestamp, endpoint and request body coded in UTF-8.

The following is a pseudo-code to verify that the digital signature of a request is legitimate:

requestSignature = request.headers['x-signature'] signatureData = encode(request.headers['x-timestamp'] + request.headers['x-endpoint'] + request.body , 'UTF-8') recreatedSignature = hmac(apiSecret, signatureData, 'SHA256') validSignature = requestSignature == recreatedSignature

Activity notification

The following endpoint must be in the client service so that it can receive the requests of the activities created/updated. If the request returns an HTTP code of type 2xx, it will not be sent again and will be marked as Sent correctly. Otherwise, we will try again.
Available parameters
Header Parameters
X-Api-Keystringrequired
This header lets you identify which api-secret you have to use in the event that multiple api-key and api-secret pairs 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 request integrity. If the signature does not match, the order must be rejected.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
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ó.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
This header is used to regenerate the signature to be checked. Compare it with the service endpoint to verify that they match.
Example: X-Endpoint: /client/api/activities/updates
Body Parameters
typestringrequired
Process type of the activity.
Example: ACTIVITY_CREATED
versionstringrequired
Version number of the event.
Example: 1.0.0
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: act-20I2tIqG3buTsvHKKORrtY2MkFH
datetimestring(format: date-time)required
Event creation date.
Example: 2021-12-31T23:59:59.999Z
activityobject
Was this section helpful to you?
POST/<url-del-cliente>
{
"type":
"ACTIVITY_CREATED"
"version":
"1.0.0"
"idempotency_key":
"act-20I2tIqG3buTsvHKKORrtY2MkFH"
"datetime":
"2021-12-31T23:59:59.999Z"
"activity":{
"account":{
...
}
"origin_tx_id":
"atx-200mVjWAnL8tD4vlG3fexiQeWvN"
"origin":
"string"
"process_type":
"string"
"type":
"string"
"data":{
...
}
"total_amount":
"1200.15"
"entry_type":
"DEBIT"
"result":
"string"
"rejection_reason":
"string"
"rejection_message":{
...
}
"forced":
true
"created_at":
"2021-12-31T23:59:59.999Z"
"updated_at":
"2021-12-31T23:59:59.999Z"
}
}
Response examples

Cash Networks Argentina

This service allows you to integrate with different cash networks to query account information and be able to add money (cash in) or log cash withdrawal attempts (cash out intent).

To cash in, each account will have an alias that will allow you to identify it in a payment network. That alias is generated automatically and associated with the account when it is created.

For withdrawals, you will need to log a cash out intent, which, combined with the alias, you can use to withdraw cash from an account on the enabled payment networks.

CountryNetworkID
ArgentinaPago FácilPAGO_FACIL

Create cash in intent

The /networks/cash/v1/cashin/intents POST endpoint will allow you to generate a cash in attempt for a given account. Each attempt represents the intention to deposit money into an account’s balance through a payment network.

Considerations

There can only be one active attempt per account and network. The attempt is resolved when the withdrawal is actually made through a cash network or when the expiration date elapses. Creating a new attempt overwrites the previous attempt.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
account_idstringrequired
Account ID
Example: acc-20I4qJinTCudWvJULZygeC257wy
network_namestringrequired
Payment network identifier
Example: PAGO_FACIL
amountstring
Amount of income intent
Example: 397.67
Response details
dataobject
metaobject
Was this section helpful to you?
POST/networks/cash/v1/cashout/intents
{
"account_id":
"acc-20I4qJinTCudWvJULZygeC257wy"
"network_name":
"PAGO_FACIL"
"amount":
"397.67"
}
Response examples

List cash out intent

The GET /networks/cash/v1/cashout/intents/{account_id} endpoint allows you to get the latest current cash out intent. To consider a current cash out, the following conditions must be met:

  • It has not been used for a withdrawal.
  • It has not expired.
  • It has not been replaced by a new cash out intent.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
account_idstringrequired
Account ID
Example: acc-20I4qJinTCudWvJULZygeC257wy
Response details
dataobject
metaobject
Was this section helpful to you?
GET/networks/cash/v1/cashout/intents/{account_id}
Response examples

Get cash in alias

The GET /networks/cash/v1/alias/{account_id} endpoint will allow you to get the alias of an account. It is a unique value associated with the account, which will help you to perform a cash in operation in the payment network.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
account_idstringrequired
Account ID
Example: acc-20I4qJinTCudWvJULZygeC257wy
Response details
dataobject
metaobject
Was this section helpful to you?
GET/networks/cash/v1/alias/{account_id}
Response examples

Cash Networks Brazil

This service allows you to integrate with different cash networks to query an account’s data and record cash in intents for an account in a cash network.

To deposit funds, you must register a cash in intent in one of the enabled payment networks.

CountryNetworkID
BrazilBoletoBOLETO

Create cash in intent

The /networks/cash/v1/cashout/intents POST endpoint will allow you to generate a cash out intent for a given account.. Each attempt represents the intention to withdraw money from an account balance through a payment network.

Lifecycle

The attempt is resolved when the money deposit is actually performed through a cash network or when the expiration date is reached, whichever occurs first.

The attempt can have different statuses depending on which action has been applied to it::

  • ACTIVE: The attempt is active and you can use it until the expiration date ('expires_at').. After the expiration date, you will not be able to use that attempt to deposit money; you will have to generate a new one..
  • REJECTED: The integration with the cash network rejected the creation of the intent..
  • PAID: The intent was paid in full for the amount you requested..
  • PARTIALLY_PAID: The intent was partially paid, meaning that the sum of the payments made on behalf of this intent is less than the amount you requested.. It is possible to make partial payments until the expiration date of the intent..
  • CANCELLED: This status can be reached in different ways.. Firstly, if you canceled the intent with the cancellation endpoint or the cash network provider proactively cancels the intent you generated..
Available parameters
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
account_idstringrequired
Account ID
Example: acc-20I4qJinTCudWvJULZygeC257wy
networkstringrequired
Payment network identifier
Example: BOLETO
amountstringrequired
Amount of income intent
Example: 397.67
Response details
dataobject
Was this section helpful to you?
POST/networks/cash/v1/cashin/intents
{
"account_id":
"acc-20I4qJinTCudWvJULZygeC257wy"
"network":
"BOLETO"
"amount":
"397.67"
}
Response examples

Get cash in intent

The /networks/cash/v1/cashin/intents/{intent_id} GET endpoint will allow you to get all the data of a cash in intent through its ID.
Available parameters
Path Parameters
intent_idstringrequired
Cash in intent ID
Example: cin-20I4qJinTCudWvJULZygeC257wy
Response details
dataobject
Was this section helpful to you?
GET/networks/cash/v1/cashin/intents/{intent_id}
Response examples

Cancel Cash In Intent

El endpoint DELETE /networks/cash/v1/cashin/intents/{intent_id} te permitirá cancelar un cash in intent.
Available parameters
Path Parameters
intent_idstringrequired
Cash in intent ID
Example: cin-20I4qJinTCudWvJULZygeC257wy
Response details
dataobject
Was this section helpful to you?
DELETE/networks/cash/v1/cashin/intents/{intent_id}
Response examples

List cash in intents by account

The /networks/cash/v1/cashin/intents/account/{account_id} GET endpoint will allow you to list all the cash in intents of a particular account.
Available parameters
Query Parameters
filter[status]string
Status
Enum: ACTIVEREJECTEDPAIDPARTIALLY_PAIDCANCELLED
filter[date_from]string(format: date-time)
Fecha desde
filter[date_to]string(format: date-time)
Fecha hasta
page[number]integer(format: int32)
Page
page[size]integer(format: int32)
Page size
Example: 10
Path Parameters
account_idstringrequired
Account ID
Example: acc-20I4qJinTCudWvJULZygeC257wy
Response details
dataobject
Was this section helpful to you?
GET/networks/cash/v1/cashin/intents/account/{account_id}
Response examples

Argentine bank accounts

The Bank Account API service within the transfer flow is responsible for managing the bank attributes of the account and obtaining the information of a destination account when initiating a transfer.

Part of the attribute management of an account is the change of Alias. Each account is created with a CVU and an alias set by default, which may be modified by the user according to their preference.

As for obtaining information from a destination account, each transfer that is made begins with the validation of the destination account by using the CVU or alias. This service is responsible for performing this management and returning the destination account already validated with additional information of the holder (CBU, bank code, name and CUIT).

Get information about an account

Available parameters
Path Parameters
id-typestringrequired
Example: ALIAS
Enum: ALIASCBUCVU
id-valuestringrequired
Example: EVIL.DOG
Response details
dataobject
Was this section helpful to you?
GET/networks/bank/v1/transfers/destination-information/{id-type}/{id-value}
Response examples

Update account attributes

Available parameters
Body Parameters
keystring
Example: ALIAS
valuestring
Example: NUEVO.ALIAS
Path Parameters
account-idstringrequired
Response details
dataobject
Was this section helpful to you?
PATCH/networks/bank/v1/accounts/{account-id}
{
"key":
"ALIAS"
"value":
"NUEVO.ALIAS"
}
Response examples

Brazilian bank accounts

The Bank Account API service within the transfer flow is responsible for managing the bank attributes of the account.

Within the management of the attributes of an account is the ABM of the PIX key.

Considerations:

  • At the moment, we only have random keys available
  • It will be possible to create and delete unlimited random keys
  • You can have up to 5 active keys simultaneously

Obtener listado de llaves PIX

Available parameters
Path Parameters
account_idstringrequired
Example: acc-0ujsszgFvbiEr7CDgE3z8MAUPFt
Response details
dataobject
Was this section helpful to you?
GET/networks/bank/v1/accounts/{account_id}/keys
Response examples

Creación de llave PIX

Available parameters
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
account_idstring
Example: acc-0ujsszgFvbiEr7CDgE3z8MAUPFt
typestring
Example: EVP
Response details
dataobject
Was this section helpful to you?
POST/networks/bank/v1/key/pix
{
"account_id":
"acc-0ujsszgFvbiEr7CDgE3z8MAUPFt"
"type":
"EVP"
}
Response examples

Delete PIX key

Available parameters
Path Parameters
keystringrequired
Example: 41c2b4e0-9425-43a0-8087-b2d239f00b63
Response details
dataobject
Was this section helpful to you?
DELETE/networks/bank/v1/{account_id}/key/pix/{key}
Response examples

Transfers in Argentina

The transfer will be made by posting in the Transfer API, once the information of the destination account is validated by the Bank Account API service.

The transfer response can be synchronous or asynchronous. In the case of a synchronous response, the Transfer API service will return the final status of the transaction (SUCCESS or FAILED). If the response is asynchronous because it takes a few more seconds, the Transfer API service will return a pending status synchronously (IN_PROGRESS) and the notification of the final status of the transaction will be reported as Activity through the Core Webhooks service.

Make Transfer

Available parameters
Header Parameters
X-Idempotency-Keystring
Body Parameters
account_idstring(format: uuid)
Example: acc-14688cf5-1b2d-41b1-ba0d-9e669b8540b9
credit_accountobject
amountobject
conceptstring
Example: VAR
Enum: ALQAPCBRHBRNCUOEXPFACHABHONOINOIHPREROPSEGSISSONVAR
descriptionstring
Example: Pago
Response details
dataobject
Was this section helpful to you?
POST/networks/bank/v1/transfers
{
"account_id":
"acc-14688cf5-1b2d-41b1-ba0d-9e669b8540b9"
"credit_account":{
"tax_type":
"CBU"
"tax_value":
"1500633400063361138832"
}
"amount":{
"currency":
"ARS"
"value":
1050.5
}
"concept":
"VAR"
"description":
"Pago"
}
Response examples

Transfers in Brazil

The transfer is performed in 2 simple steps:

  • Validation of the target account using a PIX key (via the “Get Target PIX Key Information” endpoint)
  • With the information of the destination account you must perform the second step of the operation, which is to send the transaction itself (through the “Make Transfer” endpoint)

The transfer response can be synchronous or asynchronous. In the case of a synchronous response, the Transfer API service will return the final status of the transaction (SUCCESS or FAILED). If the response is asynchronous (because it takes a few more seconds), the Transfer API service will return a pending status synchronously (IN_PROGRESS) and the notification of the final status of the transaction will be seen as Activity through the Core Webhooks service.

Obtener información de llave pix destino

Available parameters
Path Parameters
account_idstringrequired
Sender account id
Example: acc-26AA71defpMZiKvkwk2fwkCRRYU
keystringrequired
Example: 22222222222
Response details
dataobject
Was this section helpful to you?
GET/networks/bank/v1/transfers/{account_id}/key/{key}
Response examples

Make Transfer

Available parameters
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
transaction_idstring
Example: tr-9c94e7ce-792e-11ec-90d6-0242ac120003
valuenumber
Example: 100
descriptionstring
Example: Teste de transferência
Response details
dataobject
Was this section helpful to you?
POST/networks/bank/v1/transfers/out
{
"transaction_id":
"tr-9c94e7ce-792e-11ec-90d6-0242ac120003"
"value":
100
"description":
"Teste de transferência"
}
Response examples

Identity

The Identity service lets you manage your users’ onboarding process in a flexible and simple manner, confirming their identity and preventing fraud.

Create session

The identity/v1/sessions endpoint lets you create a new identity validation session and returns a unique identifier for it.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Body Parameters
user_idstring(format: uuid)required
USER ID
Response details
dataobject
Was this section helpful to you?
POST/identity/v1/sessions
{
"user_id":
"a169451c-8525-4352-b8ca-070dd449a1a5"
}
Response examples

Search session

The /sessions endpoint allow you to perform a search with specific filters.

Considerations

Filters must be specified as parameters following this pattern: filter[field]=value. For example: filter[status]=IN_PROGRESS

The results will be paginated and you can specify the amount of data per page and also which page you wish to view.

Date range

There is a filter for the created_at field, which can be used to get sessions created within a date range. For example: filter[created_at][from]=2021-07-27&filter[created_at][to]=2021-07-28

Sorting

You can specify the order of the results with certain parameters that you must send as list of strings in the sort filter type. For example: ?sort=status,user_id

The default sorting will be ascending. To specify a descending sorting, you must send the character '-' as a prefix of the attribute. For example: ?sort=status,-user_id.

The possible ordering attributes are: user_id, status and created_at.

If a parameter is incorrect or misspelled, it will return an error.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Query Parameters
filter[user_id]string
filter[status]string
Example: CREATED
Enum: CREATEDIN_PROGRESSPROCESSINGREJECTEDNOT_VALIDATEDCANCELLED
filter[created_at][from]string
ISO 8601
Example: 1998-08-20
filter[created_at][to]string
ISO 8601
Example: 1998-08-20
page[size]number
page[number]number
Response details
dataarray
metaobject
Was this section helpful to you?
GET/identity/v1/sessions
Response examples

Get session

The identity/v1/session/{id} endpoint lets you get data from an identity validation session.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
uuidrequired
Session ID
Response details
dataobject
Was this section helpful to you?
GET/identity/v1/sessions/{uuid}
Response examples

Cancel Session

The identity/v1/sessions/{id} endpoint lets you cancel an identity validation session.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
uuidstring(format: uuid)required
Session ID
Response details
Was this section helpful to you?
DELETE/identity/v1/sessions/{uuid}
Response examples

Get session report

The identity/v1/sessions/{id}/report endpoint lets you obtain a user's data collected in an identity validation session.
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
uuidstringrequired
Response details
dataobject
Was this section helpful to you?
GET/identity/v1/sessions/{uuid}/report
Response examples

Webhooks

This service notifies you when an identity validation session is completed.

Digital signature request verification process

We send a set of HTTP headers to authenticate it along with the notification.

The HTTP headers we send are:

  • x-api-key : this header allows you to identify which api-secret you have to use in the event that multiple api-key and api-secret pairs have been configured.

  • x-signature : this header contains the digital signature (body + timestamp + endpoint) that you must verify to ensure request integrity. If the signature does not match, the order must be rejected.

  • x-timestamp : this header contains the moment the order was signed in unix-epoch format so that you can verify that the signature has not expired.

  • x-endpoint : the endpoint to which the request is made and used to generate the signature. Use this header to regenerate the signature to be validated, compare it with the endpoint of your service and verify that they match.

The digital signature is an HMAC-SHA256 code constructed using the 'api-secret' and a series of bytes, composed of a timestamp concatenation, endpoint and request body coded in UTF-8.

The following is a pseudo-code to verify that the digital signature of a request is legitimate:

requestSignature = request.headers['x-signature']
signatureData = encode(request.headers['x-timestamp'] + request.headers['x-endpoint'] + request.body , 'UTF-8')
recreatedSignature = hmac(apiSecret, signatureData, 'SHA256')
validSignature = requestSignature == recreatedSignature

Session completed notification

You must inform us of this endpoint to receive identity validation session completion notifications. You must return a type 2xx HTTP code so that the notification is not sent again. Otherwise, we will send it again.

Available parameters
Header Parameters
X-Api-Keystringrequired
This header helps you identify which api-secret to use if multiple api-key and api-secret pairs were configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header has the digital signature (body + timestamp + endpoint) to be verified to ensure request integrity. If the signature does not match, reject the order.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
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: /client/api/session/completed
Body Parameters
event_idstringrequired
Event identifier.
Example: identity-session-completed
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: 27Ky00tAZ0Rdi7G2Vt9iino8AYs
sessionobject
Identity validation session
Was this section helpful to you?
POST/identity/v1/<client-url>
{
"event_id":
"identity-session-completed"
"idempotency_key":
"27Ky00tAZ0Rdi7G2Vt9iino8AYs"
"session":{
"id":
"iss-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"status":
"CANCELLED"
}
}
Response examples