We implemented the OAuth 2.0 standard so you can communicate with our APIs with a single Bearer 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.

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.

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

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'
    }
}'

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

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.

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.

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))

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

During the online flow

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

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

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.

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.

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

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

These are some of the most recognized providers

• https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started-client-side-ssl-authentication.html
• https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html
• https://cloud.google.com/load-balancing/docs/ssl-certificates/google-managed-certs

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

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.

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.

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.

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

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

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

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.

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

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

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

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:

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

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:

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.

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).

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

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.

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.

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

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.

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.

• 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.

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.

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.

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.

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.