We work as a bridge between you and your customer's local payment methods such as banks, e-wallets, credit cards among others.

With only one integration, you have access to the most popular payment methods in the emerging markets.

In order to make that possible, we have developed our API v3 of Deposits allowing you to create payments directly from your own cashier or from one of ours in case you want us to take care of the fields needed for each country and payment method.

Solutions

Our API v3 of deposits is meant to be used on the way that fits best to your needs and technical requirements.

With only one API, you can opt for different integrations:

1. OneShot Experience: You collect, validate and send all the details required for the payment, and you display the payment's metadata directly on your website or redirect the customers to the payment page.

2. Hosted Checkout Experience: We take the user to a checkout page to complete missing payment details manually. This flow is triggered as Oneshot experience fallback flow.

3. V3 PCI: You collect and send to us the Credit Card details for processing. The payment is approved/rejected instantaneously. A PCI certificate is required for this integration.

OneShot Experience

The OneShot Experience is an integration where you send all the details required for the deposit and the customer itself and we will return you the metadata of the payment for you to build the payment page on your own website or a URL to redirect the customer to the payment page!

We call it OneShot because the customer only has to generate the payment on your cashier and pay.

This integration offers a more personalized user experience, as the user won't leave your site but for pay (if at all).

In order to make the payment creation process as smoother as possible and to avoid errors, in case you don't send a field that is required for the payment method/country, we will take care of it by asking the missing information to the customer on our Hosted Checkout instead of declining the payment😉 .

Flow

Hosted Checkout Experience (Not available for new integrations)

The Hosted Checkout Experience is an integrating solution where you only need to send basic details about the deposit itself, and we will generate a link you will use to redirect your customers to our Hosted Checkout where we will prompt them for any missing details like the payment method, the document, email and full name.

Once integrated, adding new payment methods and countries with this integration requires no further development on your end since we will take care of the user experience!

With this integration, you only need to send the amount and the country of the deposit and we will handle the rest. The customers will be able to choose the payment method on our Checkout, input their data and pay.

The Hosted Checkout Experience, allows you to personalize our Checkout by sending details like the payment_type to group our payment methods on different sections of your page, the bonus_amount or a strikethrough_amount to show a promo on our Hosted Checkout, the description to show them what they are paying for or even your own logo so the customer can see it on our Hosted Checkout. All of that, with only one integration described here.

Flow

V3 PCI for Credit Cards Processing

The API V3 PCI for Credit Cards Processing allows you to build your own Credit Card checkout form to collect and send to us the customer's credit card details, allowing for a Seamless experience without redirecting the customer to an external checkout.

Flow

Getting Started

Follow this steps to start processing payments with the Zimopagos Deposits API:

1 - Sign Up: Create your merchant account in our Merchant Panel.

2 - Get Credentials: After your account has been activated, you will have access to your Staging (STG) Merchant Panel where you will need to

• Whitelist your IPs

• Retrieve your API Keys

Than can be done by going to Settings -> API Access.

3 - Integrate the APIs: Follow the instructions over this documentation to integrate our Deposits APIs.

In order to move your account from STG to PRODUCTION, there are a few tests you need to check you are able to do:

• Create deposits

• Manually approve and cancel (at least) one deposit from the STG Merchant Panel

• Make sure you are receiving and handling our notifications correctly in your site according to response statuses and reject codes

• Use the Payment Methods endpoint to retrieve payment methods availability

4 - Go Live: Once you have completed the tests required in step 3, Request Go Live on the Home of the STG Merchant Panel to generate your account in our Production environment.

We will review your tests, if everything is fine you will receive an email to activate your account on our production environment. In case there is something missing, we will let you know!

5 - Process payments: Get the production credentials, whitelist your IPs on the production environment and start processing your payments with Zimopagos!

Don't get stuck! In case you have any technical doubts not covered on this documentation, reach out to [email protected] for assistance.

Postman collection

In order for you to start testing our Deposits APIs right away, we have prepared a Postman Collection you can use to test and validate your integration along with the functionalities we offe

Here you will find all you need to know to integrate our products to start sending and receiving payments from your customers.

Payments Processing APIs

Our main Payment Processing APIs are listed below. Within each one of them you may find resourceful endpoints to consume and build a seamless integration.

Payment Methods

You can retrieve the payment methods your account has enabled by using the

On the Merchant Panel you can check what Payment Methods your account has enabled by going to the "Payment Methods" section on the left menu. The Payment Method availability is real time updated on the panel.

Considerations

1. Notice that not every payment method is available in Staging. Check on each country's table the available ones.

2. Some methods may not be available within an iframe due to our processor's security requirements. Check on each country's table the available ones. In those cases, we will ask the customer to open the payment page on a new window.

3. The checkouts may differ between STG and PROD in the cases we use different providers.

Flows

Some payment methods allows you to display the payment information directly on your website, without having to redirect the customer to an external website. Those methods are so called "ONE_SHOT" and are part of our . When creating a payment of this kind, we will return you all the fields you need to display to your customer on a and a URL to redirect the customer in case the payment requires so.

In case the flow is "REDIRECT", we will generate a link so that you can redirect the customer to the page where they will insert any missing details and see the payment instructions.

V3 Cashouts API Integration

Cashout Flow

Find below the description of a cashout flow using the D24 cashouts integration:

1 - Upon your customer's request, you submit a cashout request through the Cashout-Request API or through the Merchants panel (Transactions -> Withdrawals -> Request Cashout).

2 - Initial validations are performed by the API, such as:

• Merchant account balance enough to cover the cashout

• Merchant account Transaction/Daily/Monthly limits permit the cashout

• Destination Bank Account details are correct.

• Customer's details are correct. Eg. Document ID

3 - If the previous step is correct, the cashout is created and remains on PENDING status, otherwise, it's DECLINED. If Pending, it will be then sent to the bank for processing, when that happens, the status is set to DELIVERED.

4 - Once the transaction comes back from the bank, it can be either COMPLETED or REJECTED (by the bank).

There are some cases in which the bank could Confirm the Cashout and then Reject it because the destinatary's bank account was, for any reason, unable to receive the funds. This is a corner case but should be considered when integrating.

Postman collection

In order for you to start testing our Cashouts APIs right away, we have prepared a Postman Collection you can use to test and validate your integration along with the functionalities we offer

Refunds status notifications

Every time a refund changes its status, we will send you an asynchronous notification to the notification_url you sent in the refund request or the one you have configured under the section "Settings -> API Access" of our Merchant Panel containing the ID of the refund.

Once received the notification, you should check its new status with the and update it on your end accordingly.

Notifications fields

Notifications example

Retry logic

Every time a refund changes its status, we will send you a notification so you can back.

In case that for some reason your server was unable to receive the notification and you returned an HTTP code different than 200, we will retry the notification up to 5 more times or until you respond with HTTP 200, whatever comes first.

The time between each of the 5 notifications attempts will be exponential: 5, 25, 125 and 625 minutes accordingly.

When the notifications fails to be sent, it will be shown like this in our Merchant Panel:

If you see the errors from the screenshot above, it means the refund was successfully completed and the money reached the customer's account/card but suddenly we couldn't notify you. Keep reading to know how to resend the notifications.

Resend Notifications

In case your system was unable to receive the notification in any of the 5 attempts, you can always check its status with the

If you need to trigger the check status by receiving our notification, once the issue preventing you from receiving our notifications was fixed, you can go to the Merchant Panel, locate the refund and click on the three dots button under the "Status History" section and then "Resend notification" to force a new notification to be sent.

Introduction

Check the cashouts requirements and validations made over each country in which we operate on.

American Countries

Deposit status notifications

Every time a deposit changes its status, we will send you an asynchronous notification to the notification_url you sent in the request or the one you have configured under the section "Settings -> API Access -> Confirm URL" containing the ID of the deposit.

Once received the notification, you should check its new status with the Deposit Status Endpoint and update it on your end accordingly.

STG Testing

In the STG environment, in order to test the full flow you can manually set a deposit to COMPLETED / CANCELLED status by login into the STG Merchant Panel and going to Transactions -> Deposits. Those options will change the status of the deposit, therefore sending the respective notification to your notification_url after a few minutes.

Notifications fields

Notifications example

{
    "deposit_id": 3000000001
}

Retry logic

Every time a deposit changes its status, we will send you a notification so you can check its status back.

In case that for some reason your server was unable to handle our notification and you returned an HTTP code different than 2XX, we will retry the notification up to 5 more times or until you respond with HTTP 2XX, whatever comes first.

The time between each of the 5 notifications attempts will be exponential: 5, 25, 125 and 625 minutes accordingly.

When a notification failed to be sent, it will be shown like this in our Merchant Panel:

If you see the errors from the screenshot above, it means the payment was successfully completed and the money was credited to your account but suddenly we couldn't notify you. Keep reading to know how to resend the notifications.

Resend Notifications

In case your system was unable to handle the notification in any of the 5 attempts, you can always check its status with the Deposit Status Endpoint.

If you need to trigger the check status by receiving our notification, once the issue preventing you from receiving our notifications was fixed, you can go to the Merchant Panel, locate the deposit (Transactions -> Deposits) and click on the three dots button under the "Status History" section and then "Resend notification" to force a new notification to be sent.

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.

Calculating the Signature

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

It has to be created using HMAC-SHA-256 (RFC 2104) encoding and the payload must include the following details:

X-Date + X-Login + JSONPayload

The Authorization field on the header of the requests will contain the string "ZIMOPAGOS " plus the hash generated, in the following format:

Authorization: "ZIMO" + HMAC256(X-Date + X-Login + JSONPayload)

Example:

Authorization: ZIMO 223a9dd4784726f1536c926da7dc69155a57612c5c3c1e1b429c367a5eee67cf

Notes

The X-Login is your login API Key, it can be retrieved from the Merchant Panel by going to Settings -> API Access -> Deposit credentials -> API Key.

The X-Date is the date in ISO8601 Datetime with Timezone. Format expected: ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ. E.g.: 2020-06-21T12:33:20Z.

The Authorization value is case sensitive and must include all the above mentioned values.

The JSONPayload is the exact same JSON you sent in the body of the request.

In case the JSONPayload value is empty (for example in the status or payment methods endpoints), 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 in the different languages on how to properly calculate the Signature.

You can also check the code of our SDKs in Java and PHP to see how it is calculated.

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Formatter;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public static final String AUTHORIZATION_SCHEME = "ZIMO ";

private static final String HMAC_SHA256 = "HmacSHA256";

public static String buildDepositKeySignature(String apiSignature, String xDate, String depositKey, String JSONPayload)
      throws NoSuchAlgorithmException, InvalidKeyException, IOException {
   byte[] hmacSha256 = null;
   Mac mac = Mac.getInstance(HMAC_SHA256);
   SecretKeySpec secretKeySpec = new SecretKeySpec(apiSignature.getBytes(StandardCharsets.UTF_8), HMAC_SHA256);
   mac.init(secretKeySpec);
   hmacSha256 = mac.doFinal(buildByteArray(xDate, apiKey, JSONPayload));
   return AUTHORIZATION_SCHEME + toHexString(hmacSha256);
}

private static byte[] buildByteArray(String xDate, String apiKey, String JSONPayload) throws IOException {
   ByteArrayOutputStream bos = new ByteArrayOutputStream();
   bos.write(xDate.getBytes(StandardCharsets.UTF_8));
   bos.write(apiKey.getBytes(StandardCharsets.UTF_8));
   if (JSONPayload != null) {
      bos.write(JSONPayload.getBytes(StandardCharsets.UTF_8));
   }
   return bos.toByteArray();
}

private static String toHexString(byte[] bytes) {
   Formatter formatter = new Formatter();
   for (byte b : bytes) {
      formatter.format("%02x", b);
   }
   return formatter.toString();
}

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

namespace Application 
{

    class Directa24Example 
    {
    
        public readonly static string AUTHORIZATION_SCHEME = "ZIMO";
        
        private readonly static string HMAC_SHA256 = "HmacSHA256";
        
        public static String buildDepositKeySignature(String apiSignature, String xDate, String depositKey, String jsonPayload)
        {
            byte[] hmacSha256 = null;
            var apiSignatureEncod = Encoding.UTF8.GetBytes(apiSignature);
            var hash = new HMACSHA256(apiSignatureEncod);
            hmacSha256 = hash.ComputeHash(buildByteArray(xDate, depositKey, jsonPayload));  
            return AUTHORIZATION_SCHEME + toHexString(hmacSha256).ToLower();
        }
        
        private static byte[] buildByteArray(String xDate, String apiKey, String jsonPayload)
        {
            try
            {
                MemoryStream stream = new MemoryStream();
                var xDateEncod = Encoding.UTF8.GetBytes(xDate);
                var apiKeyEncod = Encoding.UTF8.GetBytes(apiKey);
                stream.Write(xDateEncod, 0, xDateEncod.Length);
                stream.Write(apiKeyEncod, 0, apiKeyEncod.Length);
                if (!string.IsNullOrWhiteSpace(jsonPayload))
                {
                    var jsonPayloadEncod = Encoding.UTF8.GetBytes(jsonPayload);
                    stream.Write(jsonPayloadEncod, 0, jsonPayloadEncod.Length);
                }
                return stream.ToArray();
            }
            catch (Exception ex)
            {
                throw ex;
            }
        }
        
        private static string toHexString(byte[] bytes)
        {
            return BitConverter.ToString(bytes).Replace("-", string.Empty);
        }
    }
}

<?php

class ZimoExample {
 
	const AUTHORIZATION_SCHEME = "ZIMO";
	const HMAC_SHA256 = 'sha256';
	
	
	public static function build_deposit_key_signature($api_signature, $x_date, $deposits_api_key, $json_payload) {
		
		// Concatenate the content of the header X-Date, your deposits API Key (X-Login) and 
		// the whole JSON payload of the body of the request
		$string = $x_date . $deposits_api_key . $json_payload;
		
		// Generate the HASH by using yur own deposits API Signature and 
		// concatenate "D24 " in front of the hash
		return  self::AUTHORIZATION_SCHEME . hash_hmac(self::HMAC_SHA256, $string, $api_signature);
	
	}

}

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 [email protected] 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.

Cashout Cancellation Endpoint

DELETE https://api-stg.Zimo-pagos.com/v3/cashout/cancel

This API allows you to cancel a cashout request. Only for cashouts in PENDING state.

Headers

Request Body

Cancel Cashout Request

The Cancel Cashout Request endpoint is only to cancel a cashout while it is still in PENDING state (it hasn't been sent for processing).

To do that, you will need to provide both the cashout ID on our end and the external ID you sent while creating the cashout.

Request Example

Request Fields

Request Payload Signature

The Payload-Signature of the Cashout Status Endpoint is calculated by hashing the JSON payload of the request using HMAC256 and your secret key (API Signature) to encrypt it.

for further instructions.

Cancel Cashout Response

Response Example

Response fields

Notifications

A notification will be sent every time the status of a cashout changes.

For security reasons we don't send the status of the cashout on the notification itself. Once you have received the notification, you will need to use the Cashout Status Endpoint to retrieve its new status.

The notifications will be sent to the notification_url specified in the request or to the default Withdrawals URL you have configured on the Merchant Panel by POST protocol in x-www-form-urlencoded format and will have the following fields:

STG Testing

In the STG environment you can force a notification to be sent to your notification_url from the STG Merchant Panel by going to the Transactions -> Withdrawals page, opening the cashout transaction and clicking on one of the options that will appear when clicking in the three dots button on the top right of the screen. Those options will change the status of the cashout therefore sending the respective notification after a few minutes.

Example Notifications

    date=2020-03-12%2020%3A26%3A11
    &bank_reference_id=
    &comments=
    &external_id=cashoutV35381
    &control=A4CFF64E78C4BD01F8BFCA4AFF04632EC4A33CC61BD6BBD156BA1289897892EB
    &cashout_id=60067
    &status_reason=

Control String

The control string for the notifications is made up of some random characters at the beginning and the end of the request and the external_id received in the middle.

Check the examples below on how to calculate the control string for the notifications:

public static void main(String[] args) throws IOException, NoSuchAlgorithmException, InvalidKeyException {
      String external_id = "cashoutID1234";
      String message = "Be4" + external_id + "Bo7";
      String apiSignature = "your_deposits_api_signature";

      Mac hasher = Mac.getInstance("HmacSHA256");
      hasher.init(new SecretKeySpec(apiSignature.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
      byte[] result = hasher.doFinal(message.getBytes(StandardCharsets.UTF_8));

      System.out.println(StringUtils.upperCase(DatatypeConverter.printHexBinary(result)));
}

$external_id = 'cashoutID1234';
$message = 'Be4' . $external_id . 'Bo7';
$api_signature = 'cashout_api_signature';

$hash = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $api_signature)));

 string external_id = "cashoutID1234";
 string message = "Be4" + external_id + "Bo7";
 string apiSignature = "your_cashouts_api_signature";
 
 byte[] keyByte = new System.Text.Encoding.UTF8.GetBytes(apiSignature);
 byte[] messageBytes = new System.Text.Encoding.UTF8.GetBytes(message);
 byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

 string control = BitConverter.ToString(hashmessage).Replace("-", "").ToUpper();
 

Retry logic

Every time a cashout changes its status, we will send you a notification so you can check its status back.

In case that for some reason your server was unable to receive the notification and you returned an HTTP code different than 2XX, we will retry the notification up to 5 more times or until you respond with HTTP 2XX, whatever comes first.

The time between the 5 notifications attempts will be of 5 minutes each.

When the notification failed to be sent, it will be shown like this in our Merchant Panel:

If you see the errors from the screenshot above, it means the cashout was successfully completed but suddenly we couldn't notify you. Keep reading to know how to resend the notifications.

Resend Notifications

In case your system was unable to receive the notification in any of the 5 attempts, you can always check its status with the Cashout Status Endpoint.

If you need to trigger the check status by receiving our notification, once the issue preventing you from receiving our notifications was fixed, you can go to the Merchant Panel, locate the cashout (Transactions -> Withdrawals) and click on the three dots button under the "Status History" section and then "Resend notification" to force a new notification to be sent.

Cashout Status Endpoint

POST https://api-stg.zimo-pagos.com/v3/cashout/status

This API allows you to retrieve the status of a cashout

Headers

Request Body

{
    "cashout_status": 1,
    "cashout_status_description": "Completed"
}

{
    "cashout_status": 3,
    "cashout_status_description": "Rejected",
    "rejection_code": 0,
    "rejection_reason": "Test"
}

{
    "code": 401,
    "message": "Invalid credentials."
}

{
    "code": 509,
    "message": "Cashout not found with this ID"
}

Cashout Status Request

Request Example

// HEADERS
Content-Type: application/json 
Payload-Signature: 2e5023770760ea0a02230bff1a6dab934fe3b47a5e3d43854b58676600ee3868 

// BODY
{ 
    "login": "cashout_login", 
    "pass": "cashout_pass", 
    "cashout_id": 11954 
}

Request Fields Description

Request Payload Signature

The Payload-Signature of the Cashout Status Endpoint is calculated by hashing the whole JSON payload of the request using HMAC256 and your secret key (API Signature) to encrypt it.

Click here for further instructions.

Cashout Status Response

Response Example

// Cashout successfully processed
{
    "cashout_status": 1,
    "cashout_status_description": "Completed"
}

// Cashout successfully processed through Pix including the E2E ID (Brazil)
{
    "cashout_status": 1,
    "cashout_status_description": "Completed",
    "provider_external_reference": "E352104102024022919987ScFRY3aab3",
    "bank": {
        "code": "260",
        "name": "Nubank",
        "branch": "2003",
        "account": "1892873892",
        "beneficiary_name": "John Smith"
    }
}

// Cashout Rejected by the bank
{
    "cashout_status": 3,
    "cashout_status_description": "Rejected",
    "rejection_code": 808,
    "rejection_reason": "ERROR_OTHER"
}

Response Fields Description

E2E for Pix Withdrawals

When processing Pix Withdrawals, we return as part of the Status endpoint further information about the bank account of the beneficiary.

This includes the provider_external_reference, also known as the E2E ID. It is a unique ID assigned to the transactions that can be used to track the transfer across the Brazilian banking system, useful to optimize the support experience as it allows the users to uniquely track their money as it reaches their bank account.

{
    "cashout_status": 1,
    "cashout_status_description": "Completed",
    "provider_external_reference": "E352104102024022919987ScFRY3aab3",
    "bank": {
        "code": "260",
        "name": "Nubank",
        "branch": "2003",
        "account": "1892873892",
        "beneficiary_name": "John Smith"
    }
}

We also include details about the bank account that received the money, useful when using Pix Keys.

Status Flow

Click here to see each Cashout Status meaning.

Cashout Status Flow

Status codes

Check all the possible status codes in the following page:

Cashout Update Status Endpoint

PUT https://api-stg.zimo-pagos.com/v3/cashout/status

This API allows you to change the status of a cashout

Headers

Request Body

{
    "cashout_status": 1,
    "cashout_status_description": "Completed"
}

{
    "cashout_status": 3,
    "cashout_status_description": "Rejected",
    "rejection_code": 0,
    "rejection_reason": "Test"
}

{
    "code": 401,
    "message": "Invalid credentials."
}

{
    "code": 509,
    "message": "Cashout not found with this ID"
}

Introduction

This API is used to update a cashout from PENDING to ON_HOLD or from ON_HOLD to PENDING.

A cashout in ON_HOLD won't be processed until you set it back to PENDING. This is useful in cases where you need to perform some form of KYC over the beneficiary before proceeding with the request.

You can create a cashout in ON_HOLD by specifying the flag on_hold: true on the cashout creation request.

If a cashout is ON_HOLD and you would like to definitely cancel it, please see the Cashout Cancellation Endpoint

Cashout Update Status Request

Request Example

// HEADERS
Content-Type: application/json 
Payload-Signature: 2e5023770760ea0a02230bff1a6dab934fe3b47a5e3d43854b58676600ee3868 

// BODY
{ 
   "login": "cashout_login",  
   "pass": "cashout_pass", 
   "cashout id": "97875"
   "status": "ON_HOLD"
}

Request Fields Description

Request Payload Signature

The Payload-Signature of the Cashout Update Status Endpoint is calculated by hashing the whole JSON payload of the request using HMAC256 and your secret key (API Signature) to encrypt it.

Click here for further instructions.

Cashout Update Status Response

Error Response Example

{
    "code": 510,
    "message": "Invalid status transition"
}

Status Flow

Click here to see each Cashout Status meaning.

Cashout Status Flow

• There are cases in which the bank confirms us that a payout was successful and after a few days, it gets rejected by the beneficiary's bank therefore the status on our platform will change to REJECTED as well. Those are very corner cases but should be considered.

Status codes

Check all the possible status codes in the following page:

Refund Status

GET https://api-stg.zimo-pagos.com/v3/refunds/{refund_id}

This endpoint allows you to retrieve the status of a refund request.

Path Parameters

Query Parameters

Headers

Description

You can trigger the check of the status of a refund at any moment you consider pertinent. However, every time a refund changes its status, we will send you a containing the ID of the refund so that you can check its status back to retrieve the new refund's status.

Refunds Status Request

In order to check the status of the refunds, you need to:

1. Send the request with GET method.

2. Use the headers described .

3. Specify a valid refund_id in the URL of the request as PATH PARAMETERS.

4. Send the Authorization header, as .

Regarding the Authorization value, since the body of the requests will be empty, you should use an empty ("") string or nothing as the jsonPayload field.

Example response

Response fields

Proof of refund

In order to generate an invoice as proof of refund, you need to:

1. Send the request with GET method.

2. Use the headers described .

3. Specify a valid refund_id in the URL of the request as PATH PARAMETERS.

4. Send the query parameter voucher as true.

5. Send the Authorization header, as .

Requesting a Refund and including the field voucher as a query parameter with value true will generate a voucher in base64, this voucher will need to be decoded to create the .pdf

Status Flow

to see each Refund Status meaning.

Refund Status Flow

Status codes

Check all the possible status in the following page:

Security Considerations

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

• API requests without Authentication 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 TEST environment, where you can perform your tests freely without risks of any kind.

When you sign up with us, 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 doesn't change.

API Keys

Our Deposits 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.

There are basically two set of credentials:

• One API Key and one API Signature for POST operations.

• One API Key key for read-only endpoints.

Authentication to the API is performed via HTTP Basic Auth. You must provide your API Key in all the requests as the basic auth username value. You do not need to provide a password.

Your API Key must be sent in all the API calls using the X-Login field on the header of the request.

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

Headers

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

Authorization Signature

All the requests you send must contain the Authorization header with an HMAC256 control string signature using your own API Signature. This is used to verify the request integrity as we will calculate the same Signature and compare it with the one you send. In case of mismatch we will decline the request.

In the case of the notifications given by our APIs, those will also contain an Authorization value which you should calculate and compare to make sure the content was not altered by a Man in the Middle attack.

Check the following page for instructions on how to calculate the Control Signature.

X-Login

All the requests you send must contain the header X-Login with your own API Key value used to authenticate yourself. Check API Keys.

X-Date

All the requests you send must contain the header X-Date with the time in which the request was created. The format is in ISO8601 Datetime: yyyy-MM-dd'T'HH:mm:ssZ. E.g.: 2020-06-21T12:33:20Z.

If the date you send differs in more than 5 seconds with the time in our servers, we will block the request for security reasons.

Example of how to generate the correct X-Date value

import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;

public class ClientUtils {

   private static final String DATE_PATTERN = "yyyy-MM-dd'T'HH:mm:ss'Z'";

   private static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern(DATE_PATTERN);


   public static String now() {
      return LocalDateTime.now(ZoneOffset.UTC).format(DATE_TIME_FORMATTER);
   }

}

<?php

namespace ZimoPagos\util;

class Helpers 
{
    private static $DATE_TIME_FORMATTER = "Y-m-d\TH:i:s\Z";

    public static function getCurrentDate()
    {
        date_default_timezone_set('UTC');
        return date(self::$DATE_TIME_FORMATTER);
    }
}

print(Helpers::getCurrentDate());

Idempotent Requests

Our API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to the Deposit Creation Endpoint does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one deposit is created.

In order to perform an idempotent request you need to send the X-Idempotency-Key: <key> header with a random and unique string.

Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided as these requests are idempotent by definition.

Content-Type

All of our Deposits APIs are designed to receive and respond the information in JSON format.

This header won't change across the requests, and shall always be: application/json

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 Deposit IP Address section.

Reach out to [email protected] 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.

3. Always validate that a deposit is not released more than once based on the deposit_id (The notifications can be sent multiple times).

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

Cashout Bank Codes

GET https://api-stg.zimo-pagos.com/v3/banks?country={ISO_CODE}

This API allows you to retrieve the list of banks available in each country

Query Parameters

Headers

[
    {
        "code": 1,
        "name": "BANCO DO BRASIL S.A."
    },
    {
        "code": 3,
        "name": "BANCO DA AMAZONIA S.A."
    },
    {
        "code": 4,
        "name": "BANCO DO NORDESTE DO BRASIL S.A."
    },
    {
        "code": 21,
        "name": "BANESTES S.A. BANCO DO ESTADO DO ESPIRITO SANTO"
    },
    {
        "code": 33,
        "name": "BANCO SANTANDER BRASIL S.A."
    },
    {
        "code": 37,
        "name": "BANCO DO ESTADO DO PARA S.A. - BANPARA"
    },
    {
        "code": 41,
        "name": "BANCO DO ESTADO DO RIO GRANDE DO SUL S.A. - BANRISUL"
    },
    {
        "code": 47,
        "name": "BANCO DO ESTADO DE SERGIPE S.A. - BANESE"
    },
    {
        "code": 70,
        "name": "BANCO DE BRASILIA S.A. - BRB"
    },
    {
        "code": 77,
        "name": "BANCO INTER"
    },
    {
        "code": 104,
        "name": "CAIXA ECONOMICA FEDERAL - CEF"
    },
    {
        "code": 212,
        "name": "BANCO ORIGINAL"
    },
    {
        "code": 218,
        "name": "BANCO BONSUCESSO S.A."
    },
    {
        "code": 237,
        "name": "BANCO BRADESCO S.A."
    },
    {
        "code": 246,
        "name": "BANCO ABC BRASIL S.A."
    },
    {
        "code": 290,
        "name": "PagSeguro Internet S.A"
    },
    {
        "code": 336,
        "name": "BANCO C6 S.A"
    },
    {
        "code": 341,
        "name": "ITAU UNIBANCO S.A."
    },
    {
        "code": 389,
        "name": "BANCO MERCANTIL DO BRASIL S.A."
    },
    {
        "code": 399,
        "name": "HSBC BANK BRASIL S.A. - BANCO MULTIPLO"
    },
    {
        "code": 422,
        "name": "BANCO SAFRA S.A."
    },
    {
        "code": 477,
        "name": "CITIBANK N.A."
    },
    {
        "code": 637,
        "name": "BANCO SOFISA"
    },
    {
        "code": 707,
        "name": "BANCO DAYCOVAL S.A."
    },
    {
        "code": 745,
        "name": "BANCO CITIBANK"
    },
    {
        "code": 746,
        "name": "BANCO MODAL S.A."
    },
    {
        "code": 748,
        "name": "BANCO COOPERATIVO SICREDI S.A."
    },
    {
        "code": 756,
        "name": "BANCO COOPERATIVO DO BRASIL S/A - BANCOOB"
    }
]

{
    "code": 100,
    "description": "Invalid credentials",
    "type": "INVALID_CREDENTIALS"
}

Introduction

This endpoint is used to retrieve and display to your customer the list of banks available on their country. In case we add or remove a bank, this endpoint will reflect those updates real-time and therefore it is a good idea to constantly check this endpoint for the list of banks.

Once the user selected their bank by its name, you need to send its code to us in the bank_code field of the requests.

The endpoint is read only and so it uses a read only key. It can be used from the front-end without major security concerns.

Bank Codes Request

Request Example

// URL
GET: https://api-stg.zimo-pagos.com/v3/banks?country=AR

// HEADERS
Authorization: Bearer EKiFOWiHnI 

Request Fields

Bank Codes Response

Response Example

[
    {
        "code": 1,
        "name": "BANCO DO BRASIL S.A."
    },
    {
        "code": 3,
        "name": "BANCO DA AMAZONIA S.A."
    },
    {
        "code": 4,
        "name": "BANCO DO NORDESTE DO BRASIL S.A."
    },
    {
        "code": 21,
        "name": "BANESTES S.A. BANCO DO ESTADO DO ESPIRITO SANTO"
    },
    {
        "code": 33,
        "name": "BANCO SANTANDER BRASIL S.A."
    },
    {
        "code": 37,
        "name": "BANCO DO ESTADO DO PARA S.A. - BANPARA"
    },
    {
        "code": 41,
        "name": "BANCO DO ESTADO DO RIO GRANDE DO SUL S.A. - BANRISUL"
    },
    {
        "code": 47,
        "name": "BANCO DO ESTADO DE SERGIPE S.A. - BANESE"
    },
    {
        "code": 70,
        "name": "BANCO DE BRASILIA S.A. - BRB"
    },
    {
        "code": 75,
        "name": "BANCO ABN AMRO S.A"
    },
    {
        "code": 77,
        "name": "BANCO INTER"
    },
    {
        "code": 85,
        "name": "Cooperativa Central de Crédito Urbano-CECRED"
    },
    {
        "code": 93,
        "name": "POLOCRED SCMEPP"
    },
    {
        "code": 104,
        "name": "CAIXA ECONOMICA FEDERAL - CEF"
    },
    {
        "code": 121,
        "name": "BANCO AGIPLAN S.A."
    },
    {
        "code": 136,
        "name": "Confederação Nacional das Cooperativas Centrais Unicred"
    },
    {
        "code": 212,
        "name": "BANCO ORIGINAL"
    },
    {
        "code": 218,
        "name": "BANCO BONSUCESSO S.A."
    },
    {
        "code": 237,
        "name": "BANCO BRADESCO S.A."
    },
    {
        "code": 260,
        "name": "NU PAGAMENTOS"
    },
    {
        "code": 290,
        "name": "PagSeguro Internet S.A"
    },
    {
        "code": 318,
        "name": "BANCO BMG S.A"
    },
    {
        "code": 336,
        "name": "BANCO C6 S.A"
    },
    {
        "code": 341,
        "name": "ITAU UNIBANCO S.A."
    },
    {
        "code": 389,
        "name": "BANCO MERCANTIL DO BRASIL S.A."
    },
    {
        "code": 399,
        "name": "HSBC BANK BRASIL S.A. - BANCO MULTIPLO"
    },
    {
        "code": 422,
        "name": "BANCO SAFRA S.A."
    },
    {
        "code": 477,
        "name": "CITIBANK N.A."
    },
    {
        "code": 637,
        "name": "BANCO SOFISA"
    },
    {
        "code": 655,
        "name": "Banco Votorantim S.A."
    },
    {
        "code": 707,
        "name": "BANCO DAYCOVAL S.A."
    },
    {
        "code": 712,
        "name": "BANCO OURINVEST S.A"
    },
    {
        "code": 735,
        "name": "BANCO NEON"
    },
    {
        "code": 745,
        "name": "BANCO CITIBANK"
    },
    {
        "code": 746,
        "name": "BANCO MODAL S.A."
    },
    {
        "code": 748,
        "name": "BANCO COOPERATIVO SICREDI S.A."
    },
    {
        "code": 756,
        "name": "BANCO COOPERATIVO DO BRASIL S/A - BANCOOB"
    }
]

Response fields

Required fields

Bank Account Validations

Use the Regex below to validate the bank accounts on your end.

CBU Validation Algorithm

Since the first three digits of the CBU are the bank code, it is not mandatory to send the bank_code field.

public class Validations {
    static Integer CBU_LENGTH = 22;

    public static Boolean verifyCBU(String cbu) {
        return cbuLengthValidation(cbu) && bankCodeValidation(cbu) && accountValidation(cbu);
    }

    public static Boolean cbuLengthValidation(String cbu) {
        return cbu.length() == 22 && ValidationsUtils.validateOnlyNumbers(cbu);
    }

    public static Boolean bankCodeValidation(String cbu) {
        if (cbu.length() == CBU_LENGTH && ValidationsUtils.validateOnlyNumbers(cbu)) {
            String shortCbu = StringUtils.left(cbu, 8);
            String bankCode = shortCbu.substring(0, 3);
            String branchCode = shortCbu.substring(4, 7);
            int firstCheckDigit = charToInt(shortCbu.toCharArray()[3]);
            int secondCheckDigit = charToInt(shortCbu.toCharArray()[7]);
            int sum = charToInt(bankCode.charAt(0)) * 7 + charToInt(bankCode.charAt(1)) * 1 + charToInt(bankCode.charAt(2)) * 3 + firstCheckDigit * 9 + charToInt(branchCode.charAt(0)) * 7 + charToInt(branchCode.charAt(1)) * 1 + charToInt(branchCode.charAt(2)) * 3;
            int diference = (10 - sum % 10) % 10;
            return diference == secondCheckDigit;
        } else {
            return false;
        }
    }

    public static Boolean accountValidation(String cbu) {
        String account = cbu.substring(8, 22);
        int sum = 0;
        int j = 0;
        int[] weighter = new int[]{3, 9, 7, 1};
        char[] arrayAccount = account.toCharArray();
        int checkDigit = charToInt(account.toCharArray()[13]);

        for(int i = 0; i < 13; ++i) {
            sum += charToInt(arrayAccount[i]) * weighter[j % 4];
            ++j;
        }

        int diference = (10 - sum % 10) % 10;
        return diference == checkDigit;
    }

    private static int charToInt(char ch) {
        return Integer.parseInt(String.valueOf(ch));
    }
}

Document Validations

Click here to check document types and validations.

Example Request

{
    "login": "xxxxxxxx",
    "pass": "xxxxxxxx",
    "external_id": "30000000001",
    "country": "AR",
    "currency": "ARS",
    "amount": 100,
    "document_id": "5676586998",
    "bank_account": "",
    "bank_code": "10000",
    "bank_branch": "",
    "email": "[email protected]",
    "beneficiary_name": "John",
    "beneficiary_lastname": "Smith",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}

Bank Codes

Cashout Request

POST https://api-stg.zimo-pagos.com/v3/cashout

This endpoint allows you to generate cashout requests

Headers

Request Body

{
    "cashout_id": "8405147"
}

{
    "code": 401,
    "message": "Invalid credentials."
}

{
    "code": 303,
    "message": "Invalid bank code"
}

{
    "code": 300,
    "message": "bank_account: must not be null; Invalid Bank account"
}

{
    
    "code": 504,
    "message": "User unauthorized due to cadastral situation",
    "reason": "Underage user detected",
    "reason_code": 105
}

Request Fields Description

Error response

Error response fields

Error response examples

{
  "code": 300,
  "message": "bankAccount: Invalid or missing Bank account"
}

{
  "code": 303,
  "message": "Invalid bank code"
}

{
  "code": 504,
  "message": "User unauthorized due to cadastral situation."
  "reason": "Underage user detected",
  "reason_code": 105
}

Fields required

Each country has different requirements and therefore we ask for different fields you need to send on the requests.

Go to the Countries Validations page to check each country requirements and validations.

Cashouts to debit cards

In Mexico, we accept cashouts sent directly to debit cards.

When that happens, you need to send the request through a different endpoint, otherwise your request will be declined with Invalid bank account, it shouldn't be a credit card.

PROD endpoint for Debit Cards: Email [email protected] with your cashout API Key

STG endpoint for Debit Cards: https://cc-api-stg.zimo-pagos.com/v3/cashout

The bank accounts in Mexico are in CLABE format (numeric) and have 18 digits (without dashes). Therefore one way to detect that a bank account specified by the customer is a debit card is by checking with the luhn algorithm if it is a valid card number and/or with a regex for each brand, like the example below.

public static final String SENSIBLE_DATA_PATTERN = new StringBuilder("(?:(?<visa>4[0-9]{12}(?:[0-9]{3})?)")
      .append("|(?<mastercard>5[1-5][0-9]{14})")
      .append("|(?<discover>6(?:011|5[0-9]{2})[0-9]{12})")
      .append("|(?<amex>3[47][0-9]{13})")
      .append("|(?<diners>3(?:0[0-5]|[68][0-9])?[0-9]{11})")
      .append("|(?<jcb>(?:2131|1800|35[0-9]{3})[0-9]{11}))")
      .toString();

private boolean validateCreditCard(CashoutRequestDto request) {
   final String bankAccount = request.getBank_account();
   if (StringUtils.isEmpty(bankAccount) || !LuhnCheckDigit.LUHN_CHECK_DIGIT.isValid(bankAccount) || 
      bankAccount.matches(Constants.SENSIBLE_DATA_PATTERN)) {
      return false;
   }
   return true;
}

If true, send the request through the cc-api endpoint, if false send it through the normal endpoint. The integration and requirements remains exactly the same, only changing the error message returned in case of invalid bank account and that we validate the bank_account sent to be a valid credit card number using the Luhn Algorithm.

Sending a debit card number through the non-cc endpoint will make the request to fail with the following error:

{
    "code": 300,
    "message": "bank_account: Invalid bank account, it shouldn't be a credit card"
}

Invalid bank_account error on the cc-api endpoint:

{
    "code": 300,
    "message": "bankAccount: invalid credit card number"
}

Cashout Status Codes