Security Considerations

• All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

• API requests without Payload-Signature will also fail.

• You will be able to hit our APIs only from the IPs you have previously whitelisted on the Merchant Panel.

Environments

All the integration must be performed on our STG environment, where you can perform your tests freely without risks of any kind.

When you sign up, we will generate you an account on our STG environment where you will be able to:

• See the transactions created

• Approve and cancel transactions

• Retrieve your API Keys

• Whitelist your IPs, and more

Endpoint domains

Each environment has its own domain. The path of the endpoints do not change.

API Keys

In order to authenticate, our Cashouts APIs uses API Keys in all of the requests to authenticate. Your API Keys can be retrieved from the Merchant Panel by going to Settings -> API Access -> Cashouts Credentials.

These are the three credentials you will need:

• Your user: API Key

• Your password: API Passphrase

• Your secret key to generate the signatures: API Signature

Authentication to the API is performed via HTTP Basic Auth. You must provide your API Keys in all requests as the basic auth username and password.

Your user and password keys must be sent in all the API calls using the API Key and API Passphrase fields on the body of the request.

Your API Keys, along with your IP Addresses are your way to authenticate yourself, therefore, do not share your credentials in publicly accessible areas such as GitHub, client-side code and so forth.

Headers

All requests sent through Cashouts v3 API must have the following headers.

IP Whitelisting

For security purposes, you need to whitelist the IPs from where you will call our API.

In order to whitelist your IPs and make the process as smoother as possible, you should go to Settings -> API Access and add the list of IPs you will possibly use under the Cashouts IP Address section.

Reach out to integration@zimo-pagos.com if you need to whitelist our servers IPs on your firewall.

Best Practices

We recommend you follow this list of technical and security practices to maximize the security of the information end-to-end.

1. Always ensure to verify the Signatures control string sent in the notifications to validate its veracity.

2. We convert all the data we receive to UTF-8. Make sure you are also converting it into UTF-8 to make sure both parties have the same details.

Go to the next page to learn how to generate the Payload-Signature control string to verify the requests' you send and receive integrity.

Calculating the Signature

All calls to our Cashouts APIs must contain a Payload-Signature field on the header used to ensure request integrity and to authenticate yourself since you will use your own API Signature (secret key) to generate and encrypt a hash.

It has to be created using HMAC-SHA-256 (RFC 2104) encoding and the payload is made of the entire JSON Payload sent in the body of the requests and notifications.

The Payload-Signature field on the header of the requests will contain the hash generated from hashing the entire JSON Payload:

Payload-Signature: HMAC256(jsonPayload)

Example:

Payload-Signature: 223a9dd4784726f1536c926da7dc69155a57612c5c3c1e1b429c367a5eee67cf

​

​

Notes

The Payload-Signature value is case sensitive and must be sent in lower case.

In case the jsonPayload value is empty, use an empty string instead.

The jsonPayload should be converted to UTF-8 before hashing it to prevent Invalid Signature error when sending characters with different encodings.

​

Examples

Check the examples below on how to calculate the Payload-Signature.

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.net.util.Base64;

String json_payload = "{ \"login\": \"cashout_API_Key\", \"pass\": \"cashout_API_Passphrase\",   \"external_id\": \"123456789\",  \"document_id\": \"1234567899\",  \"document_type\": \"\",   \"cashout_type\": \"BANK\", \"beneficiary_name\": \"Test User\", \"beneficiary_lastname\": \"Test User\",  \"country\": \"MX\",  \"amount\": 2000,  \"currency\": \"MXN\",  \"email\": \"test@test.com\", \"notification_url\": \"http:\\/\\/zimo-pagos.com\\/notification\",  \"bank_code\": \"072\",\"bank_branch\": \"\",  \"bank_account\": \"1234567890\", \"account_type\": \"C\", \"address\": \"\"}";
String secretKey = "cashout_secret_key";
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));
String payload_signature = Base64.encodeBase64String(hasher.doFinal(json_payload.getBytes())).toLowerCase();

<?php
$json_payload = '{
"login": "cashout_API_Key",
"pass": "cashout_API_Passphrase",
"external_id": "123456789",
"document_id": "1234567899",
"document_type": "", 
"cashout_type": "BANK",
"beneficiary_name": "Test User",
"beneficiary_lastname": "Test User",
"country": "MX",
"amount": 2000,
"currency": "MXN",
"email": "test@test.com",
"notification_url": "http://www.zimo-pagos.com/notification",
"bank_code": "072",
"bank_branch": "",
"bank_account": "1234567890",
"account_type": "C",
"address": ""
}';
$secretKey = "cashout_secret_key";
$payload_signature = strtolower(hash_hmac('sha256', pack('A*', $json_payload), pack('A*', $secretKey)));
?>

using System;
using System.Text;
using System.Security.Cryptography;

string jsonPayload = "{ \"login\": \"cashout_API_Key\", \"pass\": \"cashout_API_Passphrase\",   \"external_id\": \"123456789\",  \"document_id\": \"1234567899\",  \"document_type\": \"\",   \"cashout_type\": \"BANK\", \"beneficiary_name\": \"Test User\", \"beneficiary_lastname\": \"Test User\",  \"country\": \"MX\",  \"amount\": 2000,  \"currency\": \"MXN\",  \"email\": \"test@test.com\", \"notification_url\": \"http:\\/\\/www.zimo-pagos.com\\/notification\",  \"bank_code\": \"072\",\"bank_branch\": \"\",  \"bank_account\": \"1234567890\", \"account_type\": \"C\", \"address\": \"\"}";
string secretKey = "cashout_secret_key";        
byte[] keyByte = new ASCIIEncoding().GetBytes(secretKey);
byte[] jsonPayloadBytes = new ASCIIEncoding().GetBytes(jsonPayload);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(jsonPayloadBytes);
string payloadSignature = BitConverter.ToString(hashmessage).Replace("-", "").ToLower();