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

Payment processor flow:#

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.

Requests in progress#

If you receive a second request with the same idempotence ID and the first is still in progress, you should respond with an HTTP status 425 and an empty body.

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

• 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

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
34.223.185.46
100.20.205.117

• Production Environment:

34.206.159.176            
52.0.20.124
35.84.78.117
52.43.46.111

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 must be verified to ensure request integrity. If the signature does not match, reject the order.

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

Important: In addition to checking the signature that we send you, when generating the response, you must sign the body along with the timestamp and the 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.

How to Test Your Implementation and Sample Code#

You can test the implementation of your backend with some typical operations that we will send with a Postman collection, which is included in our [public sample repository] (https://github.com/pomelo-la/cards-transactions-examples). You can import the collection to a Postman instance and thus simulate real orders to your backend, including the signature generation and checking algorithm.

In the repository, you will also find examples of implementation of the signature generation and validation algorithm in several languages.

Settlement#

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

In the SFTP server that we will provide, you will find these files:

• Transaction file
• Presentation file

Transaction file#

Contains the details of each transaction from the previous day.

El nombre del archivo tiene el siguiente formato: transaction_yyyy-mm-dd_<nombre cliente>_<pais>.csv

Transaction file structure#

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

STATUS_DETAIL table#

Transaction file reconciliation#

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.

El nombre del archivo tiene el siguiente formato: presentment_yyyy-mm-dd_<nombre cliente>_<pais>.csv

Presentation file structure#

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