# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zimo-pagos.com/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

---

# Zimopagos APIs

Welcome to Zimopagos APIs documentation page.

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.

<table data-view="cards"><thead><tr><th align="center"></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td align="center"><strong>Deposits API</strong></td><td>Create a deposit request  by collecting and sending the information needed to pay. We will return you with the metadata required to create the checkout on your own website or redirect the customer to the payment site.</td><td><a href="/api-documentation/deposits-api">Deposits API</a></td><td><a href="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/BijJDTsvhNfJHVXepY9v/Cashin.png">Cashin.png</a></td></tr><tr><td align="center"><strong>Cashouts API</strong></td><td>Develop your own checkout page where you will collect and send us all the details required to process the cashouts.</td><td><a href="/api-documentation/cashouts-api">Cashouts API</a></td><td><a href="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/AtBi2MaVz3R24EP1jMvt/Cashout.png">Cashout.png</a></td></tr><tr><td align="center"><strong>Credit Cards PCI API</strong></td><td>This API 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.</td><td><a href="/api-documentation/deposits-api/endpoints/pci-deposit-creation-endpoint">PCI Deposit Creation Endpoint</a></td><td><a href="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/ItAntMg250MM7HDJSkNH/Credit%20Card.png">Credit Card.png</a></td></tr></tbody></table>

{% hint style="success" %}
For world-class UX and integration, we strongly suggest the use of our Deposits API OneShot Experience flow! :rocket:
{% endhint %}

{% hint style="info" %}
Have in mind that the Deposits API Hosted Checkout works as a fallback method, so that in cases which by mistake a piece of information was missing or additional information is required in order to create a Deposit, we can collect it and avoid a failure in the deposit creation.
{% endhint %}

###


# Deposits API

Our latest Deposits API is focused on simplicity, usability and personalization and it is used to allow your customers to deposit with their local payment methods of preference.

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

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](/api-documentation/deposits-api#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](/api-documentation/deposits-api#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](/api-documentation/deposits-api/endpoints/pci-deposit-creation-endpoint): 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**.

{% hint style="success" %}
Start testing all the API features with our [Postman collection here.](/api-documentation/deposits-api#postman-collection)
{% endhint %}

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

{% hint style="success" %}
Once the payment is generated, we will send a field specifying whether the payment experience can be done **OneShot:** native on your cashier with the metadata we give you or with **Redirect**.
{% endhint %}

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:wink: .

{% hint style="success" %}
With this integration, it is a good idea to **ask the customer** to fill in their details **only once** and **store them in your database** so you don't have to ask them for those details each time and **instead, you send us the information directly from your database**. In case they need to **modify** something, they should do it from **their profile** and not from your cashier.
{% endhint %}

#### Flow&#x20;

<figure><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/Lal6aH9bcXV2nC5C1Axr/image.png" alt=""><figcaption></figcaption></figure>

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

{% hint style="info" %}
This flow works only as a fallback method for ONE SHOT experience, so that in cases which by mistake a piece of information was missing or additional information is required in order to create a Deposit, we can collect it and avoid a failure in the deposit creation.
{% endhint %}

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.

{% hint style="info" %}
If you already have the customer's name, email address, document ID or any other details on your database, you can opt for sending it on the request so we don't ask the customer for it again.
{% endhint %}

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](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#deposit-creation).

#### &#x20; Flow

<figure><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/zRm4BsOpmgg6Z14OlPcj/image.png" alt=""><figcaption></figcaption></figure>

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

{% hint style="info" %}
With this integration you will be handling sensitive Credit Card data, therefore, we require you to be PCI Compliant and send us your **PCI AOC certificate**.
{% endhint %}

#### Flow&#x20;

<figure><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/J4hfscvljo8nPwsw0Gtm/image.png" alt=""><figcaption></figcaption></figure>

## Getting Started

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

**1 - Sign Up:** [Create your merchant](broken://pages/-M7EuILiDC84wuJM3YpB) account in our Merchant Panel.&#x20;

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

* 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](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint)
* [ ] 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](/api-documentation/deposits-api/api-codes#deposits-status-codes) and [reject codes](/api-documentation/deposits-api/api-codes#api-error-codes)
* [ ] Use the [Payment Methods](broken://pages/-M7hYgDIPRyR1p3XGmws) 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 <integration@zimo-pagos.com> 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

[![Run In Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/34627642-81c0473c-c006-4797-8b88-3c8f0e118bbc?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D34627642-81c0473c-c006-4797-8b88-3c8f0e118bbc%26entityType%3Dcollection%26workspaceId%3Dd035c5b1-db5b-4e0f-8032-eec3c621aa8b)

{% hint style="success" %}
Make sure you replace the `login` and `secretKey` values with your own API Key and API Signature deposit credentials
{% endhint %}


# Technical and Security Aspects

Learn about the technical and security aspects of our Deposits APIs

## Security Considerations

* All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail.&#x20;
* API requests without [Authentication](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature) will also fail.
* You will be able to hit our APIs only from the IPs you have [previously whitelisted](/api-documentation/deposits-api/technical-and-security-aspects#ip-whitelisting) 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 ](/api-documentation/deposits-api/endpoints)doesn't change.

| Environment | Domain                                 |
| ----------- | -------------------------------------- |
| Testing     | <https://api-stg.zimo-pagos.com/>      |
| Production  | Provided once you complete the testing |

{% hint style="info" %}
Notes:

* You will use the STG endpoints to integrate.
* The STG and PROD environments are not communicated in any way.&#x20;
* No transaction created on the STG environment will be reflected on the PROD environment or vice versa.&#x20;
* The API Keys and configurations between environments are also different.
  {% endhint %}

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

{% hint style="info" %}

* The API Keys on the STG and PROD environments are different.
  {% endhint %}

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](http://en.wikipedia.org/wiki/Basic_access_authentication). 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](/api-documentation/deposits-api/technical-and-security-aspects#ip-whitelisting) 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.

| Header            | Format | Mandatory | Description                                                                                                    |
| ----------------- | :----: | :-------: | -------------------------------------------------------------------------------------------------------------- |
| Authorization     | String |    Yes    | `"ZIMO"` plus a hash HMAC256 to verify request integrity                                                       |
| X-Login           | String |    Yes    | Merchant `API Key`                                                                                             |
| X-Date            | String |    Yes    | ISO8601 Datetime: `yyyy-MM-dd'T'HH:mm:ssZ`. E.g.: `2020-06-21T12:33:20Z`                                       |
| Content-Type      | String |    Yes    | `application/json`                                                                                             |
| X-Idempotency-Key | String |     No    | Unique value generated by the client which the server uses to recognize subsequent retries of the same request |

###

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

{% content-ref url="/pages/-M7ic8P-kyDs3BecUOKC" %}
[Calculating the Signature](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature)
{% endcontent-ref %}

### 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](/api-documentation/deposits-api/technical-and-security-aspects#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`.&#x20;

{% hint style="warning" %}
Make sure you use UTC as the timezone specified and not your client's local timezone.
{% endhint %}

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

{% tabs %}
{% tab title="Java" %}
{% code title="source: JAVA SDK > src/main/java/com/zimo-pagos/client/util/ClientUtils.java" %}

```java
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);
   }

}

```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code title="source: PHP SDK > src/util/Helpers.php" %}

```php
<?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());

```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="success" %}
Check our SDK in [JAVA](broken://pages/-MDB27Ucv56bd5UZlBBu) and [PHP](broken://pages/-MDB2FLdN0OJFmRUECv7) for the full code of how to generate the X-Date and the full request.
{% endhint %}

### Idempotent Requests

Our API supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) 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](/api-documentation/deposits-api/endpoints/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 [integration@zimo-pagos.com](mailto:integration@d24.com) if you need to whitelist **our servers IPs** on your firewall.&#x20;

## 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.&#x20;
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.


# Calculating the Signature

Learn how to calculate and send the Signature header value to verify requests integrity

## 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.&#x20;

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

> [X-Date](/api-documentation/deposits-api/technical-and-security-aspects#x-date) + [X-Login](/api-documentation/deposits-api/technical-and-security-aspects#x-login) + `JSONPayload`

{% hint style="success" %}
Use your API Signature to generate the Authorization value
{% endhint %}

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`](/api-documentation/deposits-api/technical-and-security-aspects#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`](/api-documentation/deposits-api/technical-and-security-aspects#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`.&#x20;

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.&#x20;

## 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](broken://pages/-MDB27Ucv56bd5UZlBBu) and [PHP](broken://pages/-MDB2FLdN0OJFmRUECv7) to see how it is calculated.

{% tabs %}
{% tab title="Java" %}

```java
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();
}


```

{% endtab %}

{% tab title="C#" %}

```csharp
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);
        }
    }
}


```

{% endtab %}

{% tab title="PHP" %}

```php
<?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);
	
	}

}


```

{% endtab %}
{% endtabs %}


# Endpoints

Learn how to integrate all of our Deposits endpoints


# Deposit Creation Endpoint

Learn how to generate deposits

{% openapi src="/files/X8Qq99q9inLBLYZRGE6t" path="/deposits" method="post" %}
[updated\_openapi.yml](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/pfBBJXNt23kDyphKnMaS/updated_openapi.yml)
{% endopenapi %}

## Experiences

When generating a deposit request there are 2 possibilities, either the deposit is created in One Shot and you can display the user directly with the payment information, or you redirect the user to our Hosted Checkout to complete the missing details.

In any of those cases, a field called `checkout_type` will be part of the response, containing which one of the flows it is:

| `Checkout_type` | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ONE_SHOT`      | The deposit request was successfully completed in One Shot and the user will be directly presented with the information to complete the payment.                                                                                                                                                                                                                                                             |
| `HOSTED`        | <p>The information sent is missing details required to complete the request. Redirect the customer to our Hosted Checkout to collect those details. </p><p>This flow works as a fallback method, so that in cases which by mistake a piece of information was missing or additional information is required in order to create a Deposit, we can collect it and avoid a failure in the deposit creation.</p> |

{% hint style="success" %}
Test all the API features with our [Postman collection here.](/api-documentation/deposits-api#postman-collection)
{% endhint %}

## OneShot Experience

On this Experience, you will send all the information required to complete the deposit request and we will respond you with the payment metadata for you to build the Checkout or with an external link for the user to see the payment information.

In case you didn't send one field that is required, we won't decline the request and instead we will prompt the customer for it :wink: .

### OneShot Request example

{% hint style="success" %}
Each Country and Payment Method has a minimum set of fields you need to send for the OneShot Experience. In case of looking to develop this Experience on your Cashier visit the [Payment Methods page](/api-documentation/deposits-api/payment-methods) to learn more about those requirements.
{% endhint %}

{% tabs %}
{% tab title="JSON" %}

```javascript
{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "AR",
    "currency": "ARS",
    "payer": {
        "id": "11",
        "document": "40818273",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "email": "juanCarlos@hotmail.com",
        "phone": "+541139022032",
        }
    },
    "payment_method": "BL",
    "description": "test description",
    "client_ip": "123.123.123.123",
    "device_id": "00000000-00000000-01234567-89ABCDEF",
    "back_url": "https://www.zimo-pagos.com/deposit_cancelled",
    "success_url": "https://www.zimo-pagos.com/deposit_completed",
    "error_url": "https://www.zimo-pagos.com/deposit_error",
    "notification_url": "https://www.zimo-pagos.com/zimo/notify",
    "logo": "https://www.zimo-pagos.com/zimo-pago.png",
    "test": true,
    "mobile": false,
    "language": "en"
}

```

{% endtab %}

{% tab title="cURL" %}

```java
curl --location --request POST 'https://api-stg.zimo-pagos.com/v3/deposits' \
--header 'X-Login: xxxxxxx' \
--header 'X-Date: 2020-06-09T19:42:51Z' \
--header 'Authorization: D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38' \
--header 'Content-Type: application/json' \
--data-raw '{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "AR",
    "currency": "ARS",
    "payer": {
        "id": "11",
        "document": "40818273",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "email": "juanCarlos@hotmail.com",
        "phone": "+541139022032",
        }
    },
    "payment_method": "BL",
    "description": "test description",
    "client_ip": "123.123.123.123",
    "device_id": "00000000-00000000-01234567-89ABCDEF",
    "back_url": "https://www.zimo-pagos.com/deposit_cancelled",
    "success_url": "https://www.zimo-pagos.com/deposit_completed",
    "error_url": "https://www.zimo-pagos.com/deposit_error",
    "notification_url": "https://www.zimo-pagos.com/zimo/notify",
    "logo": "https://www.zimo-pagos.com/zimo-pago.png",
    "test": true,
    "mobile": false,
    "language": "en"
}'


```

{% endtab %}

{% tab title="Java" %}

```java
import java.io.*;
import okhttp3.*;
public class main {
  public static void main(String []args) throws IOException{
    OkHttpClient client = new OkHttpClient().newBuilder()
      .build();
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"1000\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payer\": {\n        \"id\": \"11\",\n        \"document\": \"84932568207\",\n       \"first_name\": \"Ricardo\",\n        \"last_name\": \"Carlos\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"juanCarlos@hotmail.com\",\n        \"address\": {\n            \"street\": \"Calle 13\",\n            \"city\": \"bahia\",\n            \"state\": \"SP\",\n            \"zip_code\": \"12345-678\"\n        }\n    },\n    \"payment_method\": \"BL\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.d24.com/deposit_cancelled\",\n    \"success_url\": \"https://www.d24.com/deposit_completed\",\n    \"error_url\": \"https://www.d24.com/deposit_error\",\n    \"notification_url\": \"https://www.d24.com/d24/notify\",\n    \"logo\": \"https://www.d24.com/d24.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"pt\"\n}");
    Request request = new Request.Builder()
      .url("https://api-stg.directa24.com/v3/deposits")
      .method("POST", body)
      .addHeader("X-Login", "xxxxxxx")
      .addHeader("X-Date", "2020-06-09T19:42:51Z")
      .addHeader("Authorization", "D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38")
      .addHeader("Content-Type", "application/json")
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
  }
}


```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-stg.zimo-pagos.com/v3/deposits');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "invoice_id": "1000000001",
    "amount": "1000",
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "phone": "+23385266942",
        "email": "juanCarlos@hotmail.com",
        "address": {
            "street": "Calle 13",
            "city": "bahia",
            "state": "SP",
            "zip_code": "12345-678"
        }
    },
    "payment_method": "BL",
    "description": "test description",
    "client_ip": "123.123.123.123",
    "device_id": "00000000-00000000-01234567-89ABCDEF",
    "back_url": "https://www.d24.com/deposit_cancelled",
    "success_url": "https://www.d24.com/deposit_completed",
    "error_url": "https://www.d24.com/deposit_error",
    "notification_url": "https://www.d24.com/d24/notify",
    "logo": "https://www.d24.com/d24.png",
    "test": true,
    "mobile": false,
    "language": "pt"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'X-Login' => 'xxxxxxxx',
  'X-Date' => '2020-06-09T19:42:51Z',
  'Authorization' => 'D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38',
  'Content-Type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using RestSharp;
namespace HelloWorldApplication {
    class HelloWorld {
        static void Main(string[] args) {
            var client = new RestClient("https://api-stg.directa24.com/v3/deposits");
            client.Timeout = -1;
            var request = new RestRequest(Method.POST);
            request.AddHeader("X-Login", "xxxxxxx");
            request.AddHeader("X-Date", "2020-06-09T19:42:51Z");
            request.AddHeader("Authorization", "D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38");
            request.AddHeader("Content-Type", "application/json");
            request.AddParameter("application/json", "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"1000\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payer\": {\n        \"id\": \"11\",\n        \"document\": \"84932568207\",\n        \"first_name\": \"Ricardo\",\n        \"last_name\": \"Carlos\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"juanCarlos@hotmail.com\",\n        \"address\": {\n            \"street\": \"Calle 13\",\n            \"city\": \"bahia\",\n            \"state\": \"SP\",\n            \"zip_code\": \"12345-678\"\n        }\n    },\n    \"payment_method\": \"BL\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.d24.com/deposit_cancelled\",\n    \"success_url\": \"https://www.d24.com/deposit_completed\",\n    \"error_url\": \"https://www.d24.com/deposit_error\",\n    \"notification_url\": \"https://www.d24.com/d24/notify\",\n    \"logo\": \"https://www.d24.com/d24.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"pt\"\n}",  ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}


```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api-stg.directa24.com/v3/deposits"

payload = "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"1000\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payer\": {\n        \"id\": \"11\",\n        \"document\": \"84932568207\",\n        \"first_name\": \"Ricardo\",\n        \"last_name\": \"Carlos\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"juanCarlos@hotmail.com\",\n        \"address\": {\n            \"street\": \"Calle 13\",\n            \"city\": \"bahia\",\n            \"state\": \"SP\",\n            \"zip_code\": \"12345-678\"\n        }\n    },\n    \"payment_method\": \"BL\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.d24.com/deposit_cancelled\",\n    \"success_url\": \"https://www.d24.com/deposit_completed\",\n    \"error_url\": \"https://www.d24.com/deposit_error\",\n    \"notification_url\": \"https://www.d24.com/d24/notify\",\n    \"logo\": \"https://www.d24.com/d24.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"pt\"\n}"
headers = {
  'X-Login': 'xxxxxxx',
  'X-Date': '2020-06-09T19:42:51Z',
  'Authorization': 'D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))


```

{% endtab %}
{% endtabs %}

### OneShot Experience Response: OneShot

In case you sent all the details required for a payment method and the method supports it, we will return you all the metadata required for you to build the checkout on your **own website** avoiding the redirection.

#### Success Response fields

The fields returned in this integration are the same than the [REDIRECT](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#response-fields) one. The difference lies in the new `metadata` and `secondary_metadata` objects containing the information you need to build your own checkout for each payment method:

| Field name                          | Format | Description                                                                                    |
| ----------------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `metadata`                          | object | Object containing the metadata of the payment                                                  |
| `metadata.beneficiary_name`         | string | Name of the account beneficiary                                                                |
| `metadata.agency`                   | string | Agency of the beneficiary                                                                      |
| `metadata.CNPJ`                     | string | CNPJ of the beneficiary                                                                        |
| `metadata.account`                  | string | Account of the beneficiary                                                                     |
| `metadata.bar_code`                 | string | Voucher bar code token                                                                         |
| `metadata.digitable_line`           | string | Voucher identifier line                                                                        |
| `metadata.payer_document`           | string | Document number of the payer                                                                   |
| `metadata.payer_document_type`      | string | Type of the payer's document sent                                                              |
| `metadata.reference`                | string | Reference your customer needs to pay                                                           |
| `secondary_metadata`                | object | Object containing the secondary metadata of the payment                                        |
| `secondary_metadata.reference`      | string | Reference of the deposit                                                                       |
| `secondary_metadata.qr_code`        | string | PNG image encoded in base64 of the QR code used to display the Pix QR natively on your site    |
| `secondary_metadata.digitable_line` | string | Plain text string line the user can use to manually pay for the PIX instead of scanning the QR |
| `checkout_token`                    | string | Token needed to display the [Cards SDK](broken://pages/41GdHq3N84DE8ehy2rRJ) component.        |

{% hint style="warning" %}
Please note that the `metadata` and the `secondary_metadata`objects will respond with different values depending upon the payment method and the provider we use, the ones above are only examples. It is for that reason that you should be able to iterate through them to display the values on your cashier to your customers.
{% endhint %}

#### Success Response example

{% tabs %}
{% tab title="BANK\_TRANSFER" %}

```javascript
{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://checkout-stg.zimo-pagos.com/v1/gateway/show?id_payment=56579207&signature=d79896d2b815303cbed4",
    "deposit_id": 300000148,
    "user_id": "121",
    "merchant_invoice_id": "postmanTest349087674",
    "payment_info": {
        "type": "BANK_TRANSFER",
        "payment_method": "SB",
        "payment_method_name": "Santander",
        "amount": 176.02,
        "currency": "BRL",
        "expiration_date": "2020-06-21 09:48:39",
        "created_at": "2020-06-20 21:48:39",
        "metadata": {
            "beneficiary_name": "Zimo LLP",
            "agency": "1324",
            "CNPJ": "47.222.214/0005-70",
            "account": "13023469-6"
        }
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
This integration is an extension of the [REDIRECT](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience-response-redirect) one. It will always contain a link to redirect the customer in case you don't wan't to develop the checkout with the metadata on your website.
{% endhint %}

#### Secondary Metadata

The object `secondary_metadata` is used to display the customer with a second way to pay for the same deposit allowing them to choose the best option. For example, the user could create a deposit for a bank deposit method in Brasil, and show them our Bank Details (field `metadata`)  as well as a Pix QR code (field `secondary_metadata`) in case they prefer that option.

![](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/NDpswOv45eb7GyCsrvrF/Screen%20Shot%202021-09-17%20at%2010.27.51.png)

### OneShot Experience Response: Redirect

This integration generates a link to redirect the customer where they will see the details required to pay.

#### Success Response fields

| Field name                         | Format  | Description                                                                                         |
| ---------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `checkout_type`                    | String  | Field containing the type of the request. `[ONE_SHOT, HOSTED]`                                      |
| `redirect_url`                     | URL     | URL used to redirect the customer where they can see the details to pay                             |
| `deposit_id`                       | Integer | ID of the deposit generated. Store this ID for future reference                                     |
| `user_id`                          | String  | ID of the user. If you didn't send it, it is generated by us                                        |
| `merchant_invoice_id`              | String  | ID of the deposit. If you didn't send it, it is generated by us                                     |
| `payment_info`                     | Object  | Object containing the information about the payment                                                 |
| `payment_info.type`                | String  | Type of the payment method. See the [list here.](broken://pages/-M7hYgDIPRyR1p3XGmws#payment-types) |
| `payment_info.payment_method`      | String  | Payment method code. See the [list here.](/api-documentation/deposits-api/payment-methods)          |
| `payment_info.payment_method_name` | String  | Payment method name. See the [list here.](/api-documentation/deposits-api/payment-methods)          |
| `payment_info.amount`              | number  | **Exact** amount the customer has to pay                                                            |
| `payment_info.currency`            | string  | Currency of the amount to pay                                                                       |
| `payment_info.expiration_date`     | string  | Date in which the deposit will be marked as expired                                                 |
| `payment_info.created_at`          | string  | Deposit creation date                                                                               |

#### Success Response example

```javascript
{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://payment-stg.zimo-pagos.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI1NjU3ODQ2NCIsImlhdCI6MTU5MTgyOTYzNiwiZXhwIjoxNTkzMTI1NjM2LCJsYW5ndWFnZSI6bnVsbH0.XIlYyskFpE_rh1-8sA0Bs3JzB2iMmqAXdovClPzorrZXmzol69JqkeU7TR5FMBRn",
    "deposit_id": 300000011,
    "user_id": "11",
    "merchant_invoice_id": "test123456789",
    "payment_info": {
        "type": "VOUCHER",
        "payment_method": "BC",
        "payment_method_name": "BCP",
        "amount": 6.9448,
        "currency": "PEN",
        "expiration_date": "2020-06-15 22:53:56",
        "created_at": "2020-06-10 22:53:55"
    }
}
```

## Hosted Checkout Experience

In case that you can't collect any of the details required for the OneShot Experience, you can avoid sending it.&#x20;

{% hint style="success" %}
Using OneShot improves the experience because it reduces the amount of interactions required by the end-user.

The more details you send will personalize the Experience on our Hosted Checkout and will help in not having to ask the customer for the information again.
{% endhint %}

### Hosted Checkout Request

#### Request Example

{% tabs %}
{% tab title="JSON" %}

```javascript
{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "email": "juanCarlos@hotmail.com"
    },
    "description": "test description",
    "client_ip": "123.123.123.123",
    "back_url": "https://www.zimo-pagos.com/deposit_cancelled",
    "success_url": "https://www.zimo-pagos.com/deposit_completed",
    "error_url": "https://www.zimo-pagos.com/deposit_error",
    "notification_url": "https://www.zimo-pagos.com/zimo/notify",
    "logo": "https://www.zimo-pagos.com/zimo.png",
    "test": true,
    "request_payer_data_on_validation_failure": true,
    "mobile": false,
    "language": "pt"
}

```

{% endtab %}

{% tab title="cURL" %}

```java
curl --location --request POST 'https://api-stg.zimo-pagos.com/v3/deposits' \
--header 'X-Login: {{X-Login}}' \
--header 'X-Date: {{X-Date}}' \
--header 'Authorization: {{Authorization}}' \
--header 'X-Idempontency-Key: {{X-Idempotency-Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "invoice_id" : "100000001",
    "amount": "100",
    "country": "BR",
    "currency": "BRL",
    "payment_types": ["BANK_TRANSFER", "BANK_DEPOSIT"]
}
'


```

{% endtab %}

{% tab title="Java" %}

```java
import java.io.*;
import okhttp3.*;
public class main {
  public static void main(String []args) throws IOException{
    OkHttpClient client = new OkHttpClient().newBuilder()
      .build();
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, "{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n");
    Request request = new Request.Builder()
      .url("https://api-stg.zimo-pagos.com/v3/deposits")
      .method("POST", body)
      .addHeader("X-Login", "{{X-Login}}")
      .addHeader("X-Date", "{{X-Date}}")
      .addHeader("Authorization", "{{Authorization}}")
      .addHeader("X-Idempontency-Key", "{{X-Idempotency-Key}}")
      .addHeader("Content-Type", "application/json")
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
  }
}


```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.zimo-pagos.com/v3/deposits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>"{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n",
  CURLOPT_HTTPHEADER => array(
    "X-Login: {{X-Login}}",
    "X-Date: {{X-Date}}",
    "Authorization: {{Authorization}}",
    "X-Idempontency-Key: {{X-Idempotency-Key}}",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using RestSharp;
namespace HelloWorldApplication {
    class HelloWorld {
        static void Main(string[] args) {
            var client = new RestClient("https://api-stg.zimo-pagos.com/v3/deposits");
            client.Timeout = -1;
            var request = new RestRequest(Method.POST);
            request.AddHeader("X-Login", "{{X-Login}}");
            request.AddHeader("X-Date", "{{X-Date}}");
            request.AddHeader("Authorization", "{{Authorization}}");
            request.AddHeader("X-Idempontency-Key", "{{X-Idempotency-Key}}");
            request.AddHeader("Content-Type", "application/json");
            request.AddParameter("application/json", "{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n",  ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}


```

{% endtab %}

{% tab title="Python" %}

```python
import http.client
import mimetypes
conn = http.client.HTTPSConnection("api-stg.zimo-pagos.com")
payload = "{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n"
headers = {
  'X-Login': '{{X-Login}}',
  'X-Date': '{{X-Date}}',
  'Authorization': '{{Authorization}}',
  'X-Idempontency-Key': '{{X-Idempotency-Key}}',
  'Content-Type': 'application/json'
}
conn.request("POST", "/v3/deposits", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))


```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Notice that this request will return a Hosted Checkout because we didn't include the fields `payment_method`, `first_name` and `last_name` which are required for OneShot.
{% endhint %}

![Select payment\_method.](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/LZbIug9P0OllRDoQDXVD/Hosted%20Checkout-%201.jpg) ![Fill the missing information required.](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/oWoWyFywY9yWPkgbxn8b/Hosted%20Checkout-%202.jpg) ![Payment created! ](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/o5sfNRCZHW44s1H2lmC7/Hosted%20Checkout-%203.jpg)

### Hosted Checkout Response: Success

#### Response Fields

<table data-header-hidden><thead><tr><th>Field name</th><th width="185.33333333333331">Format</th><th>Description</th></tr></thead><tbody><tr><td>Field name</td><td>Format</td><td>Description</td></tr><tr><td><code>checkout_type</code></td><td>String</td><td>Field containing the type of the request. <code>[ONE_SHOT, HOSTED]</code></td></tr><tr><td><code>redirect_url</code></td><td>URL</td><td>URL used to redirect the customer to our Hosted Checkout</td></tr><tr><td><code>deposit_id</code></td><td>Number</td><td>ID of the deposit on Zimo-Pagos end</td></tr><tr><td><code>user_id</code></td><td>String</td><td>ID of the user on your end. If you didn't send it, it is generated by us</td></tr><tr><td><code>merchant_invoice_id</code></td><td>String</td><td>ID of the deposit on your end. If you didn't send it, make sure you save it as it is generated auto-generated and may be needed in the future (See <a href="/api-documentation/deposits-api/endpoints/refund-creation-endpoint">refunds</a>)</td></tr></tbody></table>

#### Response Example

```javascript
{
    "checkout_type": "HOSTED",
    "redirect_url": "https://payin-stg.zimo-pagos.com/validate/eyJhbGciOiJIUR_JErX-j3S1pVaD",
    "deposit_id": 300000010,
    "user_id": "4-2845801292757825290",
    "merchant_invoice_id": "100000001"
}
```

Click [here](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#error-responses) for the error response format.

## Error Response

### Error Response fields

| Field name    | Format | Description                                                                                                                                                      |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | Number | Error code. See the[ list of error codes](/api-documentation/deposits-api/api-codes#api-error-codes)                                                             |
| `description` | String | Description of the error                                                                                                                                         |
| `details[]`   | String | Details about the errors. It is not always shown                                                                                                                 |
| `type`        | String | Error code name. It is not always shown. See the [list of error codes](/api-documentation/deposits-api/api-codes#api-error-codes)                                |
| `reason_code` | Number | Reason code for KYC check failure. See the[ list of reason codes](/api-documentation/deposits-api/api-codes#fraud-reason-codes-for-kyc-errors)                   |
| `reason`      | String | Reason description for KYC check failure. See the [list of all reason descriptions](/api-documentation/deposits-api/api-codes#fraud-reason-codes-for-kyc-errors) |

### Error Response examples

{% hint style="success" %}
In case of error due to KYC check, we display two extra fields `reason` and `reason_code`. The list of errors can be[ found here](/api-documentation/deposits-api/api-codes#fraud-reason-codes-for-kyc-errors)
{% endhint %}

<pre class="language-java"><code class="lang-java">{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "payer.document: Invalid document type and/or document",
        "payer.address.state: Invalid State for Country"
    ]
}

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "amount: invalid numeric format",
        "country: Invalid value. Accepted values: AR|BR|CL|CM|CN|CO|EC|GH|IN|ID|KE|MY|MX|NG|PA|PE|PH|PY|TH|TZ|UG|UY|VN|ZA"
    ]
}

{
    "code": 502,
    "description": "Invalid request body",
    "type": "INVALID_REQUEST_BODY"
}

{
    "code": 304,
    "description": "The user limit has been exceeded: TRANSACTION",
    "type": "USER_LIMIT_EXCEEDED"
}
<strong>
</strong><strong>{
</strong><strong>    "code": 303,
</strong>    "description": "User rejected after KYC check",
    "type": "USER_REJECTED_KYC_CHECK",
    "reason": "Underage user detected",
    "reason_code": 105
}

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "invoiceId: must match \"^[A-Za-z0-9-_]*$\""
    ],
    "type": "BEAN_VALIDATION_ERROR"
}

</code></pre>

## Crypto payments

{% hint style="info" %}
Please get in touch with your Account Manager in order to start processing payments with Cryptocurrencies.
{% endhint %}

When processing payments to a Cryptocurrency e-wallet, you must send in the request an object called `crypto` with the `currency` the `wallet` address and the network the `wallet` belongs to. Please [click here](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#crypto-object) for more details about the `crypto` object.

To retrieve the actual exchange of any currency against a cryptocurrency, please use the [Crypto Exchange Endpoint.](broken://pages/-Mgvv50JyvXYXRKopN5I)

When a customer pays a crypto transaction, the money is **credited directly into the customer's wallet** address and not into your merchant balance. After the transaction was paid by the customer, the status of the transaction will be APPROVED while we are transferring the funds to the user's wallet. As soon as the money gets into the user's wallet, the deposit will change to COMPLETED status. Please [click here](/api-documentation/deposits-api/api-codes#deposits-status-codes) for more information about deposit statuses.

## Request Fields Description

| Field name                                                                            | Format                    | Description                                                                                                                                                                                                                                                  | Default |                                                    Validations                                                    |
| ------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-----: | :---------------------------------------------------------------------------------------------------------------: |
| `country`                                                                             | string (length: 2)        | Country code of the deposit in *ISO 3166-1 alpha-2 code* format                                                                                                                                                                                              |         |                               [Country codes](/countries-specifications#currencies)                               |
| `amount`                                                                              | decimal (max decimals: 2) | Deposit amount in the currency specified                                                                                                                                                                                                                     |         |                                 Number of up to 18 integers and 2 decimals places                                 |
| `currency`                                                                            | string (length: 3)        | Currency code of the amount in *ISO 4217* format                                                                                                                                                                                                             |  `USD`  |                                 [Currencies](/countries-specifications#currencies)                                |
| `invoice_id`                                                                          | string (max length: 128)  | Unique deposit ID on the merchant end                                                                                                                                                                                                                        |  random |                                                 `^[A-Za-z0-9-_]*$`                                                |
| `merchant_external_reference`                                                         | string                    | Optional parameter to include additional internal information on the merchant end.                                                                                                                                                                           |         |                                                                                                                   |
| <p><code>request\_payer\_data\_on</code></p><p><code>\_validation\_failure</code></p> | boolean                   | Boolean used to specify if you want to receive declines by invalid data even if it is not required by the payment method. [here](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#request_payer_data_on_validation_failure) for more info |  false  |                                                  `[true, false]`                                                  |
| `payer`                                                                               | object\[]                 | Object containing details about the customer                                                                                                                                                                                                                 |         |          [Payer object](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#payer-object)         |
| `payment_method`                                                                      | string (max length: 3)    | Payment method code                                                                                                                                                                                                                                          |         |                      [Payment method codes](/api-documentation/deposits-api/payment-methods)                      |
| `payment_type`                                                                        | string                    | Type of payment methods to show the customer. If `null` is sent and `payment_method` is `null`, `"ALL"` will be assumed                                                                                                                                      |   All   |                    [Payment types available](broken://pages/-M7hYgDIPRyR1p3XGmws#payment-types)                   |
| `payment_types`                                                                       | array                     | Same as `payment_type` but multiple payment methods' types can be specified with an array. I.e.: `payment_types: ["BANK_DEPOSIT", "BANK_TRANSFER"]`                                                                                                          |   All   |                    [Payment types available](broken://pages/-M7hYgDIPRyR1p3XGmws#payment-types)                   |
| `sub_merchant_id`                                                                     | integer                   | Used to specify for which SubMerchant ID the deposit will be created.                                                                                                                                                                                        |         |                                                                                                                   |
| `allow_installments`                                                                  | boolean                   | <p>Used to specify if the credit card deposit can be created with installments.<br>For more info visit this <a href="broken://pages/1FTJTSnhzrxlXxNqh0Gt">link</a>.</p>                                                                                      | `false` |                                                                                                                   |
| `reported_info`                                                                       | object\[]                 | Object containing details about the bank account from which the deposit will be made. Used in ONE\_SHOT mode to auto-detect user's payment                                                                                                                   |         | [reported\_info object](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#reported_info-object) |
| `bank_account`                                                                        | object\[]                 | Object containing details about the bank account from which the deposit will be made                                                                                                                                                                         |         |  [bank\_account object](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#bank_account-object)  |
| `expiration`                                                                          | numeric                   | <p></p><p>Used to express, in minutes, how long after its creation the deposit should expire. Cannot be more than the default expiration of the payment method.</p>                                                                                          |         |                                             Number of up to 5 integers                                            |
| `fee_on_payer`                                                                        | boolean                   | Choose if the deposit's fee will be paid by the customer or debited from your balance                                                                                                                                                                        | `false` |                                                  `[true, false]`                                                  |
| `surcharge_on_payer`                                                                  | boolean                   | Choose if the surcharge will be paid by the customer or debited from your balance                                                                                                                                                                            |  `true` |                                                  `[true, false]`                                                  |
| `bonus_amount`                                                                        | decimal (max decimals: 2) | <p>Used to show the customer a bonus amount. I.e.: <code>amount:100, bonus\_amount:50</code></p><p>User will see: Pay 100, receive 150</p>                                                                                                                   |         |                                     Number of up to 18 integers and 2 decimals                                    |
| `bonus_relative`                                                                      | boolean                   | Used to define if the `bonus_amount` was specified as a percentage of the `amount` or as an absolute value                                                                                                                                                   | `false` |                                                  `[true, false]`                                                  |
| `strikethrough_price`                                                                 | decimal (max decimals: 2) | <p>Used to show the customer a strikethrough amount. I.e.: <br>Before: <del>150</del><br>Now: 100</p>                                                                                                                                                        |         |                                     Number of up to 18 integers and 2 decimals                                    |
| `description`                                                                         | string (max length: 100)  | Deposit description. It will be shown to the customer on our Hosted Checkout as the description of the product to be acquired                                                                                                                                |         |                                           String of up to 100 characters                                          |
| `client_ip`                                                                           | string                    | Valid IPv4 or IPv6 Address                                                                                                                                                                                                                                   |         |                                                 `IPv4/v6 Address`                                                 |
| `device_id`                                                                           | string (max length: 100)  | Unique customer's device ID. Used to identify and prevent fraud.                                                                                                                                                                                             |         |                                           String of up to 100 characters                                          |
| `language`                                                                            | string (length: 2)        | Language to show the customer on the deposit page in *ISO 639-1 code* format. \*Not all the languages are available                                                                                                                                          |         |                                     String of 2 characters `[es, en, pt, ja]`                                     |
| `back_url`                                                                            | string (max length: 2048) | Valid URL over HTTPS used to redirect the customer in case of a pending (in process) deposit.                                                                                                                                                                |         |                                                    `HTTPS URL`                                                    |
| `success_url`                                                                         | string (max length: 2048) | Valid URL over HTTPS used to redirect the customer in case the deposit flow was completed.                                                                                                                                                                   |         |                                                    `HTTPS URL`                                                    |
| `error_url`                                                                           | string (max length: 2048) | Valid URL over HTTPS used to redirect the customer in case of error while generating the deposit                                                                                                                                                             |         |                                                    `HTTPS URL`                                                    |
| `notification_url`                                                                    | string (max length: 2048) | Valid URL over HTTPS used to receive the notifications about the deposit's changes of status. If none is sent, we will use the one configured on the Merchant Panel                                                                                          |         |                                                    `HTTPS URL`                                                    |
| `logo`                                                                                | string (max length: 2048) | Valid URL over HTTPS used to show your logo on our Hosted Checkout Experience. If none is sent, we will use the one configured on the Merchant Panel                                                                                                         |         |                                                    `HTTPS URL`                                                    |
| `test`                                                                                | boolean                   | Used to flag a deposit as test. If true, the deposit will not affect the merchant's balance                                                                                                                                                                  | `false` |                                                  `[true, false]`                                                  |
| `mobile`                                                                              | boolean                   | Used to specify if the redirection will be made on a mobile device                                                                                                                                                                                           | `false` |                                                  `[true, false]`                                                  |
| `early_release`                                                                       | boolean                   | Used to specify if the deposit should be early released. Useful when you want to release payments to your VIP users before it were completed                                                                                                                 | `false` |                                                  `[true, false]`                                                  |
| `requested_token`                                                                     | boolean                   | Used to indicate if the `checkout_token` is needed in the response.                                                                                                                                                                                          | `false` |                                                  `[true, false]`                                                  |

{% hint style="warning" %}
The fields `bonus_amount`, `bonus_relative`, `strikethrough_price`,  and `description` only affect our Hosted Checkout GUI and doesn't affect any balance or calculations.&#x20;
{% endhint %}

{% hint style="success" %}
Using the same back\_url, success\_url and error\_url is ok if you want to show your customers with a generic message when being redirected. Even better is to generate one unique link for each deposit for better user experience when being redirected. I.e.: `https://www.example.com/deposit/{deposit_id_hashed}/pending`
{% endhint %}

### Required flags

{% hint style="success" %}
We recommend sending the following flags to prevent declines and improve conversion rates.
{% endhint %}

#### mobile

The flag `mobile` is a boolean and has to be sent equal to **`true`** if the customer generating the deposit is using a mobile device/application. If not sent it defaults to **`false`**.

There are some payment methods that have a different flow on mobile devices compared to the flow on web devices because the payment method doesn't work the same way in those devices. When a deposit gets created as `ONE_SHOT`, it means the flow is assigned before the user navigates into our website, and therefore, we can't identify if the customer comes from a mobile device or not.&#x20;

Considering that, if the flag `mobile` is not sent we could route a mobile user through the web flow, therefore, affecting the ability of the customer to complete the deposit.

#### request\_payer\_data\_on\_validation\_failure

The flag `request_payer_data_on_validation_failure` can be used to prevent the request to be declined in case you send an invalid `payer.phone`, `payer.address.state` and/or `payer.address.zip_code`.

If it is required by the payment method, we will return you with a HOSTED CHECKOUT link where the customer will fill in the incorrect details on our checkout and if the details is not needed by the payment method, it will be ignored and the link for ONE SHOT will be returned.

Example responses:

{% tabs %}
{% tab title="Error" %}

```java
// With the flag request_payer_data_on_validation_failure = false
// or not sent (it defaults to false)

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "payer.address.zipCode: Invalid zip code format for Country",
        "payer.address.state: Invalid State for Country",
        "payer.phone: Invalid phone for Country"
    ],
    "type": "BEAN_VALIDATION_ERROR"
}

```

{% endtab %}

{% tab title="Success: HOSTED CHECKOUT" %}

```java
// With the flag request_payer_data_on_validation_failure = true
// The payment method requires any of the fields so a Hosted Checkout link 
// is returned to collect those

// Typical HOSTED response

{
    "checkout_type": "HOSTED",
    "redirect_url": "https://payin.zimo-pagos.com/validate/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiIzMzg4Mjc3OTIiLCJpYXQiOjE2MTY2MDcyMDIsImV4cCI6MTYxOTE5OTIwMn0.0-_gFW0F0Yk73J8SoAddPUaOrgsKILMVbYa1cZehrF_PEk6cj17dIXDDs6FRjkkd",
    "deposit_id": 338827792,
    "user_id": "4-1874596909371448397",
    "merchant_invoice_id": "postmanTest640841435"
}

```

{% endtab %}

{% tab title="Success: ONE SHOT" %}

```java
// With the flag request_payer_data_on_validation_failure = true
// The fields payer.phone, payer.address.state and payer.address.zip_code are not
// required for the payment method

// Typical ONE_SHOT response

{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://payment.zimo-pagos.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiIyMDQxNzcxMjMiLCJpYXQiOjE2MTY2MDY5NzcsImV4cCI6MTYxNzkwMjk3NywibGFuZ3VhZ2UiOiJwdCJ9.sVh4-WAW2Q5lehuDMWXhUuOVQUzqmN_XRrNBDhyOZUb36dWd9a6QX9i-JB_ocjWJ",
    "iframe": true,
    "deposit_id": 338827003,
    "user_id": "4-1874596909371448397",
    "merchant_invoice_id": "postmanTest806586134",
    "payment_info": {
        "type": "BANK_DEPOSIT",
        "payment_method": "B",
        "payment_method_name": "Bradesco",
        "amount": 571.03,
        "currency": "BRL",
        "expiration_date": "2021-03-24 22:29:37",
        "created_at": "2021-03-24 17:29:37",
        "metadata": {
            "reference": 204177123,
            "beneficiary_name": "zimo-pagos LLP",
            "account_type": "Conta corrente",
            "beneficiary_document_type": "CNPJ",
            "agency": "6444",
            "bank_url": "http://www.bradesco.com.br/html/classic/index.shtm",
            "beneficiary_document": "37.123.123/0001-53",
            "account": "49110-3"
        }
    }
}

```

{% endtab %}
{% endtabs %}

## Request Objects

### Payer Object

<table><thead><tr><th>Field name</th><th>Format</th><th>Description</th><th width="200" align="center">Default</th><th align="center">Validations</th><th align="center">Required</th></tr></thead><tbody><tr><td><code>id</code></td><td>string (max length: 128)</td><td>Customer's ID generated on your end. Used to locate user's transaction on our Merchant Panel</td><td align="center">If none is sent, we will autogenerate it</td><td align="center"><code>^[A-Za-z0-9]*$</code></td><td align="center">Recommended</td></tr><tr><td><code>document</code></td><td>string (max length: 30)</td><td>Customer's document ID. Ensure it is correct and the user can't change it every time he/she deposits</td><td align="center"></td><td align="center"><a href="/countries-specifications#documents">document validations</a></td><td align="center">Yes</td></tr><tr><td><code>document_type</code></td><td>string (max length: 10)</td><td>Customer's document type. Optional, if sent must be a valid document type</td><td align="center"></td><td align="center"><a href="/countries-specifications#documents">document types validations</a></td><td align="center">Yes</td></tr><tr><td><code>email</code></td><td>string (max length: 255)</td><td>Valid customer's email address</td><td align="center"></td><td align="center">Valid email address</td><td align="center">Yes</td></tr><tr><td><code>first_name</code></td><td>string (max length: 128)</td><td>Customer's first name</td><td align="center"></td><td align="center">String of up to 128 characters</td><td align="center">Yes</td></tr><tr><td><code>last_name</code></td><td>string (max length: 128)</td><td>Customer's last_name</td><td align="center"></td><td align="center">String of up to 128 characters</td><td align="center">Yes</td></tr><tr><td><code>address</code></td><td>object</td><td>Object containing customer's address details</td><td align="center"></td><td align="center"><a href="/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#payer-address-object">address object</a></td><td align="center">No</td></tr><tr><td><code>phone</code></td><td>string (max length: 32)</td><td>Valid customer's phone number</td><td align="center"></td><td align="center"><a href="/countries-specifications#mobile-numbers-validations">phone number validations</a></td><td align="center">No</td></tr><tr><td><code>birth_date</code></td><td>string (max length: 8)</td><td>Customer's birthdate in format yyyyMMdd. E.g.: 19801027</td><td align="center"></td><td align="center">Numeric format expected: <code>yyyyMMdd</code></td><td align="center">No</td></tr><tr><td><code>registration_date</code></td><td>string (max length: 8)</td><td>Customer's registration date in your website in UTC with format yyyyMMdd. E.g.: 20211123</td><td align="center"> </td><td align="center">Numeric format expected: <code>yyyyMMdd</code></td><td align="center">No</td></tr></tbody></table>

### Payer.address Object

| Field name | Format                   | Description                                                                              |                                                                        Validations                                                                       |
| ---------- | ------------------------ | ---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `street`   | string (max length: 255) | Customer's street                                                                        |                                                              String of up to 255 characters                                                              |
| `city`     | string (max length: 128) | Customer's city                                                                          |                                                              String of up to 128 characters                                                              |
| `state`    | string (max length: 3)   | Customer's state code in [*ISO 3166-2 code* format](broken://pages/-MN3ykPyMyFdel7P6Yr8) | Valid state code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format. Check our [States endpoint here](broken://pages/-MN3ykPyMyFdel7P6Yr8) |
| `zip_code` | string (max length: 16)  | Customer's zip code                                                                      |                                        [zip\_code validations](/countries-specifications#postal-code-validations)                                        |

### Reported\_info Object

This object will be used to auto-detect the user payment in our bank extracts.&#x20;

This information is mandatory for some payment methods if you would like to use the ONE\_SHOT experience by building your own cashiers with the metadata. If not sent, we will ask the customer for it on our hosted payment page.

If used with the redirect flows, we will automatically populate the fields with the information sent.

| Field name            | Format                   | Description                                |                                                 Validations                                                |
| --------------------- | ------------------------ | ------------------------------------------ | :--------------------------------------------------------------------------------------------------------: |
| `bank_account_number` | string (max length: 45)  | Bank account number of the customer        |                                        String of up to 45 characters                                       |
| `bank_branch`         | string (max length: 45)  | Bank branch of the customer's bank account |                                        String of up to 45 characters                                       |
| `bank_beneficiary`    | string (max length: 255) | Bank account owner name                    |                                       String of up to 255 characters                                       |
| `bank_account_type`   | string (max length: 16)  | Bank account type of the customer          | [List of account types](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#account-types) |

#### Payment Methods requiring the reported\_info object

See in the below table the list of fields required for each payment method.

| Country | Payment Method Code | Payment Method Name | Field Mask    | Field Regex                         | Field Name            |
| :-----: | :-----------------: | ------------------- | ------------- | ----------------------------------- | --------------------- |
|    BR   |          CA         | Caixa               |               |                                     | `bank_account_type`   |
|    BR   |          SJ         | Sicredi             |               | ^\[^\d\s]{2,30}(\s\[^\d\s]{2,30})+$ | `bank_beneficiary`    |
|    BR   |          B          | Bradesco            |               | ^\[^\d\s]{2,30}(\s\[^\d\s]{2,30})+$ | `bank_beneficiary`    |
|    BR   |          SF         | Banco Safra         |               | ^\[^\d\s]{2,30}(\s\[^\d\s]{2,30})+$ | `bank_beneficiary`    |
|    BR   |          BB         | Banco Brasil        | 00000000000-A | ^\d{1,11}-\[\da-zA-Z]$              | `bank_account_number` |
|    BR   |          BB         | Banco Brasil        | 0000-A        | ^\d{1,4}(-\[\da-zA-Z])?$            | `bank_branch`         |
|    BR   |          BZ         | Banco Original      | 0000          | ^\d{1,4}?$                          | `bank_branch`         |
|    BR   |          CA         | Caixa               | 0000          | ^\d{1,4}?$                          | `bank_branch`         |
|    BR   |          BZ         | Banco Original      | 000000000-0   | ^\d{1,9}-\d$                        | `bank_account_number` |
|    BR   |          CA         | Caixa               | 000000000-0   | ^\d{1,14}-\d$                       | `bank_account_number` |
|    CL   |          IA         | Itau                |               | ^\[^\d\s]{2,30}(\s\[^\d\s]{2,30})+$ | `bank_beneficiary`    |
|    CL   |          SC         | Santander           |               | ^\[^\d\s]{2,30}(\s\[^\d\s]{2,30})+$ | `bank_beneficiary`    |
|    CL   |          TY         | Security            |               | ^\[^\d\s]{2,30}(\s\[^\d\s]{2,30})+$ | `bank_beneficiary`    |
|    PA   |          DI         | Credicorp           |               | ^\[^\d\s]{2,30}(\s\[^\d\s]{2,30})+$ | `bank_beneficiary`    |
|    PE   |          BC         | BCP                 |               | ^\[^\d\s]{2,30}(\s\[^\d\s]{2,30})+$ | `bank_beneficiary`    |
|    PE   |          IB         | InterBank           |               | ^\[^\d\s]{2,30}(\s\[^\d\s]{2,30})+$ | `bank_beneficiary`    |

####

### Crypto object

This object will be used to specify that the deposit will be [credited into a crypto e-wallet](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#crypto-payments).

| Field name | Format                   | Description                            |                                                        Validations                                                        |
| ---------- | ------------------------ | -------------------------------------- | :-----------------------------------------------------------------------------------------------------------------------: |
| `currency` | string (max length: 10)  | Symbol of the Cryptocurrency           | [Valid Cryptocurrency symbol](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#cryptocurrency-symbols) |
| `wallet`   | string (max length: 128) | Address of the payer's crypto e-wallet |                                               String of up to 128 characters                                              |
| `network`  | string (max length: 12)  | Network of the wallet                  |                                                    Valid network symbol                                                   |

#### Cryptocurrency symbols

| Name        | Symbol |
| ----------- | ------ |
| Binance USD | BUSD   |
| DAI         | DAI    |
| RIF Dollar  | RDOC   |
| Tether      | USDT   |
| USD Coin    | USDC   |

#### Networks

| Network          | Symbol  |
| ---------------- | ------- |
| AVAX C-Chain     | AVAXC   |
| BNB Beacon Chain | BEP2    |
| BNB Smart Chain  | BEP20   |
| Ethereum         | ERC20   |
| Polygon          | Polygon |
| Solana           | Solana  |
| Tron             | TRC20   |
| Tezos            | Tezos   |
| RSK              | RSK     |

{% hint style="success" %}
For other networks not in that list please reach out to your Account Manager.
{% endhint %}

## Payment Methods fields requirements

Click on the link below to learn about our Payment Methods and the fields required for each of them:

{% content-ref url="/pages/-M7EyIJfwI7M7iTDXAkL" %}
[Payment Methods](/api-documentation/deposits-api/payment-methods)
{% endcontent-ref %}


# Notifications

Learn about how the notifications for deposits works

## 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**](broken://pages/-M7hYZI8TG8c1K-q33ly) **and update it on your end accordingly.**

{% hint style="info" %}
Bear in mind we will only connect through ports 80 and 443. Make sure your `notification_url` has one of those ports open accepting connections from us.
{% endhint %}

## 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](https://merchants-stg.directa24.com/login) 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**.

![Approve/Cancel from the Deposits view.](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/gQ6CDuJJuhL7R4cl4bAU/Screen%20Shot%202022-05-31%20at%2017.51.21.png) ![You can also Approve/Cancel deposits from the Transaction details](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/JAaRCZSSPktNwdmZuxew/Screen%20Shot%202022-05-31%20at%2017.54.04.png)

## Notifications fields

| Field        | Format | Description                                                                                               |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------- |
| `deposit_id` | Number | ID of the deposit. Use this ID to [check the status of the deposit.](broken://pages/-M7hYZI8TG8c1K-q33ly) |

## Notifications example

```javascript
{
    "deposit_id": 3000000001
}
```

## Retry logic

Every time a deposit changes its status, we will send you a notification so you can [check its status](broken://pages/-M7hYZI8TG8c1K-q33ly) 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.

{% hint style="success" %}
In case of errors while handling the notification, make sure you will answer with an HTTP code distinct than 2XX, that way we will retry the notification.
{% endhint %}

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:

![](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/NbmnhcIEB9LEU21PM1pp/image.png)

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.](broken://pages/-M7hYZI8TG8c1K-q33ly)

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.

{% hint style="success" %}
It can take up to 1 minute for the notification to be resent.
{% endhint %}

![](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/1jL0oyXTZEcCNntKRGkD/image.png)


# Deposit Status Endpoint

## Retrieve Deposit Status

> Retrieve the status of a previously created deposit. This endpoint allows you to retrieve the status of a deposit request.

```json
{"openapi":"3.0.0","info":{"title":"eroninternational Deposit API","version":"v3"},"servers":[{"url":"https://api-stg.eroninternational.com/v3","description":"Staging environment"}],"paths":{"/deposits/{deposit_id}":{"get":{"summary":"Retrieve Deposit Status","description":"Retrieve the status of a previously created deposit. This endpoint allows you to retrieve the status of a deposit request.","tags":["Deposits"],"parameters":[{"name":"deposit_id","in":"path","required":true,"description":"eroninternational deposit_id. It is obtained when creating the deposit.","schema":{"type":"integer"}},{"name":"Content-Type","in":"header","required":true,"description":"Media type of the body sent to the API. (Note: For GET, typically no request body)","schema":{"type":"string","default":"application/json"}},{"name":"X-Date","in":"header","required":true,"description":"ISO8601 Datetime with Timezone. Example: 2020-06-24T17:13:21Z","schema":{"type":"string","format":"date-time"}},{"name":"X-Login","in":"header","required":true,"description":"Merchant X-Login API Key","schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Authentication signature hash","schema":{"type":"string"}},{"name":"X-Idempotency-Key","in":"header","required":false,"description":"Unique idempotency key for ensuring that the same request is not processed more than once. (Typically for state-changing requests)","schema":{"type":"string"}}],"responses":{"200":{"description":"Deposit status successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositStatusResponse"}}}},"400":{"description":"The deposit_id specified is not valid"},"401":{"description":"Unauthorized access"},"404":{"description":"The deposit_id specified could not be found"}}}}},"components":{"schemas":{"DepositStatusResponse":{"title":"DepositStatusResponse","type":"object","properties":{"user_id":{"type":"string","description":"ID generated for the user on eron end"},"deposit_id":{"type":"integer","description":"ID of the deposit on eron end"},"subscription_id":{"type":"integer","nullable":true,"description":"ID of the Subscription that triggered the deposit"},"invoice_id":{"type":"string","description":"ID of the deposit on the merchant end"},"country":{"type":"string","nullable":true,"description":"Country ISO code"},"currency":{"type":"string","description":"Local currency code"},"local_amount":{"type":"number","format":"float","nullable":true,"description":"Amount in local currency"},"usd_amount":{"type":"number","format":"float","nullable":true,"description":"Amount in USD"},"amount":{"type":"number","format":"float","nullable":true,"description":"Amount in local currency"},"bonus_amount":{"type":"number","format":"float","nullable":true,"description":"The amount specified as bonus in the request"},"bonus_relative":{"type":"boolean","nullable":true,"description":"Specifies if bonus_amount is absolute or relative"},"payment_method":{"type":"string","nullable":true,"description":"Payment method code"},"payment_type":{"type":"string","nullable":true,"description":"Type of the payment method"},"status":{"type":"string","description":"Status of the deposit","enum":["COMPLETED","PENDING","CREATED","DECLINED","CANCELLED","EXPIRED","EARLY_RELEASED","FOR_REVIEW"]},"status_reason":{"type":"string","nullable":true,"description":"Reason why the deposit was rejected or expired. It is optional: it is null when there is no reason to report (for example, approved deposits). This list may grow over time; integrations should tolerate new values they do not recognize and must not fail when one appears.","enum":["INSUFFICIENT_FUNDS","CARD_DECLINED","TRANSACTION_NOT_PERMITTED","CARD_RESTRICTED","CARD_EXPIRED","CARD_LOST_OR_STOLEN","INVALID_CARD_DATA","INVALID_TRANSACTION","CALL_ISSUER","ISSUER_UNAVAILABLE","LIMIT_EXCEEDED","FRAUD_REJECTED","THREEDS_FAILED","THREEDS_ABANDONED","TOO_MANY_ATTEMPTS","DUPLICATED_PAYMENT","DUPLICATE_BILLING_IN_CYCLE","PAYER_ABANDONED","EXPIRED_NOT_PAID","THIRD_PARTY_PAYER","AMOUNT_MISMATCH","PROVIDER_ERROR","PLATFORM_ERROR","OTHER"]},"payer":{"$ref":"#/components/schemas/Payer","nullable":true},"fee_amount":{"type":"number","format":"float","nullable":true,"description":"Fee of the deposit"},"fee_currency":{"type":"string","nullable":true,"description":"Currency of the fee"},"refunded":{"type":"boolean","nullable":true,"description":"Shows if the deposit was refunded"},"current_payer_verification":{"type":"string","nullable":true,"description":"Current payer verification result","enum":["MATCH","UNMATCH","NO_CLIENT_DOCUMENT","NO_CURRENT_PAYER_DATA"]},"card_detail":{"$ref":"#/components/schemas/CardDetail","nullable":true},"financial_institution":{"$ref":"#/components/schemas/FinancialInstitution","nullable":true},"bank_account":{"$ref":"#/components/schemas/BankAccount","nullable":true},"provider_external_reference":{"type":"string","nullable":true,"description":"Reference of the transaction on the provider end"},"completed_payment_method_code":{"type":"string","nullable":true,"description":"Payment method used to complete the transaction"}}},"Payer":{"title":"Payer","type":"object","description":"Object containing information about the payer. Only values sent or collected will be shown.","properties":{"document":{"type":"string","description":"Payer's document of identity"},"document_type":{"type":"string","description":"Payer's document type"},"email":{"type":"string","format":"email","description":"Payer's email"},"first_name":{"type":"string","description":"Payer's first name"},"last_name":{"type":"string","description":"Payer's last name"},"phone":{"type":"string","description":"Payer's phone number"},"address":{"$ref":"#/components/schemas/PayerAddress"}}},"PayerAddress":{"title":"PayerAddress","type":"object","properties":{"city":{"type":"string","description":"Payer's city"},"state":{"type":"string","description":"Payer's state ISO code"},"street":{"type":"string","description":"Payer's street"},"zip_code":{"type":"string","description":"Payer's zip code"}}},"CardDetail":{"title":"CardDetail","type":"object","properties":{"card_holder":{"type":"string"},"brand":{"type":"string"},"masked_card":{"type":"string"},"expiration":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"card_type":{"type":"string","enum":["CREDIT","DEBIT"]},"transaction_result":{"type":"string"}}},"FinancialInstitution":{"title":"FinancialInstitution","type":"object","properties":{"name":{"type":"string"},"bank_code":{"type":"string"},"tax_identifier":{"type":"string"}}},"BankAccount":{"title":"BankAccount","type":"object","properties":{"bank_code":{"type":"string","nullable":true},"account_number":{"type":"string"},"bank_branch":{"type":"string","nullable":true},"ispb_code":{"type":"integer","nullable":true},"bank_name":{"type":"string","nullable":true},"account_type":{"type":"string","nullable":true},"account_holder":{"type":"string","nullable":true}}}}}}
```


# PCI Deposit Creation Endpoint

Learn how to use the PCI Deposit endpoint to create One Shot payments with credit cards

## Deposit creation

<mark style="color:green;">`POST`</mark> `https://cc-api-stg.zimo-pagos.com/v3/deposits`

This endpoint allows you to generate credit cards transactions by sending the Credit Card details.

#### Headers

| Name              | Type   | Description                                                                    |
| ----------------- | ------ | ------------------------------------------------------------------------------ |
| Content-Type      | string | `application/json`                                                             |
| X-Date            | string | <p>ISO8601 Datetime with Timezone: <br><code>yyyy-MM-dd'T'HH:mm:ssZ</code></p> |
| X-Login           | string | Merchant X-Login API Key                                                       |
| Authorization     | string | Authorization control hash                                                     |
| X-Idempotency-Key | string | Unique idempotency key                                                         |

#### Request Body

| Name                                          | Type    | Description                                                                           |
| --------------------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| country<mark style="color:red;">\*</mark>     | string  | Country of the transaction                                                            |
| amount<mark style="color:red;">\*</mark>      | number  | Amount of the transaction                                                             |
| currency<mark style="color:red;">\*</mark>    | string  | Currency of the amount specified                                                      |
| invoice\_id<mark style="color:red;">\*</mark> | string  | Unique deposit ID on the merchant end                                                 |
| payer<mark style="color:red;">\*</mark>       | object  | Object containing details about the customer. See  "Payer object" section for details |
| credit\_card                                  | object  | Object containing the credit card details                                             |
| card\_token                                   | string  | Card Token obtained from our Cards SDK                                                |
| description                                   | string  | Descriptor for the transaction                                                        |
| client\_ip<mark style="color:red;">\*</mark>  | string  | Valid IPv4/v6 Address of the customer                                                 |
| device\_id                                    | string  | Unique customer's device ID created using our JS library                              |
| fee\_on\_payer                                | boolean | Used to specify if you want to let the customer assume the deposit fee                |

{% tabs %}
{% tab title="200 Transaction successfully processed" %}

```java
{
  "deposit_id": 300604089,
  "user_id": "80000001",
  "merchant_invoice_id": "test766106146",
  "payment_info": {
      "type": "CREDIT_CARD",
      "result": "SUCCESS",
      "payment_method": "AE",
      "payment_method_name": "American Express",
      "amount": 505.95,
      "currency": "MXN",
      "created_at": "2021-02-05 22:10:45"
  }
}

```

{% endtab %}

{% tab title="400 Transaction failed due to field validation error" %}

```java
{
   "code": 201,
   "description": "Field validation error. Check details",
   "details": [
      "creditCard.cardNumber: size must be between 13 and 20, rejected value is 345678***********1090"
   ],
   "type": "BEAN_VALIDATION_ERROR"
}

```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The usage of this endpoint is restricted to PCI Compliant merchants who have shared their PCI AOC certificate with their Account Manager.
{% endhint %}

## V3 PCI Request

A request made through the **PCI Deposit Creation** endpoint works almost in the same way than the [non-PCI Deposits endpoint](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint) does, with the difference being on the `credit_card` object you need to send.

The transactions created using the V3 PCI endpoint will receive:

* Synchronic answer confirming the result of the transaction (in case that no 3DS authentication is required), hence no notifications will be sent by default.
* In case of requiring a 3DS Authentication of the payer, then the result of the transaction will be  `PENDING_AUTHENTICATION` in order to trigger the corresponding flow. In this case a webhook notification will be sent to check the final status of the Deposit.\
  Please visit [Deposits with 3DS Authentication](broken://pages/KDBOXgI3jFiNJwvvbPPF) for more details.

### Request Example

{% tabs %}
{% tab title="JSON" %}

```javascript
{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11111",
        "document": "84932568207",
        "document_type": "CPF",
        "email": "johnSmith12@hotmail.com",
        "first_name": "John",
        "last_name": "Smith",
        "phone": "+233852662222",
        "birth_date": "19880910",
        "address": {
            "street": "Calle 13",
            "city": "bahia",
            "state": "SP",
            "zip_code": "12345-678"
        }
    },
    "credit_card": {
        "cvv": "123",
        "card_number": "4111111111111111",
        "expiration_month": "10",
        "expiration_year": "25",
        "holder_name": "JOHN SMITH"
    },
    "description": "Test transaction",
    "client_ip": "123.123.123.123",
    "device_id": "knakvuejffkiebyab",
    "fee_on_payer": false
}
```

{% endtab %}
{% endtabs %}

###

### Response Example: Success/ Rejection / Pending Authentication

#### Response Fields

| Field name                         | Format  | Description                                                                                |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `deposit_id`                       | Integer | ID of the deposit generated on our end. Store this ID for future reference                 |
| `user_id`                          | String  | ID of the user. If you didn't send it, it is generated by us                               |
| `merchant_invoice_id`              | String  | ID of the deposit on your end. If you didn't send it, it is generated by us                |
| `payment_info`                     | Object  | Object containing the information about the payment                                        |
| `payment_info.type`                | String  | Type of transaction (Always CREDIT\_CARD)                                                  |
| `payment_info.result`              | String  | Status of the transaction: SUCCESS or REJECTED                                             |
| `payment_info.reason`              | String  | Transaction result. **Only shown in case of rejection**                                    |
| `payment_info.reason_code`         | String  | Code of the result. **Only shown in case of rejection**                                    |
| `payment_info.payment_method`      | String  | Payment method code. See the [list here.](/api-documentation/deposits-api/payment-methods) |
| `payment_info.payment_method_name` | String  | Payment method name. See the [list here.](/api-documentation/deposits-api/payment-methods) |
| `payment_info.amount`              | number  | Amount sent to the card acquirer                                                           |
| `payment_info.currency`            | string  | Currency of the amount sent to the card acquirer                                           |
| `payment_info.created_at`          | string  | Transaction date                                                                           |
| `authentication_url`               | URL     | URL to display to the end-user in order to complete the 3DS Authentication.                |

####

#### Response Example

{% tabs %}
{% tab title="Success" %}

```javascript
{
    "deposit_id": 300604089,
    "user_id": "80000001",
    "merchant_invoice_id": "test766106146",
    "payment_info": {
        "type": "CREDIT_CARD",
        "result": "SUCCESS",
        "payment_method": "AE",
        "payment_method_name": "American Express",
        "amount": 505.95,
        "currency": "MXN",
        "created_at": "2021-02-05 22:10:45"
    }
}

```

{% endtab %}

{% tab title="Rejection" %}

```javascript
{
    "deposit_id": 300604089,
    "user_id": "80000001",
    "merchant_invoice_id": "test766106146",
    "payment_info": {
        "type": "CREDIT_CARD",
        "result": "REJECTED",
        "reason": "Insufficient funds",
        "reason_code": "INSUFFICIENT_FUNDS",
        "payment_method": "AE",
        "payment_method_name": "American Express",
        "amount": 505.95,
        "currency": "MXN",
        "created_at": "2021-02-05 22:10:45"
    }
}

```

{% endtab %}

{% tab title="Pending Authentication" %}
This response will occur for all deposits that are eligible for a **3DS** Authentication.

```json
{ 
    "deposit_id": 300854027,
    "merchant_invoice_id": "postmanTest488131304", 
    "payment_info": { 
        "type": "CREDIT_CARD", 
        "result": "PENDING_AUTHENTICATION", 
        "reason": "Require 3DS Authentication", 
        "reason_code": "AUTHORIZATION_PENDING", 
        "payment_method": "VI", 
        "payment_method_name": "Visa", 
        "created_at": "2023-10-19 16:57:55", 
        "authentication_url": "https://checkout.cc-stg.directa24.com/authentication/MM15BgQjHVjGEpQLCYZQ1dBoMOcJuDAc" 
      } 
}
```

The `authentication_url` should be displayed to the end-user in order to proceed with the authentication, and posterior payment processing if successful.\
The URL can be opened within an iframe or a redirection into a new tab.
{% endtab %}

{% tab title="Pending Provider Authentication" %}
This response will occur for deposits which are pending 3DS authentication from the provider.

```json
    "deposit_id": 300854027,
    "merchant_invoice_id": "postmanTest488131304", 
    "payment_info": { 
        "type": "CREDIT_CARD", 
        "result": "IN_PROGRESS", 
        "reason": "Payment in progress, awaiting the acquirer's response.", 
        "reason_code": "PENDING_ACK", 
        "payment_method": "VI", 
        "payment_method_name": "Visa", 
        "created_at": "2023-10-19 16:57:55", 
        "authentication_url": "https://checkout.cc-stg.directa24.com/authentication/MM15BgQjHVjGEpQLCYZQ1dBoMOcJuDAc" 
      } 
}


```

The authentication\_url should be displayed to the end-user in order to proceed with the authentication, and posterior payment processing if successful. The URL can be opened within a redirection into a new tab.
{% endtab %}
{% endtabs %}

For more information about Pending Authentication results, please visit [Deposits with 3DS Authentication](broken://pages/KDBOXgI3jFiNJwvvbPPF).

### Response Example: Error

#### Response Fields

| Field name    | Format | Description                                                                                                                       |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | Number | Error code. See the[ list of error codes](/api-documentation/deposits-api/api-codes#api-error-codes)                              |
| `description` | String | Description of the error                                                                                                          |
| `details[]`   | String | Details about the errors. It is shown in case of invalid details                                                                  |
| `type`        | String | Error code name. It is not always shown. See the [list of error codes](/api-documentation/deposits-api/api-codes#api-error-codes) |

####

#### Response Example

```java
{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "payer.document: Invalid document type and/or document",
        "payer.address.state: Invalid State for Country"
    ]
}

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "amount: invalid numeric format",
        "country: Invalid value. Accepted values: AR|BR|CL|CM|CN|CO|EC|GH|IN|ID|KE|MY|MX|NG|PA|PE|PH|PY|TH|TZ|UG|UY|VN|ZA"
    ]
}

{
    "code": 502,
    "description": "Invalid request body",
    "type": "INVALID_REQUEST_BODY"
}

{
    "code": 304,
    "description": "The user limit has been exceeded",
    "type": "USER_LIMIT_EXCEEDED"
}

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "creditCard.cardNumber: size must be between 13 and 20, rejected value is 345678***********1090"
    ]
}
```

## Status reasons

Along with every REJECTED transaction, we will provide you with a `reason` and a `reason_code` you can use to map the error codes on your end.

| Transaction status |          Reason code          | Reason                                                                                      |
| :----------------: | :---------------------------: | ------------------------------------------------------------------------------------------- |
|     `REJECTED`     |      `EXTERNAL_HIGH_RISK`     | The card issuer rejected the payment because of their anti-fraud rules                      |
|     `REJECTED`     |      `TRX_NOT_SUPPORTED`      | Transaction type is not supported for acquirer                                              |
|     `REJECTED`     |     `INVALID_CARD_NUMBER`     | Invalid credit card number                                                                  |
|     `REJECTED`     |     `INVALID_CARD_HOLDER`     | Invalid card holder                                                                         |
|     `REJECTED`     |   `INVALID_CARD_EXPIRATION`   | Invalid expiration date                                                                     |
|     `REJECTED`     |    `INVALID_SECURITY_CODE`    | Invalid CVV/CVV2                                                                            |
|     `REJECTED`     |        `INVALID_ISSUER`       | Invalid card issuer                                                                         |
|     `REJECTED`     |         `INVALID_PIN`         | Invalid card pin                                                                            |
|     `REJECTED`     |      `DUPLICATE_PAYMENT`      | Payment duplicated                                                                          |
|     `REJECTED`     |     `MAX_ATTEMPTS_REACHED`    | Max attempts reached for this user and card                                                 |
|     `REJECTED`     |      `INSUFFICIENT_FUNDS`     | Insufficient funds                                                                          |
|     `REJECTED`     | `AUTHORIZATION_CALL_REQUIRED` | The transaction was rejected because the user needs to call their bank to activate the card |
|     `REJECTED`     |      `CARD_BIN_NOT_FOUND`     | Credit card bin number not found                                                            |
|     `REJECTED`     |         `CARD_EXPIRED`        | Credit card expired                                                                         |
|     `REJECTED`     |        `CARD_DECLINED`        | Card declined by issuer                                                                     |
|     `REJECTED`     |     `CARD_REPORTED_STOLEN`    | Card reported as stolen                                                                     |
|     `REJECTED`     |      `CARD_REPORTED_LOST`     | Card reported as lost                                                                       |
|     `REJECTED`     |   `CARD_RESTRICTED_BY_BANK`   | The card was blocked by the bank                                                            |
|     `REJECTED`     |    `CARD_REQUESTED_BY_BANK`   | The card is requested by the bank                                                           |
|     `REJECTED`     |       `CARD_BLACKLISTED`      | Card blacklisted                                                                            |
|     `REJECTED`     |        `CARD_DISABLED`        | Card disabled                                                                               |
|     `REJECTED`     |         `OTHER_REASON`        | Generic rejection reason                                                                    |

## Request Fields Description

<table data-header-hidden><thead><tr><th width="201">Field name</th><th width="115">Format</th><th width="232">Description</th><th align="center">Default</th><th width="153" align="center">Validations</th><th width="113" align="center"></th></tr></thead><tbody><tr><td>Field name</td><td>Format</td><td>Description</td><td align="center">Default</td><td align="center">Validations</td><td align="center">Required</td></tr><tr><td><code>country</code></td><td>string (length: 2)</td><td>Country code of the deposit in <em>ISO 3166-1 alpha-2 code</em> format</td><td align="center"></td><td align="center"><a href="/countries-specifications#currencies">Country codes</a></td><td align="center">Yes</td></tr><tr><td><code>amount</code></td><td>decimal (max decimals: 2)</td><td>Deposit amount in the currency specified</td><td align="center"></td><td align="center">Number of up to 18 integers and 2 decimals places</td><td align="center">Yes</td></tr><tr><td><code>currency</code></td><td>string (length: 3)</td><td>Currency code of the amount in <em>ISO 4217</em> format</td><td align="center"><code>USD</code></td><td align="center">See <a href="/countries-specifications#currencies">Currencies</a></td><td align="center">Yes</td></tr><tr><td><code>installments</code></td><td>integer (max length: 2)</td><td>Number of installments in which the deposit will take place.<br>*<strong>Check eligibility with your commercial contact.</strong></td><td align="center"></td><td align="center">Integer number between 1 and 12.</td><td align="center">No</td></tr><tr><td><code>invoice_id</code></td><td>string (max length: 128)</td><td>Unique deposit ID on the merchant end</td><td align="center">random</td><td align="center"><code>^[A-Za-z0-9-_]*$</code></td><td align="center">Yes</td></tr><tr><td><code>payer</code></td><td>object[]</td><td><a href="/api-documentation/deposits-api/endpoints/pci-deposit-creation-endpoint#payer-object">Object containing details about the payer</a></td><td align="center"></td><td align="center"><a href="/api-documentation/deposits-api/endpoints/pci-deposit-creation-endpoint#payer-object">Payer object</a></td><td align="center">Yes</td></tr><tr><td><code>credit_card</code></td><td>object[]</td><td><a href="/api-documentation/deposits-api/endpoints/pci-deposit-creation-endpoint#credit-card-object">Object containing the credit card details</a></td><td align="center"></td><td align="center"><a href="/api-documentation/deposits-api/endpoints/pci-deposit-creation-endpoint#credit-card-object">Credit card object</a></td><td align="center">No</td></tr><tr><td><code>description</code></td><td>string (max length: 100)</td><td>Transaction description. It could be shown on the customers credit card extract</td><td align="center"></td><td align="center">String of up to 100 characters</td><td align="center">No</td></tr><tr><td><code>client_ip</code></td><td>string</td><td>Valid IPv4 or IPv6 Address</td><td align="center"></td><td align="center"><code>IPv4/v6 Address</code></td><td align="center">Yes</td></tr><tr><td><code>device_id</code></td><td>string (max length: 100)</td><td>Unique customer's device ID. Used to identify and prevent fraud.</td><td align="center"></td><td align="center">String of up to 100 characters</td><td align="center">No</td></tr><tr><td><code>card_token</code></td><td>string (max length: 50)</td><td>Card Token generated with <a href="broken://pages/gpl6Eo7C77EIYtpkrRWu">Cards SDK Without User Interface</a>.</td><td align="center"></td><td align="center">String of up to 50 characters</td><td align="center">No</td></tr><tr><td><code>fee_on_payer</code></td><td>boolean</td><td>Choose if the deposit's fee will be paid by the customer or debited from your balance</td><td align="center"><code>false</code></td><td align="center"><code>[true, false]</code></td><td align="center">No</td></tr><tr><td><code>sub_merchant_id</code></td><td>integer</td><td>Used to specify for which SubMerchant ID the deposit will be created.</td><td align="center"></td><td align="center"></td><td align="center"></td></tr></tbody></table>

## Request Objects

### Credit Card Object

| Field name         | Format                         | Description                                          |                            Validations                           | Required |
| ------------------ | ------------------------------ | ---------------------------------------------------- | :--------------------------------------------------------------: | :------: |
| `cvv`              | String (max length: 4 digits)  | Credit card CVV/CVV2 code                            | <p><code>^\d{3,4}$</code></p><p>size must be between 3 and 4</p> |    Yes   |
| `card_number`      | String (max length: 16 digits) | The credit card number consisting of up to 16 digits |  [Luhn Algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm)  |    Yes   |
| `expiration_month` | String(length: 2)              | Credit card expiration month                         |                    `^(1[0-2]\|0[1-9]\|[1-9])$`                   |    Yes   |
| `expiration_year`  | String(length: 2)              | Credit card expiration year last two digits          |         <p><code>^\d{2}$</code></p><p>Valid year: 25</p>         |    Yes   |
| `holder_name`      | String (max length: 256)       | The name of the credit card owner                    |                            Valid name                            |    Yes   |

### Payer Object

<table data-header-hidden><thead><tr><th>Field name</th><th width="183">Format</th><th>Description</th><th align="center">Default</th><th align="center">Validations</th><th align="center"></th></tr></thead><tbody><tr><td>Field name</td><td>Format</td><td>Description</td><td align="center">Default</td><td align="center">Validations</td><td align="center">Required</td></tr><tr><td><code>id</code></td><td>string (max length: 128)</td><td>Customer's ID generated on your end. Used to locate user's transaction on our Merchant Panel</td><td align="center">If none is sent, we will autogenerate it</td><td align="center"><code>^[A-Za-z0-9]*$</code></td><td align="center">Recommended</td></tr><tr><td><code>document</code></td><td>string (max length: 30)</td><td>Customer's document ID. Ensure it is correct and the user can't change it every time he/she deposits</td><td align="center"></td><td align="center"><a href="/countries-specifications#documents">document validations</a></td><td align="center">Yes</td></tr><tr><td><code>document_type</code></td><td>string (max length: 10)</td><td>Customer's document type. Optional, if sent must be a valid document type</td><td align="center"></td><td align="center"><a href="/countries-specifications#documents">document types validations</a></td><td align="center">Yes</td></tr><tr><td><code>email</code></td><td>string (max length: 255)</td><td>Valid customer's email address</td><td align="center"></td><td align="center">Valid email address</td><td align="center">Yes</td></tr><tr><td><code>first_name</code></td><td>string (max length: 128)</td><td>Customer's first name</td><td align="center"></td><td align="center">String of up to 128 characters</td><td align="center">Yes</td></tr><tr><td><code>last_name</code></td><td>string (max length: 128)</td><td>Customer's last name</td><td align="center"></td><td align="center">String of up to 128 characters</td><td align="center">Yes</td></tr><tr><td><code>address</code></td><td>object[]</td><td><a href="/api-documentation/deposits-api/endpoints/pci-deposit-creation-endpoint#payer-address-object">Object containing customer's address details</a></td><td align="center"></td><td align="center"><a href="/api-documentation/deposits-api/endpoints/pci-deposit-creation-endpoint#payer-address-object">address object</a></td><td align="center">No</td></tr><tr><td><code>phone</code></td><td>string (max length: 32)</td><td>Valid customer's phone number</td><td align="center"></td><td align="center"><a href="/countries-specifications#mobile-numbers-validations">phone number validations</a></td><td align="center">No</td></tr><tr><td><code>birth_date</code></td><td>string (max length: 8)</td><td>Customer's birthdate in format yyyyMMdd. E.g.: 19801027</td><td align="center"></td><td align="center">Numeric format expected: <code>yyyyMMdd</code></td><td align="center">No</td></tr></tbody></table>

### Payer.address Object

| Field name | Format                   | Description                                                                              |                                                                        Validations                                                                       | Required |
| ---------- | ------------------------ | ---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------: | :------: |
| `street`   | string (max length: 255) | Customer's street                                                                        |                                                              String of up to 255 characters                                                              |    No    |
| `city`     | string (max length: 128) | Customer's city                                                                          |                                                              String of up to 128 characters                                                              |    No    |
| `state`    | string (max length: 3)   | Customer's state code in [*ISO 3166-2 code* format](broken://pages/-MN3ykPyMyFdel7P6Yr8) | Valid state code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format. Check our [States endpoint here](broken://pages/-MN3ykPyMyFdel7P6Yr8) |    No    |
| `zip_code` | string (max length: 16)  | Customer's zip code                                                                      |                                        [zip\_code validations](/countries-specifications#postal-code-validations)                                        |    No    |

## Card Numbers for Testing

In the following table you will find card numbers from specific brands to test different payment flows and our systems' responses.

{% hint style="info" %}
For all **Results**:

* Expiration date has to be in the future (`expiration_month` *+* `expiration_year)`
* `cvv`: any three numeric digits.
* `holder_name` : any name.
  {% endhint %}

{% hint style="success" %}
For **Success** Results in STG: any card number not listed below, will simulate a success scenario.\
(For example, Card Number: 4111111111111111)
{% endhint %}

### Visa

| **Card Number**  | **Result**                                                              |
| ---------------- | ----------------------------------------------------------------------- |
| 4222222222222220 | Card Rejected.                                                          |
| 4000000000000060 | Card Expired.                                                           |
| 4444444444444440 | Insufficient funds.                                                     |
| 4000000000000110 | Card reported as stolen.                                                |
| 4000000000000040 | The card issuer rejected the payment because of their anti-fraud rules. |

### Mastercard

| **Card Number**  | **Result**                                                              |
| ---------------- | ----------------------------------------------------------------------- |
| 5454545454545450 | Card Rejected.                                                          |
| 5555555555554440 | Card Expired.                                                           |
| 5105105105105100 | Insufficient funds.                                                     |
| 5451951574925480 | Card reported as stolen.                                                |
| 5406251139676600 | The card issuer rejected the payment because of their anti-fraud rules. |

### American Express

| **Card Number** | **Result**                                                              |
| --------------- | ----------------------------------------------------------------------- |
| 340000000000009 | Card Rejected.                                                          |
| 373737373737374 | Card Expired.                                                           |
| 370000000000002 | Insufficient funds.                                                     |
| 343434343434343 | Card reported as stolen.                                                |
| 341111111111111 | The card issuer rejected the payment because of their anti-fraud rules. |

### JCB

| **Card Number**  | **Result**                                                              |
| ---------------- | ----------------------------------------------------------------------- |
| 3530185156387080 | Card Rejected.                                                          |
| 3566002020360500 | Card Expired.                                                           |
| 3555555555555552 | Insufficient funds.                                                     |
| 3539189698635270 | Card reported as stolen.                                                |
| 3588430314874690 | The card issuer rejected the payment because of their anti-fraud rules. |


# Refund Creation Endpoint

Create refunds requests from a completed deposit

## Refund Creation

<mark style="color:green;">`POST`</mark> `https://api-stg.zimo-pagos.com/v3/refunds`

This endpoint allows you to create a full or a partial refund over a completed deposit.

#### Headers

| Name              | Type   | Description                                              |
| ----------------- | ------ | -------------------------------------------------------- |
| Content-Type      | string | `application/json`                                       |
| X-Date            | string | ISO8601 Datetime with Timezone: `yyyy-MM-dd'T'HH:mm:ssZ` |
| X-Login           | string | Merchant X-Login API Key                                 |
| Authorization     | string | Authorization control hash                               |
| X-Idempotency-Key | string | Unique idempotency key                                   |

#### Request Body

| Name              | Type    | Description                                                                                            |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| deposit\_id       | integer | Zimo-pagos `deposit_id`. It is obtained when creating the deposit                                      |
| invoice\_id       | string  | The `invoice_id` you sent while creating the deposit or the `merchant_invoice_id` auto-generated by us |
| amount            | number  | Amount to refund. If none is sent, the full deposit amount is assumed                                  |
| bank\_account     | object  | Object containing the information of the beneficiary. Not needed for credit cards                      |
| comments          | string  | Commentaries about the refund, if any                                                                  |
| notification\_url | string  | HTTPS URL used to send the notifications about refund's change of status                               |

{% tabs %}
{% tab title="200 Refund created successfully" %}

```java
{
    "refund_id": 168284
}
```

{% endtab %}

{% tab title="400 Error in the request" %}

```java
{
    "code": 802,
    "description": "Amount to refund not valid",
    "type": "INVALID_AMOUNT_TO_REFUND"
}
```

{% endtab %}

{% tab title="404 Deposit not found" %}

```java
{
    "code": 208,
    "description": "Resource not found",
    "type": "RESOURCE_NOT_FOUND"
}
```

{% endtab %}
{% endtabs %}

## Description

The **`refunds`** endpoint allows you to create a **full/partial**(depending on the market) **r**efund over a Credit Card deposit in **completed** state or **full/partial** refunds over other payment methods' deposits in **completed** state.

In the case of credit cards, since the refund will be processed to the same card, all you need to send are the fields to identify the deposit.

In the case of other payment methods where we don't have the account of the payer, you need to send the beneficiary's ID, bank account details and bank code retrieved with the[ Endpoint for Bank Codes.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)

You can create as many refunds as needed over a completed deposit, as long as the total amount of those refunds doesn't exceed the original amount deposited.

## Refunds Request

In order to start creating refunds, you need to:

1. Send the request with **POST** method.
2. Use the headers described [here](/api-documentation/deposits-api/technical-and-security-aspects#headers).
3. Specify a valid `deposit_id` and `invoice_id` related to the deposit to be refunded.
4. Send the Authorization header calculated in the same way than for deposits, as [explained here](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature).
5. Send the body of the request as JSON.

## Example Request

{% tabs %}
{% tab title="cURL" %}

```java
// CASH Method:

curl --location --request POST 'https://api-stg.zimo-pagos.com/v3/refunds' \
--header 'X-Login: {{X-Login}}' \
--header 'X-Date: {{X-Date}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "deposit_id": 300533646,
    "invoice_id": "newIUnit45328731",
    "amount": "100",
    "bank_account": {
        "beneficiary": "Carlos Ramirez",
        "bank_code": 1,
        "branch": "9283",
        "account_number": "18293435",
        "account_type": "SAVING"
    },
    "comments": "Test refund over v3",
    "notification_url": "https://webhook.site/url"
}'


// CREDIT CARD method:

curl --location --request POST 'https://api-stg.zimo-pagos.com/v3/refunds' \
--header 'X-Login: {{X-Login}}' \
--header 'X-Date: {{X-Date}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "deposit_id": 300533647,
    "invoice_id": "newIUnit45328732",
    "comments": "Test CREDIT CARD refund over v3",
    "notification_url": "https://webhook.site/url"
}'
```

{% endtab %}

{% tab title="JAVA" %}

```java
import java.io.*;
import okhttp3.*;
public class main {
  public static void main(String []args) throws IOException{
    OkHttpClient client = new OkHttpClient().newBuilder()
      .build();
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, "{\n    \"deposit_id\": 300533646,\n    \"invoice_id\": \"newIUnit45328731\",\n    \"amount\": \"100\",\n    \"bank_account\": {\n        \"beneficiary\": \"Carlos Ramirez\",\n        \"bank_code\": 1,\n        \"branch\": \"9283\",\n        \"account_number\": \"18293435\",\n        \"account_type\": \"SAVING\"\n    },\n    \"comments\": \"Test refund over v3\",\n    \"notification_url\": \"https://webhook.site/url\"\n}");
    Request request = new Request.Builder()
      .url("https://api-stg.zimo-pagos.com/v3/refunds")
      .method("POST", body)
      .addHeader("X-Login", "{{X-Login}}")
      .addHeader("X-Date", "{{X-Date}}")
      .addHeader("Authorization", "{{Authorization}}")
      .addHeader("Content-Type", "application/json")
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
  }
}


```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using RestSharp;
namespace HelloWorldApplication {
    class HelloWorld {
        static void Main(string[] args) {
            var client = new RestClient("https://api-stg.zimo-pagos.com/v3/refunds");
            client.Timeout = -1;
            var request = new RestRequest(Method.POST);
            request.AddHeader("X-Login", "{{X-Login}}");
            request.AddHeader("X-Date", "{{X-Date}}");
            request.AddHeader("Authorization", "{{Authorization}}");
            request.AddHeader("Content-Type", "application/json");
            request.AddParameter("application/json", "{\n    \"deposit_id\": 300533646,\n    \"invoice_id\": \"newIUnit45328731\",\n    \"amount\": \"100\",\n    \"bank_account\": {\n        \"beneficiary\": \"Carlos Ramirez\",\n        \"bank_code\": 1,\n        \"branch\": \"9283\",\n        \"account_number\": \"18293435\",\n        \"account_type\": \"SAVING\"\n    },\n    \"comments\": \"Test refund over v3\",\n    \"notification_url\": \"https://webhook.site/url\"\n}",  ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}


```

{% endtab %}

{% tab title="PHP" %}

<pre class="language-php"><code class="lang-php"><strong>&#x3C;?php
</strong>
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.zimo-pagos.com/v3/refunds",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>"{\n    \"deposit_id\": 300533646,\n    \"invoice_id\": \"newIUnit45328731\",\n    \"amount\": \"100\",\n    \"bank_account\": {\n        \"beneficiary\": \"Carlos Ramirez\",\n        \"bank_code\": 1,\n        \"branch\": \"9283\",\n        \"account_number\": \"18293435\",\n        \"account_type\": \"SAVING\"\n    },\n    \"comments\": \"Test refund over v3\",\n    \"notification_url\": \"https://webhook.site/url\"\n}",
  CURLOPT_HTTPHEADER => array(
    "X-Login: {{X-Login}}",
    "X-Date: {{X-Date}}",
    "Authorization: {{Authorization}}",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


</code></pre>

{% endtab %}
{% endtabs %}

### Request fields description

<table data-header-hidden><thead><tr><th width="192">Field</th><th>Format</th><th>Description</th><th align="center">Validations</th></tr></thead><tbody><tr><td>Field</td><td>Format</td><td>Description</td><td align="center">Validations</td></tr><tr><td><code>deposit_id</code></td><td>Integer</td><td>Zimo-pagos <code>deposit_id</code>. It is obtained when <a href="/api-documentation/deposits-api/endpoints/deposit-creation-endpoint">creating the deposit</a></td><td align="center">Valid <code>deposit_id</code> of a completed deposit</td></tr><tr><td><code>invoice_id</code></td><td>String (max length: 128)</td><td>The <code>invoice_id</code> you sent while <a href="/api-documentation/deposits-api/endpoints/deposit-creation-endpoint">creating the deposit</a> or the <code>merchant_invoice_id</code> auto-generated by us</td><td align="center">Valid <code>invoice_id</code> of a completed deposit</td></tr><tr><td><code>amount</code></td><td>Big decimal (positive, up to 2 decimals)</td><td>Amount to refund. Only used in case of partial refunds. If none is sent, a full refund will be assumed</td><td align="center">Positive. Equal or smaller than the deposit amount</td></tr><tr><td><code>bank_account[]</code></td><td>Object[]</td><td>Object containing the details where the refund should be sent to</td><td align="center"></td></tr><tr><td><code>comments</code></td><td>String (max length: 200)</td><td>Commentaries about the refund, if any</td><td align="center">String of up to 200 characters</td></tr><tr><td><code>notification_url</code></td><td>String (max length: 2048)</td><td>Valid HTTPS URL used to send the notifications about refund's change of status</td><td align="center">HTTPS URL</td></tr></tbody></table>

### `bank_account` Object <a href="#bank_account-object" id="bank_account-object"></a>

| Field name       | Format                   | Description                                                                                                                                   |                                                                     Validations                                                                     |
| ---------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------: |
| `beneficiary`    | string (max length: 255) | Beneficiary's name and last name                                                                                                              |                                                            String of up to 255 characters                                                           |
| `document_type`  | string (max length: 10)  | Beneficiary's document type                                                                                                                   | <p>Valid document type for the country of the deposit.</p><p><a href="/countries-specifications#documents-validations">See validations here</a></p> |
| `document`       | string (max length: 30)  | Beneficiary's document ID                                                                                                                     |    <p>Valid document for the country of the deposit.</p><p><a href="/countries-specifications#documents-validations">See validations here</a></p>   |
| `bank_code`      | string (max length: 5)   | Beneficiary's valid `bank_code` for the country. Use the [Bank Codes Endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) |                                    [Bank Codes API](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)                                   |
| `branch`         | string (max length: 45)  | Beneficiary's bank branch                                                                                                                     |                                                            String of up to 45 characters                                                            |
| `account_number` | string (max length: 45)  | Beneficiary's bank account number                                                                                                             |                                                            String of up to 45 characters                                                            |
| `account_type`   | string (max length: 45)  | Beneficiary's account type                                                                                                                    |                             [List of account\_type](/api-documentation/cashouts-api/countries-validations#account-types)                            |

#### Account types

<table data-header-hidden><thead><tr><th width="409">account_type</th><th>Description</th></tr></thead><tbody><tr><td><code>account_type</code></td><td>Description</td></tr><tr><td>SAVING</td><td>Savings account</td></tr><tr><td>CHECKING</td><td>Checkings account</td></tr><tr><td>VISTA</td><td>Salary account</td></tr><tr><td>MASTER</td><td>Master account</td></tr><tr><td>SAVING_SET</td><td>Joint savings account</td></tr><tr><td>CHECKING_SET</td><td>Joint checkings</td></tr><tr><td>DEFAULT</td><td>Default</td></tr></tbody></table>

## Example Response

### CASH Success Response Example

```java
{
    "refund_id": 168284
}
```

### CASH Success Response Fields

| Field       | Format  | Description                                                                                                                                           |
| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `refund_id` | Integer | ID of the refund on Zimo-pagos end. Store this ID for future [checks of its status](/api-documentation/deposits-api/endpoints/refund-status-endpoint) |

### CREDIT CARD Responses Example

{% tabs %}
{% tab title="SUCCESS" %}

```java
{
    "refund_id": "80000001",
    "deposit_id": 300604089,
    "merchant_invoice_id": "test766106146",
    "refund_info": {
        "type": "CREDIT_CARD",
        "result": "SUCCESS",
        "payment_method": "AE",
        "payment_method_name": "American Express",
        "amount": 505.95,
        "currency": "MXN",
        "created_at": "2021-02-05 22:10:45"
    }
}
```

{% endtab %}

{% tab title="IN PROGRESS" %}

```java
{
    "refund_id": "80000001",
    "deposit_id": 300604089,
    "merchant_invoice_id": "test766106146",
    "refund_info": {
        "type": "CREDIT_CARD",
        "result": "IN_PROGRESS",
        "reason": "Check refund status or await its notification",
        "payment_method": "AE",
        "payment_method_name": "American Express",
        "amount": 505.95,
        "currency": "MXN",
        "created_at": "2021-02-05 22:10:45"
    }
}
```

{% endtab %}

{% tab title="REJECTED" %}

<pre class="language-java"><code class="lang-java"><strong>{
</strong>    "refund_id": "80000001",
<strong>    "deposit_id": 300604089,
</strong>    "merchant_invoice_id": "test766106146",
    "refund_info": {
        "type": "CREDIT_CARD",
        "result": "REJECTED",
        "reason": "Insufficient funds",
        "reason_code": "INSUFFICIENT_FUNDS",
        "payment_method": "AE",
        "payment_method_name": "American Express",
        "amount": 505.95,
        "currency": "MXN",
        "created_at": "2021-02-05 22:10:45"
    }
}
</code></pre>

{% endtab %}
{% endtabs %}

When the refund is made over a CREDIT CARD deposit, it might be (depending upon availability) completed instantaneously, and so all the details of the refund are returned.

In case the result is SUCCESS, it means the refund was successfully created and the user should receive the money back into their card soon.&#x20;

In case the result is REJECTED, the response of the API will return two fields called `reason` and `reason_code` providing more information about the rejection reason.

In case the result is IN\_PROGRESS, it means the refund will be processed asynchronously and so a notification will be sent to the `notification_url` specified at the time of creating the refund as soon as it gets completed or rejected. [Click here](/api-documentation/deposits-api/endpoints/refund-creation-endpoint/notifications) for more information about the notifications of the refunds.

### Error Responses Example

```java
// Invalid amount to refund. The amount is bigger than the deposit or
// it has been already refunded
{
    "code": 802,
    "description": "Amount to refund not valid",
    "type": "INVALID_AMOUNT_TO_REFUND"
}

// The object_bank account needs to be sent
{
    "code": 804,
    "description": "Missing bank account information",
    "type": "MISSING_BANK_ACCOUNT"
}

// The deposit_id and/or the merchant_invoice_id didn't belong to a deposit
{
    "code": 208,
    "description": "Resource not found",
    "type": "RESOURCE_NOT_FOUND"
}

```

### Error Responses Fields

| Field         | Format  | Description                                                                                                                                    |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | Integer | Error code. [Click here to check all the possible error codes for refund](/api-documentation/deposits-api/api-codes#refund-error-codes)        |
| `description` | String  | Description of the error                                                                                                                       |
| `type`        | String  | Type of the error. [Click here to check all the possible error types for refund](/api-documentation/deposits-api/api-codes#refund-error-codes) |

�


# Notifications

Learn about how the notifications for refunds works

## 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**[ ](broken://pages/-M7hYZI8TG8c1K-q33ly)[**Refund Status Endpoint**](/api-documentation/deposits-api/endpoints/refund-status-endpoint) **and update it on your end accordingly.**

{% hint style="info" %}
Bear in mind we will only connect through ports 80 and 443. Make sure your `notification_url` has one of those ports open accepting connections from us.
{% endhint %}

## Notifications fields

| Field       | Format | Description                                                                                                                          |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `refund_id` | Number | ID of the refund. Use this ID to [check the status of the refund.](/api-documentation/deposits-api/endpoints/refund-status-endpoint) |

## Notifications example

```java
{
    "refund_id": 168284
}
```

## Retry logic

Every time a refund changes its status, we will send you a notification so you can [check its status](/api-documentation/deposits-api/endpoints/refund-status-endpoint) 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:

![](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/NbmnhcIEB9LEU21PM1pp/image.png)

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 [Refund Status Endpoint.](/api-documentation/deposits-api/endpoints/refund-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 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.

{% hint style="success" %}
It can take up to 1 minute for the notification to be resent in PROD and 3 on STG.
{% endhint %}

![](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/1jL0oyXTZEcCNntKRGkD/image.png)


# Refund Status Endpoint

Retrieve the status of a previously created refund

## Refund Status

<mark style="color:blue;">`GET`</mark> `https://api-stg.zimo-pagos.com/v3/refunds/{refund_id}`

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

#### Path Parameters

| Name                                         | Type    | Description                                                    |
| -------------------------------------------- | ------- | -------------------------------------------------------------- |
| refund\_id<mark style="color:red;">\*</mark> | Integer | Zimo-pagos refund\_id. It is obtained when creating the refund |

#### Query Parameters

| Name    | Type    | Description                                                                                                                    |
| ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| voucher | Boolean | `true` / `false` value,  The request with  True value will return the refund invoice in base64 to be decoded to create a .pdf. |

#### Headers

| Name                                            | Type   | Description                                              |
| ----------------------------------------------- | ------ | -------------------------------------------------------- |
| X-Date<mark style="color:red;">\*</mark>        | String | ISO8601 Datetime with Timezone: `yyyy-MM-dd'T'HH:mm:ssZ` |
| X-Login<mark style="color:red;">\*</mark>       | String | Merchant X-Login API Key                                 |
| Authorization<mark style="color:red;">\*</mark> | String | Authentication signature hash                            |

{% tabs %}
{% tab title="200 Refund status successfully retrieved." %}

```java
{
    "deposit_id": 300533646,
    "merchant_invoice_id": "newIUnit45328731",
    "status": "PENDING"
}
```

{% endtab %}

{% tab title="404 The refund with the refund\_id specified could not be found." %}

```java
{
    "code": 208,
    "description": "Resource not found",
    "type": "RESOURCE_NOT_FOUND"
}
```

{% endtab %}
{% endtabs %}

## 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 [notification](/api-documentation/deposits-api/endpoints/refund-creation-endpoint/notifications) 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 [here](/api-documentation/deposits-api/technical-and-security-aspects#headers).
3. Specify a valid `refund_id` in the URL of the request as PATH PARAMETERS.
4. Send the Authorization header, as [explained here](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature).

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.

{% tabs %}
{% tab title="cURL" %}

<pre class="language-bash"><code class="lang-bash"><strong>curl --location --request GET 'https://api-stg.zimo-pagos.com/v3/refunds/1682844' \
</strong>--header 'X-Login: {{X-Login}}' \
--header 'X-Date: {{X-Date}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Content-Type: application/json' \
--data-raw ''


</code></pre>

{% endtab %}

{% tab title="JAVA" %}

<pre class="language-java"><code class="lang-java">import java.io.*;
import okhttp3.*;
public class main {
  public static void main(String []args) throws IOException{
<strong>    OkHttpClient client = new OkHttpClient().newBuilder()
</strong>      .build();
    Request request = new Request.Builder()
      .url("https://api-stg.zimo-pagos.com/v3/refunds/1682844")
      .method("GET", null)
      .addHeader("X-Login", "{{X-Login}}")
      .addHeader("X-Date", "{{X-Date}}")
      .addHeader("Authorization", "{{Authorization}}")
      .addHeader("Content-Type", "application/json")
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
  }
}


</code></pre>

{% endtab %}

{% tab title="C#" %}

<pre class="language-csharp"><code class="lang-csharp">using System;
<strong>using RestSharp;
</strong>namespace HelloWorldApplication {
    class HelloWorld {
        static void Main(string[] args) {
            var client = new RestClient("https://api-stg.zimo-pagos.com/v3/refunds/1682844");
            client.Timeout = -1;
            var request = new RestRequest(Method.GET);
            request.AddHeader("X-Login", "{{X-Login}}");
            request.AddHeader("X-Date", "{{X-Date}}");
            request.AddHeader("Authorization", "{{Authorization}}");
            request.AddHeader("Content-Type", "application/json");
            request.AddParameter("application/json", "",  ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}


</code></pre>

{% endtab %}

{% tab title="PHP" %}

<pre class="language-php"><code class="lang-php"><strong>&#x3C;?php
</strong>
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.zimo-pagos.com/v3/refunds/1682844",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "X-Login: {{X-Login}}",
    "X-Date: {{X-Date}}",
    "Authorization: {{Authorization}}",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


</code></pre>

{% endtab %}
{% endtabs %}

## Example response

{% tabs %}
{% tab title="COMPLETED" %}

```java
{
    "deposit_id": 300533569,
    "merchant_invoice_id": "84044",
    "status": "COMPLETED",
    "amount": 100.00
}
```

{% endtab %}

{% tab title="PENDING" %}

```java
{
    "deposit_id": 300502126,
    "merchant_invoice_id": "84121",
    "status": "PENDING"
}
```

{% endtab %}
{% endtabs %}

### Response fields

<table data-header-hidden><thead><tr><th width="249">Field name</th><th width="117.33333333333331">Format</th><th>Description</th></tr></thead><tbody><tr><td>Field name</td><td>Format</td><td>Description</td></tr><tr><td><code>deposit_id</code></td><td>Integer</td><td>ID of the deposit refunded</td></tr><tr><td><code>merchant_invoice_id</code></td><td>String</td><td>Merchant invoice id of the deposit refunded</td></tr><tr><td><code>status</code></td><td>Enum</td><td>Status of the refund. <a href="/api-documentation/deposits-api/api-codes#refunds-status-codes">Click here for the full list of refund codes.</a></td></tr><tr><td><code>amount</code></td><td>Number</td><td>Amount of the refund</td></tr><tr><td><code>voucher</code></td><td>String</td><td>Proof of refund in base64 coding for generation of <code>.pdf</code> file.<br>Included in response only if <code>voucher</code> is sent as <code>true</code> in query params.</td></tr></tbody></table>

{% hint style="warning" %}
In order to make the experience more personalized, we may add more fields to this response's object in the future. Please develop your integration to be able to ignore new fields considering that it will continue working fine no matter if we add new fields.
{% endhint %}

## 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 [here](/api-documentation/deposits-api/technical-and-security-aspects#headers).
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 [explained here](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature).

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

[Click here](/api-documentation/deposits-api/api-codes#refunds-status-codes) to see each Refund Status meaning.

### Refund Status Flow

&#x20;

![](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/N29KgBGBjWQ7tk9ZVix1/Refund%20Status%20Diagram%20v3.svg)

{% hint style="info" %}

1. DECLINED is not a status by itself. It means the refund failed to be created.
2. As soon as the refund request is created, its status will be PENDING.&#x20;
3. In case we need more information to complete the request or any of the details were incorrect, we will change the status to INCORRECT\_DETAILS and you will need to provide the correct details. Once the details have been provided, its status will be PENDING again.
4. The status CANCELLED means the refund was manually cancelled by you. Only refunds in PENDING or INCORRECT\_DETAILS can be cancelled. Final status.
5. If everything is fine we will send the refund for processing and the status will be marked as DELIVERED. It can't be cancelled at this point.
6. As soon as the processor/bank confirms the refund, it will be marked as COMPLETED or REJECTED (by the bank).
7. There are some **corner cases** in which the receiver's bank tell us that the refund was completed but days after it gets rejected. In those cases the status changes from COMPLETED to REJECTED.
   {% endhint %}

## Status codes

Check all the possible status in the following page:

{% content-ref url="/pages/-M8MAwZ0r4Szs2f\_lbbI" %}
[API Codes](/api-documentation/deposits-api/api-codes)
{% endcontent-ref %}


# Payment Methods

Learn about our Payment Methods

## Payment Methods

{% content-ref url="/pages/-M7EywIJjqpFs68bKk5l" %}
[America](/api-documentation/deposits-api/payment-methods/america)
{% endcontent-ref %}

{% content-ref url="/pages/-M7EzpcNUPkNApVJ8G46" %}
[Broken mention](broken://pages/-M7EzpcNUPkNApVJ8G46)
{% endcontent-ref %}

{% content-ref url="/pages/-M7Ey\_UxoSGYAezpzpst" %}
[Broken mention](broken://pages/-M7Ey_UxoSGYAezpzpst)
{% endcontent-ref %}

&#x20;

{% hint style="info" %}
Check with your commercial representative regarding other countries and payment methods not in these lists.
{% endhint %}

You can retrieve the payment methods your account has enabled by using the [Payment Methods endpoint.](broken://pages/-M7hYgDIPRyR1p3XGmws)

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.&#x20;

<figure><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/AVCxPqhEN4fFgxGDTmTw/image.png" alt=""><figcaption><p>Payment Methods Grid</p></figcaption></figure>

### 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 [OneShot Experience: OneShot](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience-response-oneshot). When creating a payment of this kind, we will return you all the fields you need to display to your customer on a [metadata object](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#response-fields-1) 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.

|    Flow    | Description                                                                                                                                                                                    |
| :--------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ONE_SHOT` | In the `ONE_SHOT` flow, you will receive all the details needed to build a payment page on your own website. For example, the Boleto's number, barcode, expiration, amount, payment link, etc. |
| `REDIRECT` | In the `REDIRECT` flow, we will respond you with a link you should use to redirect your customers so they can pay.                                                                             |

{% hint style="warning" %}
The `ONE_SHOT` and `REDIRECT` flows depends upon provider's availability. In order for us to provide you with the most efficient service, we may switch between service providers who doesn't support `ONE_SHOT`flows, hence your cashier should be able to adapt to both scenarios.
{% endhint %}


# America

Check the list of Payment Methods available on each American country


# Bolivia

Check the list of Payment Methods available on Bolivia

{% hint style="warning" %}
*As of Monday, October 28th, some of our channels for Bolivia are temporarily down, Visa and VPAY QR are working as expected.* \
\
*We will update you with an estimated time for resumption as soon as possible. For further information, please contact your account manager. Thank you for your understanding.*
{% endhint %}

## Payment Methods

|                                                                Icon                                                               | payment\_method | Name       |    Flows   | Payment Type | Available for test | Iframe supported |
| :-------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ---------- | :--------: | :----------: | :----------------: | :--------------: |
|              <img src="https://resources.directa24.com/cashin/payment_method/square/RPD.svg" alt="" data-size="line">             |      `RPD`      | RapidPagos | `REDIRECT` |    VOUCHER   |         Yes        |        Yes       |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/Kvmlc9eBu7APQP09URPt/image.png" alt="" data-size="line"> |      `PFB`      | Pago Facil | `REDIRECT` |    VOUCHER   |         Yes        |        Yes       |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/jMX2reBwoMp53fVyFpjt/image.png" alt="" data-size="line"> |       `VI`      | Visa       | `REDIRECT` | CREDIT\_CARD |         Yes        |        Yes       |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/9koRqWU7Sc1rbCYkBP0C/image.png" alt="" data-size="line"> |       `MC`      | MasterCard | `REDIRECT` | CREDIT\_CARD |         Yes        |        Yes       |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/HNNEK4mV7Izjg1zviOGq/image.png" alt="" data-size="line"> |      `VPQ`      | VPA QR     | `REDIRECT` |    VPAY QR   |         Yes        |        Yes       |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' **types**, **logos** and **more** details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name | address\[] | phone |
| ------------------- | :------: | :---: | :---------: | :--------: | :--------: | :---: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |     No     |   No  |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Brazil

Check the list of Payment Methods available on Brazil

## Payment Methods

|                                                                                                                                                      Icon                                                                                                                                                     | payment\_method | Name            |                           Flows                           |  Payment Type  | Available for test | Iframe supported |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | --------------- | :-------------------------------------------------------: | :------------: | :----------------: | :--------------: |
|                                                     [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/t5w5F84vIhYbYI2TPQNf/BL.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/BL.svg)                                                     |       `BL`      | Boleto          | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                                     [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/uPjYNoiDQe3cJUeJwdOL/IX.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/IX.svg)                                                     |       `IX`      | Pix             | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |        Yes       |
|                                                     [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/F0Er6MugdYeWwBbtHpZ7/PP.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/PP.svg)                                                     |       `PP`      | PicPay          | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |                    |        Yes       |
|                                                     [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/nrZvCDz8mZrR6VLAdQ1W/BB.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/BB.svg)                                                     |       `BB`      | Banco do Brasil | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |        Yes       |
|                                                     [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/B5dSZ8M3y7D8J0s0R1Mz/CA.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/CA.svg)                                                     |       `CA`      | Caixa           | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |  BANK\_DEPOSIT |         Yes        |        Yes       |
|                                                      [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/k2XCfbJr3ltMFcSZntEj/I.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/I.svg)                                                      |       `I`       | Itaú            |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  | BANK\_TRANSFER |         Yes        |        Yes       |
|                                                      [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/A7TZ4SnMuEIfGZ2sESsC/B.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/B.svg)                                                      |       `B`       | Bradesco        | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |        Yes       |
|                                                     [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/04H7Iy7jHUmdfQCJIHGe/SB.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/SB.svg)                                                     |       `SB`      | Santander       | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |  BANK\_DEPOSIT |         Yes        |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/BEOO8A9JoDKacmTVcj2h/BZ.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/BZ.svg) <img src="https://resources.directa24.com/cashin/payment_method/square/BZ.svg" alt="" data-size="line"> |       `BZ`      | Banco Original  | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |  BANK\_DEPOSIT |         Yes        |        Yes       |
|  <img src="https://resources.directa24.com/cashin/payment_method/square/SF.svg" alt="" data-size="line">[<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/xMZcR3s74xenWjWavT4v/SF.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/SF.svg) |       `SF`      | Banco Safra     | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |  BANK\_DEPOSIT |         Yes        |        Yes       |
|                                                     [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/0QzHvg0Ghlrtc2VcLV6h/UL.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/UL.svg)                                                     |       `UL`      | Banrisul        | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |  BANK\_DEPOSIT |         Yes        |        Yes       |
|                                                                                                    <img src="https://resources.directa24.com/cashin/payment_method/square/VI.svg" alt="" data-size="line">                                                                                                    |       `VI`      | Visa            |      <p><code>REDIRECT</code><br><code>PCI</code></p>     |  CREDIT\_CARD  |         Yes        |        Yes       |
|                                                                                                    <img src="https://resources.directa24.com/cashin/payment_method/square/MC.svg" alt="" data-size="line">                                                                                                    |       `MC`      | Mastercard      |      <p><code>REDIRECT</code><br><code>PCI</code></p>     |  CREDIT\_CARD  |         Yes        |        Yes       |
|                                                                                                    <img src="https://resources.directa24.com/cashin/payment_method/square/EL.svg" alt="" data-size="line">                                                                                                    |       `EL`      | Elo             |      <p><code>REDIRECT</code><br><code>PCI</code></p>     |  CREDIT\_CARD  |         Yes        |        Yes       |
|                                                                                       <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/Zv3Rck5TrcMzIo7dtXN2/image.png" alt="" data-size="line">                                                                                       |       `NU`      | Nubank          |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  | BANK\_TRANSFER |         Yes        |        Yes       |
|                                                                                       <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/S9Ehug90LSQoKW2JwiMH/image.png" alt="" data-size="line">                                                                                       |       `ME`      | MercadoPago     |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  | BANK\_TRANSFER |         Yes        |        Yes       |
|                                                                                       <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/7Asjm39Xu48velddRtkq/image.png" alt="" data-size="line">                                                                                       |      `ICSH`     | iCash           |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |     VOUCHER    |         Yes        |        Yes       |
|                                                                                       <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/waQJd666BToFmASeHRoV/image.png" alt="" data-size="line">                                                                                       |       SUA       | SUAPI           |                         `REDIRECT`                        |     WALLET     |         Yes        |        Yes       |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' **types**, **logos** and **more** details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name | address\[] | phone |
| ------------------- | :------: | :---: | :---------: | :--------: | :--------: | :---: |
| Boleto              |    Yes   |  Yes  |     Yes     |     Yes    |     Yes    |   No  |
| Banco do Brasil     |    Yes   |  Yes  |     Yes     |     Yes    |     Yes    |   No  |
| Itaú                |    Yes   |  Yes  |     Yes     |     Yes    |     Yes    |   No  |
| PicPay              |    Yes   |  Yes  |     Yes     |     Yes    |     No     |  Yes  |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |     No     |   No  |

###

### Address object requirements

<table><thead><tr><th>Payment Method Name</th><th width="150">Required for deposits above</th><th width="150" align="center">street</th><th width="150" align="center">city</th><th width="150" align="center">state</th><th align="center">zip_code</th></tr></thead><tbody><tr><td>Boleto</td><td>USD 3000</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td>Banco do Brasil</td><td>USD 200</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td>Itaú</td><td>USD 200</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Chile

Check the list of Payment Methods available on Chile

## Payment Methods

|                                                                                                    Icon                                                                                                    | payment\_method | Name             |                          Flow                          |  Payment Type | Available for test | Iframe supported |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ---------------- | :----------------------------------------------------: | :-----------: | :----------------: | :--------------: |
|    [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/C4d24G8FJzQ9RC9MaCWI/WP.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/WP.svg)   |       `WP`      | WebPay           |                       `REDIRECT`                       |  CREDIT\_CARD |                    |        No        |
|                                                   <img src="https://resources.directa24.com/cashin/payment_method/square/VI.svg" alt="" data-size="line">                                                  |       `VI`      | VISA             |    <p><code>REDIRECT</code><br><code>PCI</code></p>    |  CREDIT\_CARD |                    |        Yes       |
|                                                   <img src="https://resources.directa24.com/cashin/payment_method/square/MC.svg" alt="" data-size="line">                                                  |       `MC`      | Mastercard       |    <p><code>REDIRECT</code><br><code>PCI</code></p>    |  CREDIT\_CARD |                    |        Yes       |
|    [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/Sl0mfcAxqvVJUwBtu7TO/BE.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/BE.svg)   |       `BE`      | Banco Estado     |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        Yes       |
|    [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/vGCTZYLs2fFfODMmlG69/BX.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/BX.svg)   |       `BX`      | Banco de Chile   |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        Yes       |
|    [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/cwbleIIkHG0dgt7XOck7/CI.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/CI.svg)   |       `CI`      | Banco BCI        |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/9tvsRDSJlVozi0B8dqK4/favicon.ico" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/LE.svg) |       `LE`      | Banco CrediChile |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        Yes       |
|    [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/meuk43EfYqaMh3hpiG7H/LL.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/LL.svg)   |       `LL`      | Banco Falabella  |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        Yes       |
|    [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/sjbNtrsSikAvTqFVgSgf/KV.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/KV.svg)   |       `KV`      | Caja Vecina      | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |                    |        Yes       |
|    [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/a3PtR5f80jt5z3cJJDoT/XL.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/XL.svg)   |       `XL`      | Express Lider    |                       `REDIRECT`                       |    VOUCHER    |                    |        Yes       |
|    [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/765jH7TOnZaNXdPwr5py/SL.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/SL.svg)   |        SL       | Sencillito       | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |                    |        Yes       |
|    [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/h93DAd2OrmfGSInI51Pg/IA.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/IA.svg)   |       `IA`      | Itaú             |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        Yes       |
|    [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/YPsL3J0E2jppDtaJsOcR/SC.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/SC.svg)   |       `SC`      | Banco Santander  |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        Yes       |
|                                      <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/n8mFJjXX0Y1eyeLmwLaE/image.png" alt="" data-size="line">                                     |       `ST`      | Scotiabank       |                     `BANK_DEPOSIT`                     | BANK\_DEPOSIT |                    |        Yes       |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Canada

Check the list of Payment Methods available on Canada

{% hint style="warning" %}
Please be aware that our service is currently unavailable in this Country. We are working to restore service as quickly as possible. Thank you for your patience.
{% endhint %}

## Payment Methods

|                                                                                                  Icon                                                                                                 | payment\_method | Name              |    Flow    |  Payment Type  | Available for test | Iframe supported |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ----------------- | :--------: | :------------: | :----------------: | :--------------: |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/4DC8ogLqThj0wuGvPmIN/IF.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/IF.svg) |       `IF`      | Interac Etransfer | `REDIRECT` |     VOUCHER    |                    |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/upzQQrW4BZISXKqD1S5h/IR.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/IR.svg) |       `IR`      | Interac Online    | `REDIRECT` | BANK\_TRANSFER |                    |        Yes       |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Colombia

Check the list of Payment Methods available on Colombia

## Payment Methods

<table><thead><tr><th width="219" align="center">Icon</th><th align="center">payment_method</th><th width="150">Name</th><th width="147" align="center">Flow</th><th width="166" align="center">Payment Type</th><th align="center">Available for test</th><th align="center">Iframe supported</th></tr></thead><tbody><tr><td align="center"><img src="https://resources.directa24.com/cashin/payment_method/square/ME.svg" alt="" data-size="line"></td><td align="center"><code>ME</code></td><td>MercadoPago</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/VI.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/VI.svg" alt="" data-size="line"></a></td><td align="center"><code>VI</code></td><td>VISA</td><td align="center"><code>REDIRECT</code><br><code>PCI</code></td><td align="center">CREDIT_CARD</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/MC.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/MC.svg" alt="" data-size="line"></a></td><td align="center"><code>MC</code></td><td>MasterCard</td><td align="center"><code>REDIRECT</code><br><code>PCI</code></td><td align="center">CREDIT_CARD</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/AE.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/AE.svg" alt="" data-size="line"></a></td><td align="center"><code>AE</code></td><td>American Express</td><td align="center"><code>REDIRECT</code><br><code>PCI</code></td><td align="center">CREDIT_CARD</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/EY.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/EY.svg" alt="" data-size="line"></a></td><td align="center"><code>EY</code></td><td>Efecty</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">No</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/PD.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/PD.svg" alt="" data-size="line"></a></td><td align="center"><code>PD</code></td><td>Punto Red</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">No</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/PC.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/PC.svg" alt="" data-size="line"></a></td><td align="center"><code>PC</code></td><td>PSE</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">BANK_DEPOSIT</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/jxAaQDMPTdpJ32y7YFK7/image.png" alt="" data-size="line"></td><td align="center"><code>NQ</code></td><td>Nequi</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">BANK_DEPOSIT</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/EX.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/EX.svg" alt="" data-size="line"></a></td><td align="center"><code>EX</code></td><td>Almacenes Exito</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/CR.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/CR.svg" alt="" data-size="line"></a></td><td align="center"><code>CR</code></td><td>Carulla</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/SX.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/SX.svg" alt="" data-size="line"></a></td><td align="center"><code>SX</code></td><td>Surtimax</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/JE.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/JE.svg" alt="" data-size="line"></a></td><td align="center"><code>JE</code></td><td>JER</td><td align="center"><code>REDIRECT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/CX.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/CX.svg" alt="" data-size="line"></a></td><td align="center"><code>CX</code></td><td>Su Chance</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/XU.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/XU.svg" alt="" data-size="line"></a></td><td align="center"><code>XU</code></td><td>Con Suerte</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/XI.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/XI.svg" alt="" data-size="line"></a></td><td align="center"><code>XI</code></td><td>Superinter</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/XC.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/XC.svg" alt="" data-size="line"></a></td><td align="center"><code>XC</code></td><td>Coopenessa</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/DQ.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/DQ.svg" alt="" data-size="line"></a></td><td align="center"><code>DQ</code></td><td>Edeq</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/DX.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/DX.svg" alt="" data-size="line"></a></td><td align="center"><code>DX</code></td><td>Dimonex</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/FG.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/FG.svg" alt="" data-size="line"></a></td><td align="center"><code>FG</code></td><td>FullCarga</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/MR.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/MR.svg" alt="" data-size="line"></a></td><td align="center"><code>MR</code></td><td>Moviired</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><img src="https://resources.directa24.com/cashin/payment_method/square/SR.svg" alt="" data-size="line"></td><td align="center"><code>SR</code></td><td>Su Suerte</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><img src="https://resources.directa24.com/cashin/payment_method/square/SZ.svg" alt="" data-size="line"></td><td align="center"><code>SZ</code></td><td>Surti Mayorista</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><img src="https://resources.directa24.com/cashin/payment_method/square/RD.svg" alt="" data-size="line"></td><td align="center"><code>RD</code></td><td>Su Red</td><td align="center"><code>REDIRECT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/WR0NknGSqrnb8k7U85mH/TRYA.svg" alt="" data-size="line"></td><td align="center"><code>TRYA</code></td><td>TransFiYa</td><td align="center"><code>REDIRECT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td><td align="center">Yes</td></tr><tr><td align="center"><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/0MzYWW1WzKcxz2Nokwwm/image.png" alt="" data-size="line"></td><td align="center"><code>TP</code></td><td>TPAGA</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name | address\[] | phone |
| ------------------- | :------: | :---: | :---------: | :--------: | :--------: | :---: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |     No     |   No  |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}

### Pagos Seguros en Linea (PSE) One shot flow

The PSE direct One shot flow send the customer directly to the checkout page, instead of redirecting to an intermediate page to choose the bank.\
\
It is necessary to add the `sub_payment_method` field to the deposit request to use this flow.  \
Below it's presented the list of banks accepted:\ <br>

| Bank name                               | Sub\_payment\_method |
| --------------------------------------- | -------------------- |
| Rappipay                                | `RPP`                |
| Bancamia                                | `BMI`                |
| Banco de Bogotá                         | `BDB`                |
| Banco Popular                           | `BPC`                |
| Banco GNB Sudameris                     | `GNB`                |
| Banco Caja Social                       | `BCJ`                |
| Banco Agrario                           | `AGR`                |
| Banco Davivienda                        | `BDA`                |
| Bancolombia                             | `BN`                 |
| Banco AV Villas                         | `BAV`                |
| Bancoomeva                              | `BCM`                |
| Banco Finandina                         | `BFB`                |
| Banco Cooperativo Coopcentral           | `BCC`                |
| Banco Santander Colombia                | `SC`                 |
| Banco Serfinanza                        | `BSF`                |
| BBVA Colombia                           | `AV`                 |
| Lulo Bank                               | `BLU`                |
| Dale                                    | `DAL`                |
| CFA Cooperativa Financiera              | `CFA`                |
| Citibank                                | `CK`                 |
| Cotrafa                                 | `COT`                |
| Coofinep Cooperativa Financiera         | `CCF`                |
| Confiar Cooperativa Financiera          | `CON`                |
| Banco Union antes giros                 | `BUG`                |
| Coltefinanciera                         | `COL`                |
| Daviplata                               | `DVP`                |
| Falabella                               | `LL`                 |
| BAN100 (formerly Banco Credifinanciera) | `BCR`                |
| Itau                                    | `I`                  |
| Iris                                    | `IRS`                |
| Movii S.A.                              | `MR`                 |
| Nequi                                   | `NQ`                 |
| Banco de occidente                      | `OC`                 |
| Pichincha                               | `IX`                 |
| Scotiabank Colpatria                    | `ST`                 |


# Costa Rica

Check the list of Payment Methods available on Costa Rica

{% hint style="warning" %}
*PayPal is currently down due to operational issues. We’re working to resolve this and appreciate your patience.*
{% endhint %}

## Payment Methods

|                                                                Icon                                                               | payment\_method | Name           |                          Flow                          |  Payment Type | Available for test | Supports iFrame |
| :-------------------------------------------------------------------------------------------------------------------------------: | :-------------: | -------------- | :----------------------------------------------------: | :-----------: | :----------------: | :-------------: |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/46uGVKDKaG5Xfui7uHhg/image.png" alt="" data-size="line"> |      `PPL`      | PayPal         | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |         Yes        |       Yes       |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/52OGahuLXeFkx5XqW4NT/image.png" alt="" data-size="line"> |      `PTH`      | Punto Hey      |                       `REDIRECT`                       |    VOUCHER    |         Yes        |       Yes       |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/RefR7g0xCCxaEPN1sSoL/image.png" alt="" data-size="line"> |      `BNA`      | Banco Nacional |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |       Yes       |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Ecuador

Check the list of Payment Methods available on Ecuador

{% hint style="warning" %}
*Beginning September 20th, 2024, all credit card payments will require 3DS (Three-Domain Secure) verification. This new measure is mandatory and designed to enhance the security of your transactions. You can learn more about Deposits with 3DS Authentication* [*here*](broken://pages/KDBOXgI3jFiNJwvvbPPF)*.* \
\
*We appreciate your understanding and cooperation.*
{% endhint %}

## Payment Methods

|                                                                                                  Icon                                                                                                 | payment\_method | Name                |                          Flow                          |  Payment Type | Available for test | Iframe supported |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ------------------- | :----------------------------------------------------: | :-----------: | :----------------: | :--------------: |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/WYPmdNNwzj41n1itj04m/FO.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/FO.svg) |       `FO`      | Facilito            | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |         Yes        |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/G8O6OnPca6RZLvjx0isL/GB.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/GB.svg) |       `GB`      | Banco Guayaquil     |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/DVk04Wy8i8Gx9LEYaI1U/PX.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/PX.svg) |       `PX`      | Banco Pichincha     |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        No        |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/CM2iPkg1gPxc3j0lfH4s/MV.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/MV.svg) |       `MV`      | Pichincha MiVecino  |                       `REDIRECT`                       |    VOUCHER    |         Yes        |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/bONHb0lZA4BFcVAdTdrf/PJ.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/PJ.svg) |       `PJ`      | Pago Ágil           | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |         Yes        |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/Wu9FTQbz0TIFNt22rA2J/ES.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/ES.svg) |       `ES`      | ServiPagos          | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |         Yes        |        Yes       |
|                                                <img src="https://resources.directa24.com/cashin/payment_method/square/BR.svg" alt="" data-size="line">                                                |       `BR`      | Banco Del Barrio    | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |         Yes        |        Yes       |
|                                   <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/FaII76E9pvtxtds4Yr4N/image.png" alt="" data-size="line">                                   |      `BBO`      | Banco Bolivariano   |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/0wpdPuaVio4oNfeHEesK/TE.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/TE.svg) |       `TE`      | Tia                 | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |         Yes        |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/NTpSRGW8IObDmBQSOQAw/AW.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/AW.svg) |       `AW`      | Activa WesternUnion | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |         Yes        |        Yes       |
|                                                <img src="https://resources.directa24.com/cashin/payment_method/square/IE.svg" alt="" data-size="line">                                                |       `IE`      | Banco Internacional |                       `REDIRECT`                       | BANK\_DEPOSIT |         Yes        |        Yes       |
|                                                <img src="https://resources.directa24.com/cashin/payment_method/square/WU.svg" alt="" data-size="line">                                                |       `WU`      | Western Union       | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |         Yes        |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/4hCLd92DakDUH5iID2IS/FD.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/FD.svg) |       `FD`      | Farmacias911        | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |    VOUCHER    |         Yes        |        Yes       |
|                                   <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/XmDUnA9dmVFwmfeOFrds/image.png" alt="" data-size="line">                                   |      `PPH`      | Payphone            | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> |     WALLET    |         Yes        |        Yes       |
|                                   <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/NmtFi6axgtrvH4OJZwpa/image.png" alt="" data-size="line">                                   |       `DU`      | De Una!             |                       `REDIRECT`                       |    VOUCHER    |         Yes        |        Yes       |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Honduras

Check the list of Payment Methods available on Honduras

{% hint style="warning" %}
*At the moment, the payment methods listed for Honduras are only available for certain industries. Please contact your Account Manager to learn more about eligibility and available options for your business.*\
\
*Additionally, please note that PayPal is currently down due to operational issues. We’re working to resolve this and appreciate your patience.*
{% endhint %}

## Payment Methods

<table><thead><tr><th>Icon</th><th width="171">payment_method</th><th>Name</th><th width="142">Flow</th><th width="146">payment_type</th><th width="180">Available for test</th><th>iFrame supported</th></tr></thead><tbody><tr><td><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/WxoG3azanToi51rUGLq6/image.png" alt="" data-size="line"></td><td><code>PPL</code></td><td>PayPal</td><td><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td>VOUCHER</td><td>Yes</td><td>Yes</td></tr><tr><td><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/u40muOmdmyDnx9X36twC/image.png" alt="" data-size="original"></td><td><code>TMO</code></td><td>Tigo Money</td><td><code>REDIRECT</code></td><td>WALLET</td><td>Yes</td><td>Yes</td></tr><tr><td><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/pHp1axT738RboyIttndo/image.png" alt="" data-size="original"></td><td><code>FIC</code></td><td>Ficohsa</td><td><code>REDIRECT</code></td><td>VOUCHER</td><td>Yes</td><td>Yes</td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the OneShot Experience

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Mexico

Check the list of Payment Methods available on Mexico

{% hint style="warning" %}
*PayPal is currently down due to operational issues. We’re working to resolve this and appreciate your patience.*
{% endhint %}

## Payment Methods

|                                                                                      Icon                                                                                      | payment\_method | Name                   |                            Flow                           |  Payment Type  | Available for test | Iframe supported |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ---------------------- | :-------------------------------------------------------: | :------------: | :----------------: | :--------------: |
|                                     <img src="https://resources.directa24.com/cashin/payment_method/square/ME.svg" alt="" data-size="line">                                    |       `ME`      | MercadoPago            |                         `REDIRECT`                        |     WALLET     |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/SE.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/SE.svg) |       `SE`      | Spei                   | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/VI.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/VI.svg) |       `VI`      | Visa                   |      <p><code>REDIRECT</code><br><code>PCI</code></p>     |  CREDIT\_CARD  |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/MC.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/MC.svg) |       `MC`      | MasterCard             |      <p><code>REDIRECT</code><br><code>PCI</code></p>     |  CREDIT\_CARD  |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/AE.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/AE.svg) |       `AE`      | American Express       |      <p><code>REDIRECT</code><br><code>PCI</code></p>     |  CREDIT\_CARD  |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/OX.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/OX.svg) |       `OX`      | OXXO                   | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                    <img src="https://resources.directa24.com/cashin/payment_method/square/COD.svg" alt="" data-size="line">                                    |      `COD`      | CoDi                   | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/AZ.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/AZ.svg) |       `AZ`      | Banco Azteca           | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/BV.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/BV.svg) |       `BV`      | BBVA Bancomer          | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                    <img src="https://resources.directa24.com/cashin/payment_method/square/BVL.svg" alt="" data-size="line">                                    |      `BVL`      | BBVA Bancomer Online   | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |        Yes       |
|                        <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/HqsIqdRDMSFDDWZrvI0S/image.png" alt="" data-size="line">                       |       `BM`      | Banamex                | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |                  |
|                                    <img src="https://resources.directa24.com/cashin/payment_method/square/STS.svg" alt="" data-size="line">                                    |      `STS`      | Santander SuperNet     |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  | BANK\_TRANSFER |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/SM.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/SM.svg) |       `SM`      | Santander              |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |  BANK\_DEPOSIT |         Yes        |        Yes       |
|                                     <img src="https://resources.directa24.com/cashin/payment_method/square/AF.svg" alt="" data-size="line">                                    |       `AF`      | Afirme online banking  | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |        Yes       |
|                        <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/gFqwebXTuCciUrGUIqUn/image.png" alt="" data-size="line">                       |       `TC`      | Todito                 |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |     WALLET     |         Yes        |                  |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/PN.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/PN.svg) |       `PN`      | PayNet                 | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                     <img src="https://resources.directa24.com/cashin/payment_method/square/FA.svg" alt="" data-size="line">                                    |       `FA`      | Farmacia del Ahorro    | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                     <img src="https://resources.directa24.com/cashin/payment_method/square/EA.svg" alt="" data-size="line">                                    |       `EA`      | Extra                  |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |     VOUCHER    |         Yes        |        Yes       |
|                                    <img src="https://resources.directa24.com/cashin/payment_method/square/CLX.svg" alt="" data-size="line">                                    |      `CLX`      | Calimax                |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |     VOUCHER    |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/BW.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/BW.svg) |       `BW`      | Bodega Aurrera         | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/CU.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/CU.svg) |       `CU`      | Circulo K              | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/EN.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/EN.svg) |       `EN`      | 7 Eleven               | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                     <img src="https://resources.directa24.com/cashin/payment_method/square/FL.svg" alt="" data-size="line">                                    |       `FL`      | Farmacia la mas barata | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                     <img src="https://resources.directa24.com/cashin/payment_method/square/RO.svg" alt="" data-size="line">                                    |       `RO`      | Roma                   | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                     <img src="https://resources.directa24.com/cashin/payment_method/square/SQ.svg" alt="" data-size="line">                                    |       `SQ`      | Soriana                | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                     <img src="https://resources.directa24.com/cashin/payment_method/square/WE.svg" alt="" data-size="line">                                    |       `WE`      | Walmart Express        | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
| [<img src="https://resources.directa24.com/cashin/payment_method/square/WA.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/WA.svg) |       `WA`      | Walmart                | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                    <img src="https://resources.directa24.com/cashin/payment_method/square/BAZ.svg" alt="" data-size="line">                                    |      `BAZ`      | BAZ SuperApp           | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                                    <img src="https://resources.directa24.com/cashin/payment_method/square/BQL.svg" alt="" data-size="line">                                    |      `BQL`      | Banorte online banking | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |        Yes       |
|                       <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/Osl5dgyfnuAv48hQd5PY/Paypal.svg" alt="" data-size="line">                       |      `PPL`      | PayPal                 |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |     VOUCHER    |         Yes        |        Yes       |
|                        <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/3Z7VtCkHoaIXEU16Ez7m/image.png" alt="" data-size="line">                       |      `OXP`      | OXXOPay                |                         `REDIRECT`                        |     VOUCHER    |         Yes        |        Yes       |
|                        <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/tYH7XKHpwGCDZK6kpT2R/image.png" alt="" data-size="line">                       |       `SW`      | SuperCity              | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |
|                        <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/RTUMIOYq3E41w1A6SF6L/image.png" alt="" data-size="line">                       |       `SS`      | Sams Club              | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> |     VOUCHER    |         Yes        |        Yes       |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}

## SPEI Offline

The SPEI offline feature will allow customers in Mexico to create deposits without having to go through the regular SPEI flow - going straight to make the payment, skipping the checkout part.

In these cases, the user transfers money to their previously used unique CLABE account, and we instantly get notified of this deposit made.&#x20;

Upon receiving a notification regarding a new transfer that was not recorded in our system, we will take it into account and create the appropriate record based on various factors, to decide if this payment is accepted or not.\
\
**To activate this functionality, please get in contact with your responsible Account Manager, or Technical Account Manager.**\
\
**It is also mandatory to provide us with a URL for a POST request, with the following body:**

```
{
  "deposit_id": 123456789,
  "payer_account_number": "123456789123456789",
  "country": "MX",
  "document": "84932568207",
  "full_name": "John Doe",
  "date_of_birth": "19871027",
  "address": "Ruta 13, Mexico",
  "email": "jon.doe@example.com",
  "amount": 200,
  "currency": "MXN",
  "payment_method": "SEOF"
}
```

**Field Descriptions**

<table><thead><tr><th width="236">Field</th><th>Description</th></tr></thead><tbody><tr><td>deposit_id</td><td>Unique identifier linked to the payment deposit.</td></tr><tr><td>payer_account_number</td><td>CLABE of the customer that has made the payment.</td></tr><tr><td>country</td><td>"MX" - indicating Mexico</td></tr><tr><td>document</td><td>Identification document assigned to the payer initiating the payment</td></tr><tr><td>full_name</td><td>Full name of the payer that has initiated the payment.</td></tr><tr><td>date_of_birth</td><td>Date of birth of the payer - Year/Month/Day</td></tr><tr><td>address</td><td>Address of the payer</td></tr><tr><td>email</td><td>Email of the payer</td></tr><tr><td>amount</td><td>Amount of the transaction created</td></tr><tr><td>currency</td><td>Currency of the payment - "MXN"</td></tr><tr><td>payment_method</td><td>Payment method - "SEOF" - Indicating SPEI offline</td></tr></tbody></table>

This JSON structure includes all the information required so we can enable this feature for your account.

The URL provided from your side should return either a 200 HTTP Status, in case the deposit wants to be approved, or a 400 status, which will indicate the rejection of a deposit. Any other status is considered as rejected payments.

**Response**\
\
Furthermore, you will have the option to return a response with the following fields on the body:

```
{
   "invoice_id" : "XXXXXX",
   "notification_url" : "https://url-example/ipn/deposit/XXXXXX
}
```

Since SPEI offline payments are not created via the API first, we generate a random "invoice\_id" and use your default notification URL for the deposits (Found under settings --> API Access)\
\
If this information is returned from your side, we will use the values provided by you instead.


# Panama

Check the list of Payment Methods available on Panama

## Payment Methods

<br>

| Icon                                                                                                                                  | payment\_method | Name       | Flow     | Payment Type | Available for Test | Iframe supported |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ---------- | -------- | ------------ | ------------------ | ---------------- |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/iaIYvRGgzg2s50lnLTPh/image.png" alt="" data-size="original"> | PTP             | Punto Pago | REDIRECT | VOUCHER      | Yes                | Yes              |
|                                                                                                                                       |                 |            |          |              |                    |                  |
|                                                                                                                                       |                 |            |          |              |                    |                  |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Paraguay

Check the list of Payment Methods available on Paraguay

## Payment Methods

|                                                                Icon                                                               | payment\_method | Name          |                          Flow                          |  Payment Type  | Available for test | Iframe supported |
| :-------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ------------- | :----------------------------------------------------: | :------------: | :----------------: | :--------------: |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/4NxwccRMhIh4NHW3YJVi/image.png" alt="" data-size="line"> |       `TR`      | Bank Transfer | <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p> | BANK\_TRANSFER |         Yes        |        Yes       |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos, and more details.
{% endhint %}

## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Peru

Check the list of Payment Methods available on Perú

## Methods

{% hint style="info" %}
Tupay payment methods include different solutions within them, all in the same place. For more details, you can [click here](#tupay-methods-description).
{% endhint %}

|                                                                                                   Icon                                                                                                   | payment\_method | Name                  |                            Flow                           |  Payment Type | Available for test | Iframe supported |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | --------------------- | :-------------------------------------------------------: | :-----------: | :----------------: | :--------------: |
|                                                  <img src="https://resources.directa24.com/cashin/payment_method/square/XA.svg" alt="" data-size="line">                                                 |       `XA`      | Tupay                 |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |      N/A      |         Yes        |        Yes       |
|                                     <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/gC6NIxvHGwCiF8IGMSXL/image.png" alt="" data-size="line">                                    |      `XAQR`     | Tupay QR              |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |      N/A      |         Yes        |        Yes       |
|                                     <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/1xtKu4pmWDzsuZAv74fp/image.png" alt="" data-size="line">                                    |      `XABT`     | Tupay Bank Transfers  |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |      N/A      |         Yes        |        Yes       |
|                                     <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/TpYQjhP1oPiYFXgbe3Vt/image.png" alt="" data-size="line">                                    |      `XACC`     | Credit Cards by Tupay |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |    VOUCHER    |         Yes        |        Yes       |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/EF.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/EF.svg)              |       `EF`      | Pago Efectivo         |                         `REDIRECT`                        |    VOUCHER    |         Yes        |        No        |
|   [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/SS3cfJpngRIQKhvRwq2N/VI.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/VI.svg)  |       `VI`      | Visa                  |      <p><code>REDIRECT</code><br><code>PCI</code></p>     |  CREDIT\_CARD |         Yes        |        Yes       |
|   [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/bOf3Ya79wRIF89Tm5Dv2/MC.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/MC.svg)  |       `MC`      | Mastercard            |      <p><code>REDIRECT</code><br><code>PCI</code></p>     |  CREDIT\_CARD |         Yes        |        Yes       |
| [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/7UGLn4xK1AZ1HrYddge6/image.png" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/YP.svg) |       `YP`      | Yape                  |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |     WALLET    |         Yes        |        Yes       |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/IB.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/IB.svg)              |       `IB`      | Interbank             |                         `REDIRECT`                        | BANK\_DEPOSIT |         Yes        |        No        |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/BC.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/BC.svg)              |       `BC`      | BCP                   | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_DEPOSIT |         Yes        |        Yes       |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/ST.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/ST.svg)              |       `ST`      | Scotia                |                         `REDIRECT`                        | BANK\_DEPOSIT |         Yes        |        No        |
|                                                 <img src="https://resources.directa24.com/cashin/payment_method/square/BAB.svg" alt="" data-size="line">                                                 |      `BAB`      | Banbif                | <p><code>REDIRECT</code></p><p><code>ONE\_SHOT</code></p> | BANK\_DEPOSIT |         Yes        |        Yes       |
|                                                  <img src="https://resources.directa24.com/cashin/payment_method/square/RY.svg" alt="" data-size="line">                                                 |       `RY`      | Banco Ripley          |                         `REDIRECT`                        | BANK\_DEPOSIT |         Yes        |        Yes       |
|                                                  <img src="https://resources.directa24.com/cashin/payment_method/square/ME.svg" alt="" data-size="line">                                                 |       `ME`      | Mercadopago           |                         `REDIRECT`                        |     WALLET    |         Yes        |        Yes       |
|                                                 <img src="https://resources.directa24.com/cashin/payment_method/square/NAG.svg" alt="" data-size="line">                                                 |      `NAG`      | Niubiz Agents Payment |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |    VOUCHER    |         Yes        |        Yes       |
|                                                 <img src="https://resources.directa24.com/cashin/payment_method/square/RDP.svg" alt="" data-size="line">                                                 |      `RDP`      | Red Digital           |                         `REDIRECT`                        |    VOUCHER    |         Yes        |        Yes       |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/WU.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/WU.svg)              |       `WU`      | Western Union         |                         `REDIRECT`                        |    VOUCHER    |         Yes        |        No        |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/BP.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/BP.svg)              |       `BP`      | BBVA                  |                         `REDIRECT`                        | BANK\_DEPOSIT |         Yes        |        No        |
|   [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/MUhfOEUrqB2sh958OO0o/KE.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/KE.svg)  |       `KE`      | Kasnet                |   <p><code>REDIRECT</code><br><code>ONE\_SHOT</code></p>  |    VOUCHER    |         Yes        |        Yes       |
|   [<img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/aOOmhPMte3KgmiS9umQw/TM.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/TM.svg)  |       `TM`      | Tambo                 |                         `REDIRECT`                        |    VOUCHER    |         Yes        |        Yes       |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/HC.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/HC.svg)              |       `HC`      | Caja Huancayo         |                         `REDIRECT`                        |    VOUCHER    |         Yes        |        No        |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/US.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/US.svg)              |       `US`      | Caja Cusco            |                         `REDIRECT`                        |    VOUCHER    |         Yes        |        No        |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/JA.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/JA.svg)              |       `JA`      | Caja Arequipa         |                         `REDIRECT`                        |    VOUCHER    |         Yes        |        No        |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/JI.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/JI.svg)              |       `JI`      | Caja ICA              |                         `REDIRECT`                        |    VOUCHER    |         Yes        |        No        |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/JP.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/JP.svg)              |       `JP`      | Caja Piura            |                         `REDIRECT`                        |    VOUCHER    |         Yes        |        No        |
|              [<img src="https://resources.directa24.com/cashin/payment_method/square/JT.svg" alt="" data-size="line">](https://resources.directa24.com/cashin/payment_method/square/JT.svg)              |       `JT`      | Caja Tacna            |                         `REDIRECT`                        |    VOUCHER    |         Yes        |        No        |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}

### Tupay methods description

With the Tupay payment methods, you can offer a wide array of solutions by utilizing only 1 checkout, different payment methods include:\
\
**Tupay (XA)**\
\
The payment method Tupay, includes all the payment methods available via this channel, including digital wallets, bank transfers, credit cards, and cash methods.\
\
The customer can choose whatever method they want to complete the transaction.\
\
**Tupay QR (XAQR)**\
\
This payment method includes both Yape and Plin, which are the most used digital wallets in Peru, together with other smaller digital wallets. The QR code within can be used to pay with any of these digital wallets.\
\
**Tupay Bank Transfers (XABT)**\
\
Tupay Bank Transfers lets the final customer utilize whatever bank that they have, in order to make a bank transfer as a payment.\
\
**Tupay Credit Cards (XACC)**\
\
This allows customers to pay with a credit card, Visa or MasterCard. Also, it can include debit cards.


# Nicaragua

Check the list of Payment Methods available on Nicaragua

{% hint style="warning" %}
*PayPal is currently down due to operational issues. We’re working to resolve this and appreciate your patience.*
{% endhint %}

## Payment Methods

| Icon                                                                                                                              | Payment Method | Name   | Flow                | Available for testing | Supports iFrame |
| --------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------ | ------------------- | --------------------- | --------------- |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/Z1zt6jZH60fmtLuksGdN/image.png" alt="" data-size="line"> | `PPL`          | PayPal | `REDIRECT ONE_SHOT` | Yes                   | Yes             |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# El Salvador

Check the list of Payment Methods available on El Salvador

{% hint style="warning" %}
*PayPal is currently down due to operational issues. We’re working to resolve this and appreciate your patience.*
{% endhint %}

## Payment Methods

| Icon                                                                                                                              | Payment Method | Name   | Flow                | Available for testing | Supports iFrame |
| --------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------ | ------------------- | --------------------- | --------------- |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/Z1zt6jZH60fmtLuksGdN/image.png" alt="" data-size="line"> | `PPL`          | PayPal | `REDIRECT ONE_SHOT` | Yes                   | Yes             |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Dominican Republic

Check the list of Payment Methods available on Dominican Republic

<br>

### Payment Methods <a href="#payment-methods" id="payment-methods"></a>

| Icon                                                                                                                                  | payment\_method | Name          | Flow     | Payment Type  | Available for test | Iframe supported |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------- | -------- | ------------- | ------------------ | ---------------- |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/1J8leT57IxYa0BNh1SbK/image.png" alt="" data-size="original"> | BPRD            | Banco Popular | REDIRECT | BANK\_DEPOSIT | Yes                | Yes              |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Guatemala

Check the list of Payment Methods available on Guatemala

## Payment Methods

| Icon                                                                                                                                  | payment\_method | Name                | Flow     | Payment Type  | Available for test | Iframe supported |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------- | -------- | ------------- | ------------------ | ---------------- |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/GlwIrwKXTWoDCFA620hO/image.png" alt="" data-size="original"> | BAM             | Banco Agromercantil | REDIRECT | BANK\_DEPOSIT | Yes                | Yes              |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/tOOR1uyGyBXg4yOGf9qo/image.png" alt="" data-size="original"> | BIND            | Banco Industrial    | REDIRECT | BANK\_DEPOSIT | Yes                | Yes              |

{% hint style="success" %}
Use the [Payment Methods Endpoint](broken://pages/-M7hYgDIPRyR1p3XGmws) to retrieve the Payment Methods' types, logos and more details.
{% endhint %}

### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | :-----: | :----: | :------: | :-------------: |
| All                 |   Yes   |   Yes  |    Yes   |       Yes       |

###

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | :------: | :---: | :---------: | :--------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |

{% hint style="success" %}
Other fields not in these lists are optional.
{% endhint %}


# Argentina

Check the list of Payment Methods available on Argentina

### Payment Methods

<table><thead><tr><th width="68.90625">Logo</th><th>Payment Method</th><th>Name</th><th>Flow</th><th>Payment Type</th><th width="161.4375">Available for test</th></tr></thead><tbody><tr><td><img src="https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2F7o8k0tRFNRqZ8HV7Pyup%2FChatGPT%20Image%2018%20feb%202026%2C%2006_06_50%20p.m..png?alt=media&amp;token=55e922b2-07ed-4994-95a7-73d40e0de665" alt=""></td><td><code>MBT</code></td><td>Modo BT</td><td>REDIRECT</td><td>BANK_DEPOSIT</td><td>No</td></tr><tr><td><img src="https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2FT5H0191jDRSxnkehwqPJ%2FMODO.svg?alt=media&amp;token=046e8d10-fab8-4ba2-8a00-c3df69d0c9d1" alt=""></td><td><code>MODO</code></td><td>Modo</td><td>REDIRECT</td><td>CREDIT_CARD</td><td>No</td></tr><tr><td><div><figure><img src="https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2F1FjK2QmgQqccmQtOSNsK%2Fimage.png?alt=media&amp;token=b1015bfa-f3aa-4746-b38c-5599a4409ef7" alt="" width="120"><figcaption></figcaption></figure></div></td><td> <code>CVU</code></td><td>Bank Transfer</td><td>REDIRECT ONE_SHOT</td><td>BANK_DEPOSIT</td><td>Yes</td></tr><tr><td><p></p><p><img src="https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2F1FjK2QmgQqccmQtOSNsK%2Fimage.png?alt=media&amp;token=b1015bfa-f3aa-4746-b38c-5599a4409ef7" alt="" data-size="original"></p></td><td><code>CVUO</code></td><td>CVU Offline</td><td>OFFLINE</td><td>BANK_DEPOSIT</td><td>No</td></tr><tr><td><div><figure><img src="https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2F2qPnhvzUpCcDjPcO477I%2Fimage.png?alt=media&amp;token=a6a9baf0-5593-4e28-9478-a3d72b5a1dd8" alt="" width="120"><figcaption></figcaption></figure></div></td><td> <code>VI</code></td><td>Visa</td><td>REDIRECT</td><td>CREDIT_CARD</td><td>Yes</td></tr><tr><td><div><figure><img src="https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2FsmR4dwRoO6XAsLD29qZY%2Fimage.png?alt=media&amp;token=53db32fd-2ffe-4b67-a928-5640b490a56b" alt="" width="120"><figcaption></figcaption></figure></div></td><td> <code>VD</code></td><td>Visa Debit</td><td>REDIRECT</td><td>DEBIT_CARD</td><td>Yes</td></tr><tr><td><div><figure><img src="https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2F5AaI6K95FoPup1SjVQVw%2Fimage.png?alt=media&amp;token=dd911f8b-016f-49e8-857e-bca52ed69b5a" alt="" width="50"><figcaption></figcaption></figure></div></td><td> <code>MC</code></td><td>Mastercard</td><td>REDIRECT</td><td>CREDIT_CARD</td><td>Yes</td></tr><tr><td><div><figure><img src="https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2FhIiEBOWhnOjTcAxEIBd1%2Fimage.png?alt=media&amp;token=6a554cdf-eb4c-4340-9823-3ffc488bf3c9" alt="" width="120"><figcaption></figcaption></figure></div></td><td> <code>MD</code></td><td>Mastercard Debit</td><td>REDIRECT</td><td>DEBIT_CARD</td><td>Yes</td></tr><tr><td><div><figure><img src="https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2FI7KfletC7PZ5sIe5Fd2C%2Fimage.png?alt=media&amp;token=c61d7649-4471-497f-8358-92ab2848d850" alt="" width="120"><figcaption></figcaption></figure></div></td><td> <code>AE</code></td><td>American Express</td><td>REDIRECT</td><td>CREDIT_CARD</td><td>Yes</td></tr></tbody></table>

***

### Fields required for the OneShot Experience

| Payment Method Name | country | amount | payer\[] | payment\_method |
| ------------------- | ------- | ------ | -------- | --------------- |
| All                 | Yes     | Yes    | Yes      | Yes             |

***

### Payer object requirements

| Payment Method Name | document | email | first\_name | last\_name |
| ------------------- | -------- | ----- | ----------- | ---------- |
| All                 | Yes      | Yes   | Yes         | Yes        |

***

Other fields not in these lists are optional.

{% hint style="success" %}

### **CVU Offline**

Additionally to the standard CVU flow described above, we offer a different way in processing CVU deposits.\
To learn more about this flow, please visit <a href="/countries-specifications/cvu-offline" class="button primary">CVU Offline</a>
{% endhint %}


# API Codes

Learn about the API Codes returned by our APIs

## Deposits Status Codes

The `status` of the deposits are separated into different and very specific categories for you to better handle and know the behavior of your customers.

|                                                                       Status                                                                       | Description                                                                                                                                                                                                                                                                                 |
| :------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|       <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/xxdxPxNZuf7krm0BlgOA/CREATED.svg" alt="" data-size="original">      | The deposit is created but the customer hasn't opened the link yet.                                                                                                                                                                                                                         |
|      <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/25JRMEpvPsL1YImeDdKz/INITIATED.svg" alt="" data-size="original">     | The deposit is created and the customer has opened the link but he/she didn't complete the payment flow (select payment method, complete personal details, confirm details) or the provider was unable to process the request.                                                              |
|    <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/bmZ6gd2ShRSdk0ZjIKJW/EARLY_RELEASE.svg" alt="" data-size="original">   | The deposit is created with all the information required and it is awaiting on customer's payment. It has been marked by you to release it earlier. Please note that the customer hasn't paid yet and the money won't be credited to your balance until the customer's payment is detected. |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/x84M1Rzu2mq1QN3W8B0e/Untitled%20Diagram.svg" alt="" data-size="original"> | The deposit is created with all the information required and it is awaiting on customer's payment.                                                                                                                                                                                          |
|     <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/DJUv7saN6DzAr05nlgEi/FOR_REVIEW.svg" alt="" data-size="original">     | The deposit didn't pass our anti-fraud systems and will be retained until manual review.                                                                                                                                                                                                    |
|       <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/KWMLaXyoHRnWvC5ouZq5/EXPIRED.svg" alt="" data-size="original">      | The deposit has reached its expiration time and the user didn't pay.                                                                                                                                                                                                                        |
|      <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/broVfspC5o0HcXmuzVmk/CANCELLED.svg" alt="" data-size="original">     | The deposit has been cancelled by the customer or it has been 7 days after the expiration.                                                                                                                                                                                                  |
|      <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/P8GyWfndt8zIXZROTLxk/APPROVED.svg" alt="" data-size="original">      | The deposit was paid by the customer but it still hasn't arrived the payer's crypto wallet. Only used for [crypto payments](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#crypto-payments).                                                                           |
|      <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/mbgGsYgmNYZPCGhfCL3r/COMPLETED.svg" alt="" data-size="original">     | The deposit has been completed and the money was credited to your account or to the payer's crypto wallet.                                                                                                                                                                                  |

{% hint style="success" %}
Use the [Deposit Status Endpoint](broken://pages/-M7hYZI8TG8c1K-q33ly) to retrieve the status of a refund.
{% endhint %}

## Refunds Status Codes

|                                                                       Status                                                                       | Description                                                                           |
| :------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------- |
| <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/x84M1Rzu2mq1QN3W8B0e/Untitled%20Diagram.svg" alt="" data-size="original"> | The refund is created and is pending to be processed. It can still be cancelled.      |
|  <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/rWQsjdOrsPOUeRKAFSol/INCORRECT_DETAILS.svg" alt="" data-size="original"> | The refund is pending for you to provide more information. It can still be cancelled. |
|      <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/yx733ZARwGqAKnMKdr5R/DELIVERED.svg" alt="" data-size="original">     | The refund has been sent to the bank for processing. It can't be cancelled anymore.   |
|      <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/broVfspC5o0HcXmuzVmk/CANCELLED.svg" alt="" data-size="original">     | The refund has been manually cancelled. Final status.                                 |
|      <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/ATHFV1nSai3AKSWvpuzG/REJECTED.svg" alt="" data-size="original">      | The refund has been rejected by the bank. Final status.                               |
|      <img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/mbgGsYgmNYZPCGhfCL3r/COMPLETED.svg" alt="" data-size="original">     | The refund has been completed. Final status.                                          |

{% hint style="success" %}
Use the [Refund Status Endpoint](/api-documentation/deposits-api/endpoints/refund-status-endpoint) to retrieve the status of a refund.
{% endhint %}

## API Error Codes

### Categories

We group the error codes into different categories for better understanding.

* `1xx` - Header errors
* `2xx` - Merchant/request validations errors
* `3xx` - User errors
* `4xx` - Create deposit errors
* `5xx` - Other errors
* `7xx` - Internal errors
* `8xx` - [Refund errors](/api-documentation/deposits-api/api-codes#refund-error-codes)
* `9xx` - [Credit Card errors](/api-documentation/deposits-api/api-codes#credit-card-error-codes)

###

### Deposit API Error Codes

<table><thead><tr><th width="150" align="center">API Code</th><th width="150" align="center">HTTP Code</th><th align="center">Type</th><th>Message</th><th>Description</th></tr></thead><tbody><tr><td align="center">100</td><td align="center">401</td><td align="center"><code>INVALID_CREDENTIALS</code></td><td>Invalid Credentials</td><td>The <code>X-Login</code> you sent is incorrect or it is not yet active</td></tr><tr><td align="center">101</td><td align="center">400</td><td align="center"><code>MISSING_REQUIRED_HEADER</code></td><td>Missing or invalid format for required header {headerName}</td><td>Make sure all the headers are correct. <a href="/api-documentation/deposits-api/technical-and-security-aspects#headers">Click here for details</a></td></tr><tr><td align="center">102</td><td align="center">400</td><td align="center"><code>INVALID_SIGNATURE</code></td><td>Invalid signature</td><td>Invalid <code>Authorization</code> signature. <a href="/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature">Click here for instructions</a></td></tr><tr><td align="center">103</td><td align="center">400</td><td align="center"><code>INVALID_DATE_RANGE</code></td><td>X-Date header value out of valid range</td><td>The <code>X-Date</code> value you sent in the header is outside the allowed time-frame. <a href="/api-documentation/deposits-api/technical-and-security-aspects#x-date">Click here for details</a></td></tr><tr><td align="center">104</td><td align="center">400</td><td align="center"><code>IDEMPOTENCY_KEY_ALREADY_USED</code></td><td>Idempotency key {key} has been already used</td><td>The X-Idempotency-Key you sent has already been used</td></tr><tr><td align="center">105</td><td align="center">400</td><td align="center"><code>EMPTY_HEADER_VALUE</code></td><td>Optional header {headerName} must not be blank</td><td>If an optional header is sent, it can't be blank</td></tr><tr><td align="center">200</td><td align="center">405</td><td align="center"><code>METHOD_NOT_ALLOWED</code></td><td>Method not allowed</td><td>The request method used is not allowed. <a href="/api-documentation/deposits-api/endpoints">Click here</a> for endpoints instructions</td></tr><tr><td align="center">201</td><td align="center">400</td><td align="center"><code>BEAN_VALIDATION_ERROR</code></td><td>Field validation error. Check details</td><td>One or more fields sent were incorrect</td></tr><tr><td align="center">202</td><td align="center">401</td><td align="center"><code>INVALID_IP</code></td><td>Unregistered IP address</td><td>You must whitelist your IP Address. <a href="/api-documentation/deposits-api/technical-and-security-aspects#ip-whitelisting">Click here for instructions</a></td></tr><tr><td align="center">203</td><td align="center">429</td><td align="center"><code>VELOCITY_CHECK</code></td><td>Too many consecutive attempts for user (Velocity Check)</td><td>The user has created many deposits in a short period of time</td></tr><tr><td align="center">204</td><td align="center">400</td><td align="center"><code>INVALID_MEDIA_TYPE</code></td><td>Invalid media type</td><td>The payload format is in an unsupported format. Make sure the header Content-Type is <code>application/json</code></td></tr><tr><td align="center">205</td><td align="center">400</td><td align="center"><code>MISSING_REQUEST_PARAMETER</code></td><td>Missing request parameter</td><td>The request is missing an important parameter</td></tr><tr><td align="center">206</td><td align="center">400</td><td align="center"><code>MISSING_PATH_VARIABLE</code></td><td>Missing path variable</td><td>The request is missing an important path variable</td></tr><tr><td align="center">207</td><td align="center">400</td><td align="center"><code>INVALID_REQUEST_PARAMETER_TYPE</code></td><td>Invalid request parameter type</td><td>A parameter type sent was incorrect</td></tr><tr><td align="center">208</td><td align="center">404</td><td align="center"><code>RESOURCE_NOT_FOUND</code></td><td>Resource not found</td><td>The deposit_id being used doesn't exist</td></tr><tr><td align="center">209</td><td align="center">400</td><td align="center"><code>INVALID_REQUEST_BODY</code></td><td>Invalid request body: {details}</td><td>There is a syntax error in the JSON payload</td></tr><tr><td align="center">212</td><td align="center">400</td><td align="center"><code>DEPOSIT_REJECTED_FRAUD_CHECK</code></td><td>Rejected after fraud check</td><td>Transaction has been flagged as potential fraud</td></tr><tr><td align="center">217</td><td align="center">403</td><td align="center"><code>FORBIDDEN_MERCHANT</code></td><td>Merchant has no authorization to use this API</td><td>Your Merchant Account is not enabled to use this API. Contact your Account Manager for more information</td></tr><tr><td align="center">218</td><td align="center">400</td><td align="center"><code>CRYPTO_NOT_ALLOWED_FOR_MERCHANT</code></td><td>Wrong merchant routing type for crypto payments</td><td>Your Merchant Account is not enabled to use the Crypto functionality. Contact your Account Manager for more information</td></tr><tr><td align="center">300</td><td align="center">400</td><td align="center"><code>USER_BLACKLISTED</code></td><td>User blacklisted</td><td>The user is known for committing fraud</td></tr><tr><td align="center">301</td><td align="center">400</td><td align="center"><code>USER_GREYLISTED</code></td><td>User greylisted</td><td>The user is banned because we detected suspicious behavior</td></tr><tr><td align="center">302</td><td align="center">400</td><td align="center"><code>USER_UNAUTHORIZED</code></td><td>User unauthorized</td><td>The user is blocked. For further information go to the "Clients" section on the Merchant Panel</td></tr><tr><td align="center">303</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>User rejected after KYC check</td><td>Check the user's situation</td></tr><tr><td align="center">304</td><td align="center">400</td><td align="center"><code>USER_LIMIT_EXCEEDED</code></td><td>The user limit has been exceeded: {TRANSACTION|DAILY|WEEKLY|MONTHLY}</td><td>Check the user's limit on the Merchant Panel under the "Clients" section</td></tr><tr><td align="center">305</td><td align="center">400</td><td align="center"><code>PAYMENT_METHOD_RESTRICTED</code></td><td>Restricted payment method type</td><td>The payment type is disallowed for the payer</td></tr><tr><td align="center">306</td><td align="center">400</td><td align="center"><code>REGULATORY_LIMIT</code></td><td>The transaction cannot be completed due to regulatory limits applied to the payers account.</td><td>The transaction could not be processed for the Payer due to regulatory limits.</td></tr><tr><td align="center">400</td><td align="center">400</td><td align="center"><code>INVALID_AMOUNT</code></td><td>Invalid amount. The minimum is USD 2 or equivalent in local currency</td><td>The amount does not reach the minimum limit of USD 2</td></tr><tr><td align="center">401</td><td align="center">400</td><td align="center"><code>PAYMENT_METHOD_NOT_FOUND</code></td><td>Payment method not found</td><td>The <code>payment_method_code</code> sent isn't correct, or the Payment Method isn't enabled for your Merchant account. Use the <a href="broken://pages/-M7hYgDIPRyR1p3XGmws">payment_methods</a> API to diagnose this error</td></tr><tr><td align="center">402</td><td align="center">400</td><td align="center"><code>INVOICE_ALREADY_USED</code></td><td>Invoice already used</td><td>The <code>invoice_id</code> sent has already been used</td></tr><tr><td align="center">403</td><td align="center">400</td><td align="center"><code>INVALID_BANK_CODE</code></td><td>Invalid bank code: {code}</td><td>The <code>bank_code</code> sent is invalid</td></tr><tr><td align="center">404</td><td align="center">400</td><td align="center"><code>ERROR_CREATING_PAYMENT</code></td><td>Payment method provider unavailable</td><td>Our provider is temporarily unavailable. Use a different payment method or try again</td></tr><tr><td align="center">406</td><td align="center">400</td><td align="center"><code>INVALID_ADDRESS</code></td><td>Invalid address</td><td>The <code>address</code> sent is invalid</td></tr><tr><td align="center">407</td><td align="center">400</td><td align="center"><code>INVALID_CITY</code></td><td>Invalid city</td><td>The <code>city</code> sent is invalid</td></tr><tr><td align="center">408</td><td align="center">400</td><td align="center"><code>PAYMENT_METHOD_LIMIT_EXCEEDED</code></td><td>Payment method limit exceeded</td><td>The <code>amount</code> sent exceeds the provider's payment method limit. Try with a smaller amount</td></tr><tr><td align="center">410</td><td align="center">400</td><td align="center"><code>PAYMENT_METHOD_MINIMUM_REQUIRED</code></td><td>Payment method minimum required</td><td>The <code>amount</code> sent is smaller than the provider's payment method minimum limit. Try with a bigger amount</td></tr><tr><td align="center">411</td><td align="center">400</td><td align="center"><code>INVALID_USER_DOCUMENT</code></td><td>Invalid user document ID</td><td>The document_id specified was rejected by the provider itself. Check it is valid</td></tr><tr><td align="center">412</td><td align="center">400</td><td align="center"><code>PAYMENT_METHOD_UNAVAILABLE</code></td><td>Payment Method Unavailable</td><td>The payment method is temporarily unavailable, please try again later</td></tr><tr><td align="center">413</td><td align="center">400</td><td align="center"><code>INVALID_REPORTED_INFO_BANK_BENEFICIARY</code></td><td>Invalid reportedInfo.bankBeneficiary value</td><td>The value sent in the field <code>reported_info.bank_beneficiary</code> is invalid.<a href="/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#reported_info-object"> Check validations</a></td></tr><tr><td align="center">414</td><td align="center">400</td><td align="center"><code>MISSING_REPORTED_INFO</code></td><td>Missing reportedInfo attribute</td><td>There are missing values for the reported_info object. <a href="/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#payment-methods-requiring-the-reported_info-object">Check requirements</a></td></tr><tr><td align="center">415</td><td align="center">400</td><td align="center"><code>INVALID_REPORTED_INFO_BANK_BRANCH</code></td><td>Invalid reportedInfo.bankBranch value</td><td>The value sent in the field <code>reported_info.bankBranch</code> is invalid. <a href="/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#payment-methods-requiring-the-reported_info-object">Check validations</a></td></tr><tr><td align="center">416</td><td align="center">400</td><td align="center"><code>INVALID_REPORTED_INFO_BANK_ACCOUNT_NUMBER</code></td><td>Invalid reportedInfo.bankAccountNumber value</td><td>The value sent in the field <code>reported_info.bankAccountNumber</code> is invalid.<a href="/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#payment-methods-requiring-the-reported_info-object"> Check validations</a></td></tr><tr><td align="center">417</td><td align="center">400</td><td align="center"><code>INVALID_REPORTED_INFO_ACCOUNT_TYPE</code></td><td>Invalid reportedInfo.bankAccountType value</td><td>The value sent in the field <code>reported_info.bankAccountType</code> is invalid.<a href="/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#payment-methods-requiring-the-reported_info-object"> Check validations</a></td></tr><tr><td align="center">418</td><td align="center">400</td><td align="center"><code>MISSING_REQUIRED_FIELDS</code></td><td>Missing required fields in order to generate Deposit</td><td>The request is missing a required field. Please check <a href="/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience">here</a>.</td></tr><tr><td align="center">419</td><td align="center">400</td><td align="center"><code>MISSING_PAYER_ID_OR_DOCUMENT</code></td><td>payer.id or payer.document field is missing</td><td>The request is missing the payer.id or payer.document field and at least one of them is mandatory to create the deposit</td></tr><tr><td align="center">500</td><td align="center">500</td><td align="center"><code>GENERIC_ERROR</code></td><td>Oh no! Something has gone wrong. Please contact a system administrator</td><td>Internal error, please contact support</td></tr><tr><td align="center">511</td><td align="center">400</td><td align="center"><code>NO_PAYMENT_METHODS_AVAILABLE</code></td><td>No payment methods available</td><td>Please contact your AM regarding payment methods’ availability</td></tr><tr><td align="center">720</td><td align="center">400</td><td align="center"><code>MISSING_CONFIGURATION</code></td><td>Missing configuration for merchant account</td><td>Please contact your AM/TAM</td></tr></tbody></table>

###

### Refund API Error Codes

<table><thead><tr><th width="150" align="center">API Code</th><th width="150" align="center">HTTP Code</th><th align="center">Type</th><th>Message</th><th>Description</th></tr></thead><tbody><tr><td align="center">800</td><td align="center">400</td><td align="center"><code>REFUND_NOT_ENABLED</code></td><td>Refund is not enabled</td><td>Your Merchant account doesn't have the refund capability enabled. Check with your Account Manager</td></tr><tr><td align="center">801</td><td align="center">400</td><td align="center"><code>DEPOSIT_NOT_COMPLETED</code></td><td>Refund cannot be applied since deposit is not in status completed</td><td>The refunds can only be applied over COMPLETED deposits</td></tr><tr><td align="center">802</td><td align="center">400</td><td align="center"><code>INVALID_AMOUNT_TO_REFUND</code></td><td>Amount to refund not valid</td><td>The amount to refund is not valid. Check if the amount is negative or bigger than the deposit itself.</td></tr><tr><td align="center">803</td><td align="center">400</td><td align="center"><code>INSUFFICIENT_FUNDS</code></td><td>Insufficient funds</td><td>Your Merchant account doesn't have enough funds to cover for the refund amount</td></tr><tr><td align="center">804</td><td align="center">400</td><td align="center"><code>MISSING_BANK_ACCOUNT</code></td><td>Missing bank account information</td><td>The bank account information is missing</td></tr><tr><td align="center">805</td><td align="center">400</td><td align="center"><code>ERROR_IN_REFUND</code></td><td>Error, the refund was not processed. {details}</td><td>The refund could not be completed. Flag it for review on our Merchant Panel for further information</td></tr></tbody></table>

### PCI Deposit API Error codes

<table><thead><tr><th width="124" align="center">API Code</th><th width="128" align="center">HTTP Code</th><th width="203" align="center">Type</th><th width="197">Message</th><th>Description</th></tr></thead><tbody><tr><td align="center">421</td><td align="center">400</td><td align="center"><code>INSTALLMENTS_NOT_ENABLED</code></td><td>Merchant {MID} does not support installments for country {iso}.</td><td>Your merchant account is not allowed to create deposits with installments in that country.</td></tr><tr><td align="center">422</td><td align="center">400</td><td align="center"><code>INSTALLMENTS_QUANTITY_INVALID</code></td><td>Merchant {MID} installments quantity is invalid for country {iso code}. Requested {number}, allowed [{quantity of installments allowed}].</td><td>The amount of installments requested is not allowed for your merchant account in that country.<br>Please check the allowed quantity.</td></tr><tr><td align="center">900</td><td align="center">400</td><td align="center"><code>CREDIT_CARD_BIN_NOT_FOUND</code></td><td>Invalid credit card bin</td><td>We were unable to find a valid issuer with the first 6 digits of the card</td></tr></tbody></table>

###

### Fraud Reason Codes for KYC Errors&#x20;

{% hint style="info" %}
The reasons below are shown whenever the deposit is declined with `type` `USER_REJECTED_KYC_CHECK` or `DEPOSIT_REJECTED_FRAUD_CHECK`
{% endhint %}

<table><thead><tr><th width="128" align="center">HTTP Code</th><th width="179" align="center">Reason Code</th><th width="162">Reason</th><th width="162">Description</th></tr></thead><tbody><tr><td align="center">400</td><td align="center">101</td><td>Transaction related to blacklisted user.</td><td>The transaction was rejected because one of its attributes was related to a blacklisted user</td></tr><tr><td align="center">400</td><td align="center">102</td><td>Email risk</td><td>High risk detected by our fraud prevention engine related to the user's email address</td></tr><tr><td align="center">400</td><td align="center">103</td><td>Credit card risk</td><td>High risk detected by our fraud prevention engine related to the credit card used</td></tr><tr><td align="center">400</td><td align="center">104</td><td>User rejected after KYC check</td><td>User rejected by our KYC controls</td></tr><tr><td align="center">400</td><td align="center">105</td><td>Underage user detected</td><td>User does not meet the minimum age requirement</td></tr><tr><td align="center">400</td><td align="center">106</td><td>Mismatch between user name and document name</td><td>The user's name does not match the name associated with the document provided</td></tr><tr><td align="center">400</td><td align="center">107</td><td>Document status is not OK</td><td>Some irregularities have been detected while validating the document information</td></tr><tr><td align="center">400</td><td align="center">108</td><td>PEP user detected</td><td>The user is a Politically Exposed Person (PEP)</td></tr><tr><td align="center">400</td><td align="center">109</td><td>High risk detected</td><td>High risk detected by our fraud prevention engine</td></tr><tr><td align="center">400</td><td align="center">110</td><td>Failed biometric check</td><td>Something went wrong while performing the biometric check on the user</td></tr><tr><td align="center">400</td><td align="center">111</td><td>Failed OTP verification</td><td>Something went wrong while performing the OTP check on the user</td></tr><tr><td align="center">400</td><td align="center">112</td><td>3DS Authentication failed</td><td>Transaction rejected due to failed 3DS</td></tr><tr><td align="center">400</td><td align="center">113</td><td>Document does not exist</td><td>Invalid Document</td></tr><tr><td align="center">400</td><td align="center">114</td><td>User rejected after CNPJ validations</td><td>Invalid/Irregular CNPJ (Brasil Only)</td></tr></tbody></table>


# Cashouts API

Cashouts API v3 Introduction

### 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&#x20;
* Merchant account Transaction/Daily/Monthly limits permit the cashout
* Destination Bank Account details are correct.&#x20;
* 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

{% embed url="<https://tinyurl.com/directa24-cashout-postman>" %}
Click here to download the Postman Collection.
{% endembed %}

{% hint style="success" %}
We provide you with test credentials to our test environment, but make sure sure you replace the vars `apiKey`, `apiPassphrase` and `apiSignature` in the Pre-req. Scripts" section of all the requests with your own [API credentials for cashouts](/api-documentation/cashouts-api/technical-and-security-aspects#api-keys)
{% endhint %}


# Technical and Security Aspects

Technical and Security Aspects of our V3 Cashout endpoints

## Security Considerations

* All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail.&#x20;
* API requests without [Payload-Signature](/api-documentation/cashouts-api/technical-and-security-aspects/calculating-the-payload-signature) will also fail.
* You will be able to hit our APIs only from the IPs you have [previously whitelisted](#ip-whitelisting) 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](/api-documentation/cashouts-api/endpoints) do not change.

| Environment | Domain                                 |
| ----------- | -------------------------------------- |
| Staging     | `https://api-stg.zimo-pagos.com/`      |
| Production  | Provided once you complete the testing |

{% hint style="info" %}
Notes:

* You will use the STG endpoints to integrate.
* The STG and PROD environments are not communicated in any way.&#x20;
* No transaction created on the STG environment will be reflected on the PROD environment or vice versa.&#x20;
* The API Keys and configurations between environments are also different.
* In case of seeing the error "Insufficient Funds" on STG, you can create and approve a deposit or reach out to <integration@zimo-pagos.com> to add funds to your account.
  {% endhint %}

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

{% hint style="info" %}

* The API Keys between the STG and PROD environments are different.
  {% endhint %}

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](http://en.wikipedia.org/wiki/Basic_access_authentication). 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](#ip-whitelisting) 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.

| Header            | Format | Mandatory | Description                                                |
| ----------------- | :----: | :-------: | ---------------------------------------------------------- |
| Payload-Signature | String |    Yes    | HMAC256 of the whole JSON Payload using your API Signature |
| Content-Type      | String |    Yes    | `application/json`                                         |
| User-Agent        | String |    Yes    | Server client user agent                                   |

## 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](mailto:integration@d24.com) if you need to whitelist **our servers IPs** on your firewall.&#x20;

## 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.&#x20;

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 Payload-Signature

Learn how to correctly calculate the Signature Control String to authenticate with the V3 Cashout endpoints

## Calculating the Signature <a href="#calculating-the-signature" id="calculating-the-signature"></a>

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.

{% hint style="success" %}
Use your API Signature to create the HASH
{% endhint %}

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 <a href="#notes" id="notes"></a>

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 <a href="#examples" id="examples"></a>

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

{% tabs %}
{% tab title="Java" %}

```java
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();


```

{% endtab %}

{% tab title="PHP" %}

```csharp
<?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)));
?>


```

{% endtab %}

{% tab title="C#" %}

```php
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();


```

{% endtab %}
{% endtabs %}


# Endpoints

Learn how to integrate all of our Cashouts endpoints


# Cashout Creation Endpoint

Learn how to generate cashouts request by using our Cashout API v3 directly from your website

## Cashout Request

<mark style="color:green;">`POST`</mark> `https://api-stg.zimo-pagos.com/v3/cashout`

This endpoint allows you to generate cashout requests

#### Headers

| Name                                                | Type   | Description        |
| --------------------------------------------------- | ------ | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>      | string | `application/json` |
| Payload-Signature<mark style="color:red;">\*</mark> | string | Control signature  |

#### Request Body

| Name                                                | Type    | Description                                                                                   |
| --------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| login<mark style="color:red;">\*</mark>             | string  | Your Zimo-pagos CASHOUTS API login key                                                        |
| pass<mark style="color:red;">\*</mark>              | string  | Your Zimo-pagos CASHOUTS API pass key                                                         |
| external\_id<mark style="color:red;">\*</mark>      | string  | Unique cashout ID on the merchant end                                                         |
| country<mark style="color:red;">\*</mark>           | string  | Country of the cashout                                                                        |
| amount<mark style="color:red;">\*</mark>            | number  | Amount of the cashout                                                                         |
| currency                                            | string  | Currency in which the amount was specified                                                    |
| document\_id<mark style="color:red;">\*</mark>      | string  | Document ID of the beneficiary                                                                |
| document\_type                                      | string  | Document type of the ID specified                                                             |
| beneficiary\_id                                     | string  | beneficiary id (for anonymous)                                                                |
| beneficiary\_name<mark style="color:red;">\*</mark> | string  | Beneficiary's name                                                                            |
| beneficiary\_lastname                               | string  | Beneficiary's last name                                                                       |
| email                                               | string  | Beneficiary's email address                                                                   |
| phone                                               | string  | Beneficiary's phone number                                                                    |
| bank\_code                                          | number  | Beneficiary's bank code                                                                       |
| bank\_account                                       | string  | Beneficiary's bank account                                                                    |
| bank\_branch                                        | string  | Beneficiary's branch of their bank account                                                    |
| account\_type                                       | string  | Beneficiary's account type                                                                    |
| address                                             | string  | Beneficiary's address                                                                         |
| city                                                | string  | Beneficiary's city                                                                            |
| postal\_code                                        | string  | Beneficiary's postal code                                                                     |
| beneficiary\_birthdate                              | string  | Beneficiary's birthdate                                                                       |
| notification\_url<mark style="color:red;">\*</mark> | string  | URL where the notifications will be sent                                                      |
| comments                                            | string  | Commentaries about the cashout                                                                |
| on\_hold                                            | boolean | Used to mark a cashout as on hold and not process it until manually changed to pending by you |

{% tabs %}
{% tab title="200: OK Cashout request successfully created." %}

```bash
{
    "cashout_id": "8405147"
}
```

{% endtab %}

{% tab title="401: Unauthorized The credentials specified are incorrect." %}

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

{% endtab %}

{% tab title="412: Precondition Failed Error in the data validation." %}

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

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


```

{% endtab %}

{% tab title="400: Bad Request KYC error" %}

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

```

{% endtab %}
{% endtabs %}

## Request Fields Description

| Field                  | Format                         | Description                                                                                                                                                 |                                             Validations                                             |
| ---------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------: |
| login                  | string (max length: 32)        | Your Zimo-pagos **CASHOUTS** API Key, found on the Merchant Panel by going to: Settings -> API Access. Notice there are specific Cashout credentials        |                                                                                                     |
| pass                   | string (max length: 32)        | Your Zimo-pagos **CASHOUTS** API Passphrase, found on the Merchant Panel by going to: Settings -> API Access. Notice there are specific Cashout credentials |                                                                                                     |
| external\_id           | string (max length: 100)       | Unique cashout ID on the merchant end                                                                                                                       |                                                                                                     |
| country                | string (length: 2)             | Country code for the cashout in *ISO 3166-1 alpha-2 code* format                                                                                            |                      [See country codes](/countries-specifications#currencies)                      |
| amount                 | Big Decimal (up to 2 decimals) | Cashout amount on the currency specified                                                                                                                    |                                             Valid number                                            |
| currency               | string (length: 3)             | Currency code of the amount in *ISO 4217* format                                                                                                            |                     [See valid currencies](/countries-specifications#currencies)                    |
| document\_id           | string (max length: 40)        | Beneficiary’s personal identification number                                                                                                                |                   [See document validations](/countries-specifications#documents)                   |
| document\_type         | string (maxLength: 15)         | Beneficiary’s personal identification number type                                                                                                           |                [See document types validations](/countries-specifications#documents)                |
| beneficiary\_name      | string (max length: 100)       | Beneficiary's name                                                                                                                                          |                                    String of up to 100 characters                                   |
| beneficiary\_lastname  | string (max length: 100)       | Beneficiary's last name                                                                                                                                     |                                    String of up to 100 characters                                   |
| email                  | string (maxLength: 100)        | Beneficiary's valid email address                                                                                                                           |                 [Valid email address](/countries-specifications#emails-validations)                 |
| phone                  | string (maxLength: 20)         | Beneficiary's phone number                                                                                                                                  |         [See phone number validations](/countries-specifications#mobile-numbers-validations)        |
| bank\_code             | Integer (max length: 6)        | Beneficiary's bank code                                                                                                                                     |          [See bank codes API](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)         |
| bank\_account          | string (max length: 30)        | Beneficiary's bank account number                                                                                                                           | [See bank\_account validations](/api-documentation/cashouts-api/countries-validations#bank-account) |
| bank\_branch           | string (max length: 15)        | Beneficiary's bank branch number                                                                                                                            |  [See bank\_branch validations](/api-documentation/cashouts-api/countries-validations#bank-branch)  |
| account\_type          | string (max length: 1)         | Type of account                                                                                                                                             |    [See bank\_account types](/api-documentation/cashouts-api/countries-validations#account-types)   |
| address                | string (max length: 255)       | Beneficiary's address                                                                                                                                       |                                    String of up to 200 characters                                   |
| city                   | string (max length: 100)       | Beneficiary's city                                                                                                                                          |                                    String of up to 100 characters                                   |
| postal\_code           | string (max length: 20)        | Beneficiary's postal code                                                                                                                                   |          [See postal\_code validations](/countries-specifications#postal-code-validations)          |
| beneficiary\_birthdate | string (pattern: 'YYYYMMDD')   | Beneficiary's birthdate                                                                                                                                     |                                                                                                     |
| notification\_url      | string (max length: 300)       | To be provided if the notification URL is different from the notification URL defined on the Merchant Panel                                                 |                                         Valid URL over HTTPS                                        |
| comments               | string (max length: 200)       | A commentary for this cashout                                                                                                                               |                                    String of up to 200 characters                                   |
| on\_hold               | boolean                        | If the merchant wants to hold the cashout and set it to process later through the merchants panel. Default: false                                           |                                           `[true, false]`                                           |

## Error response

### Error response fields

| Field Name    | Format | Description                                                                                                                                                                        |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | Number | Error code. See the [list of error codes](/api-documentation/cashouts-api/api-codes#cashout-internal-error-codes)                                                                  |
| `message`     | String | Description of the error                                                                                                                                                           |
| `reason`      | String | Reason description for KYC check failure. See the [list of reasons](/api-documentation/cashouts-api/api-codes#fraud-reason-codes-for-kyc-errors). \*Only shown in case of code 504 |
| `reason_code` | Number | Reason code for KYC check failure. See the [list of reason codes](/api-documentation/cashouts-api/api-codes#fraud-reason-codes-for-kyc-errors). \*Only shown in case of code 504   |

### Error response examples

```json
{
  "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.&#x20;

Go to the[ Countries Validations ](/api-documentation/cashouts-api/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 <integration@zimo-pagos.com> 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](https://en.wikipedia.org/wiki/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 ](https://www.geeksforgeeks.org/luhn-algorithm/)if it is a valid card number and/or with a regex for each brand, like the example below.

```java
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](https://en.wikipedia.org/wiki/Luhn_algorithm).

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

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

Invalid bank\_account error on the cc-api endpoint:

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


# Notifications

Learn about how the notifications of the Cashout API v3 work

## Notifications

A notification will be sent every time the status of a cashout changes.&#x20;

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](/api-documentation/cashouts-api/endpoints/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:

| Field               | Format                                  | Description                                           |
| ------------------- | --------------------------------------- | ----------------------------------------------------- |
| date                | Date. Format: YYYY-MM-DD HH:MM:SS (GMT) | Date the cashout changed its status                   |
| bank\_reference\_id | String (max. 50 chars)                  | Reference ID of the bank if any                       |
| comments            | String (max. 200 chars)                 | Comments of the cashout if any                        |
| external\_id        | String (max. 100 chars)                 | ID of the cashout you sent while creating the request |
| control             | String                                  | Control signature of the notification                 |
| cashout\_id         | Number                                  | ID of the cashout on our end                          |
| status\_reason      | String                                  | Reason of the status if any                           |

### STG Testing

In the STG environment you can force a notification to be sent to your `notification_url` from the [STG Merchant Panel](https://merchants-stg.directa24.com/login) 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**.

{% hint style="info" %}
On STG, the notifications could take up to 5 minutes in being sent.
{% endhint %}

![](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/EyLtBkDqQhzqJdd7fQVb/cashout_notifications.png)

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

{% hint style="info" %}
The control string should be generated using your own secret key (API Signature) and must be in upper case.

Make sure you convert the message to hash to UTF-8 to prevent errors.
{% endhint %}

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

{% tabs %}
{% tab title="JAVA" %}

```java
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)));
}

```

{% endtab %}

{% tab title="PHP" %}

```php
$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)));


```

{% endtab %}

{% tab title="C#" %}

```csharp
 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();
 
```

{% endtab %}
{% endtabs %}

## Retry logic

Every time a cashout changes its status, we will send you a notification so you can [check its status](/api-documentation/cashouts-api/endpoints/cashout-status-endpoint) 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.

{% hint style="success" %}
In case of errors while handling the notification, make sure you will answer with an HTTP code distinct than 2XX, that way we will retry the notification.
{% endhint %}

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:

![](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/HJNMTeTzHV8Gx4CAeame/cashout_notifications_failed.png)

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.](/api-documentation/cashouts-api/endpoints/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.

{% hint style="success" %}
It can take up to 2 minute for the notification to be resent.
{% endhint %}

![](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/Z7sS3kDY5MRBb482JqkP/Screen%20Shot%202021-09-23%20at%2013.35.29.png)


# Cashout Status Endpoint

Learn how to use the Endpoint to retrieve the status of a cashout

## Cashout Status Endpoint

<mark style="color:green;">`POST`</mark> `https://api-stg.zimo-pagos.com/v3/cashout/status`

This API allows you to retrieve the status of a cashout

#### Headers

| Name                                                | Type   | Description        |
| --------------------------------------------------- | ------ | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>      | string | `application/json` |
| Payload-Signature<mark style="color:red;">\*</mark> | string | Control Signature  |

#### Request Body

| Name                                           | Type   | Description                                                                                                  |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| login<mark style="color:red;">\*</mark>        | String | Your Zimo-pagos CASHOUTS API login key                                                                       |
| pass<mark style="color:red;">\*</mark>         | string | Your Zimo-pagos CASHOUTS API pass key                                                                        |
| cashout\_id<mark style="color:red;">\*</mark>  | number | The ID of the cashout to check status of. It is the one generated by Zimo-pagos when the cashout was created |
| external\_id<mark style="color:red;">\*</mark> | string | The ID of the cashout to check status of. It is the one you sent when the cashout was created                |

{% tabs %}
{% tab title="200 The status of the cashout was successfully retrieved" %}

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

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

{% endtab %}

{% tab title="401 Invalid credentials error" %}

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

{% endtab %}

{% tab title="412 The cashout ID was not found" %}

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

{% endtab %}
{% endtabs %}

## Cashout Status Request

### Request Example

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

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

### Request Fields Description

| Field         | Format                | Description                                                                                                                                                                                                                     |
| ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `login`       | String. Length 32 max | Your Zimo-pagos **CASHOUTS** API Key, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credential                                                                               |
| `pass`        | String. Length 32 max | Your Zimo-pagos **CASHOUTS** API Passphrase, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials                                                                       |
| `cashout_id`  | Number                | Identifier of the cashout on Zimo-pagos' end. It is the one returned by the [Create Cashout Endpoint](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint)                                                      |
| `external_id` | String                | Identifier of the cashout on the Merchant end. It is the one you sent while [Creating the Cashout request](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint). You can opt to send this field or `cashout_id` |

{% hint style="success" %}
You can choose to send the external\_id or the cashout\_id
{% endhint %}

### 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](/api-documentation/cashouts-api/technical-and-security-aspects/calculating-the-payload-signature) for further instructions.

&#x20;

## Cashout Status Response

### Response Example

```java
// 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

| Field                         | Format | Description                                                                                                                                |
| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `cashout_status`              | Number | Status code of the cashout. [See list of status](/api-documentation/cashouts-api/api-codes#cashout-status-codes)                           |
| `cashout_status_description`  | String | Description of the status                                                                                                                  |
| `provider_external_reference` | String | ID of the transaction on the bank side. For Pix, it's the E2E ID (End-to-end)                                                              |
| `bank[]`                      | object | Object containing information about the bank of the beneficiary                                                                            |
| `bank[].code`                 | String | Code of the bank of the beneficiary                                                                                                        |
| `bank[].name`                 | String | Name of the bank of the beneficiary                                                                                                        |
| `bank[].branch`               | String | Branch of the beneficiary's bank account                                                                                                   |
| `bank[].account`              | String | Account number of the beneficiary's bank account                                                                                           |
| `bank[].beneficiary_name`     | String | Name of the owner of the account                                                                                                           |
| `rejection_code`              | Number | Rejection code if sent by the bank. [See list of rejection codes](/api-documentation/cashouts-api/api-codes#cashout-rejection-error-codes) |
| `rejection_reason`            | String | Reason of the rejection if sent by the bank                                                                                                |

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

```json
{
    "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](/api-documentation/cashouts-api/api-codes#cashout-status-codes) to see each Cashout Status meaning.

### Cashout Status Flow

&#x20;

![Cashout Status Flow Diagram](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/WgVDw2rEviEUucEkDpgU/Cashouts%20Status%20Flow%20v3.svg)

{% hint style="info" %}

1. DECLINED: The DECLINED status is not a status by itself. It means the transaction couldn't be created because of an error with the data, the customer or the merchant configuration. No transaction will change its status from DECLINED.
2. PENDING: Once the cashout is in PENDING status, it means it was successfully created and that it will be send for processing soon, changing to DELIVERED. It can also be manually changed to ON\_HOLD or CANCELLED.
3. ON\_HOLD: A cashout will be created with ON\_HOLD status only if specified while creating the cashout with *on\_hold: true.* Otherwise, it can be manually set to ON\_HOLD from the Merchant Panel. If a cashout is ON\_HOLD, it won't be send for processing until you manually go and set it to PENDING from the Merchant Panel. It can still be CANCELLED.
4. CANCELLED: It means you didn't want to proceed with the cashout and it was CANCELLED through the Merchant Panel or through the Cancel Cashout Endpoint. Final status.
5. DELIVERED: As soon as the cashout is sent to the bank for processing, its status will change to DELIVERED. At which point it can't be cancelled anymore.
6. COMPLETED: If the cashout was successfully completed, its status will be set to COMPLETED. Final status\*.
7. REJECTED: If the cashout was rejected by the bank, its status will be set to REJECTED. Final status. \
   \
   \*There are cases in which the banks confirm that a payout was successfully processed and after a few days, it gets returned by the beneficiary's bank therefore the status on our platform will change to REJECTED as well. Those are corner cases but must be considered.
   {% endhint %}

## Status codes

Check all the possible status codes in the following page:

{% content-ref url="/pages/-M9uqleE2Ysi\_e8bMH3B" %}
[API Codes](/api-documentation/cashouts-api/api-codes)
{% endcontent-ref %}


# Cashout Update Status Endpoint

Learn how to use the endpoint to update the status of a cashout

## Cashout Update Status Endpoint

<mark style="color:orange;">`PUT`</mark> `https://api-stg.zimo-pagos.com/v3/cashout/status`

This API allows you to change the status of a cashout

#### Headers

| Name                                                | Type   | Description        |
| --------------------------------------------------- | ------ | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>      | string | `application/json` |
| Payload-Signature<mark style="color:red;">\*</mark> | string | Control Signature  |

#### Request Body

| Name                                          | Type   | Description                                                                                                  |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| login<mark style="color:red;">\*</mark>       | String | Your Zimo-Pagos CASHOUTS API login key                                                                       |
| pass<mark style="color:red;">\*</mark>        | string | Your Zimo-Pagos CASHOUTS API pass key                                                                        |
| cashout\_id<mark style="color:red;">\*</mark> | number | The ID of the cashout to asign status to. It is the one generated by Zimo-Pagos when the cashout was created |
| status<mark style="color:red;">\*</mark>      | string | The status to be assigned to the cashout                                                                     |

{% tabs %}
{% tab title="200 The status of the cashout was successfully retrieved" %}

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

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

{% endtab %}

{% tab title="401 Invalid credentials error" %}

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

{% endtab %}

{% tab title="412 The cashout ID was not found" %}

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

{% endtab %}
{% endtabs %}

## 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](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint).

{% hint style="info" %}
Only cashouts in PENDING status can be updated to ON\_HOLD. Once the cashout was sent to the bank, it will change to DELIVERED at which point it can't be cancelled anylonger
{% endhint %}

If a cashout is ON\_HOLD and you would like to definitely cancel it, please see the [Cashout Cancellation Endpoint](/api-documentation/cashouts-api/endpoints/cashout-cancel-endpoint)

{% hint style="warning" %}
Cashouts in ON\_HOLD retain the amounts from your balance, so be careful to not accumulate cashouts in this status for long time.
{% endhint %}

## Cashout Update Status Request

### Request Example

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

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

### Request Fields Description

| Field        | Format                | Description                                                                                                                                                        |
| ------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `login`      | String. Length 32 max | Your D24 **CASHOUTS** API Key, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials                        |
| `pass`       | String. Length 32 max | Your D24 **CASHOUTS** API Passphrase, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials                 |
| `cashout_id` | Number                | Identifier of the cashout on D24 end. It is the one returned by the [Create Cashout Endpoint](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint) |
| `status`     | String                | Status to be assigned to the cashout. Valid values: `PENDING`, `ON_HOLD`                                                                                           |

###

### 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](/api-documentation/cashouts-api/technical-and-security-aspects/calculating-the-payload-signature) for further instructions.

&#x20;

## Cashout Update Status Response

### Error Response Example

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

| `code`    | Number | Error code               |
| --------- | ------ | ------------------------ |
| `message` | String | Description of the error |

## Status Flow

[Click here](/api-documentation/cashouts-api/api-codes#cashout-status-codes) to see each Cashout Status meaning.

### Cashout Status Flow

&#x20;

![Cashout Status Flow Diagram](https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/WgVDw2rEviEUucEkDpgU/Cashouts%20Status%20Flow%20v3.svg)

{% hint style="info" %}

1. DECLINED: The DECLINED status is not a status by itself. It means the transaction couldn't be created because of an error with the data, the customer or the merchant configuration. No transaction will change its status from DECLINED.
2. PENDING: Once the cashout is in PENDING status, it means it was successfully created and that it will be send for processing soon, changing to DELIVERED. It can also be manually changed to ON\_HOLD or CANCELLED.
3. ON\_HOLD: A cashout will be created with ON\_HOLD status only if specified while creating the cashout with *on\_hold: true.* Otherwise, it can be manually set to ON\_HOLD from the Merchant Panel. If a cashout is ON\_HOLD, it won't be send for processing until you manually go and set it to PENDING from the Merchant Panel. It can still be CANCELLED.
4. CANCELLED: It means you didn't want to proceed with the cashout and it was CANCELLED through the Merchant Panel or through the Cancel Cashout Endpoint. Final status.
5. DELIVERED: As soon as the cashout is sent to the bank for processing, its status will change to DELIVERED. At which point it can't be cancelled anymore.
6. COMPLETED: If the cashout was successfully completed, its status will be set to COMPLETED. Final status\*.
7. REJECTED: If the cashout was rejected by the bank, its status will be set to REJECTED. Final status.
   {% endhint %}

* 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:

{% content-ref url="/pages/-M9uqleE2Ysi\_e8bMH3B" %}
[API Codes](/api-documentation/cashouts-api/api-codes)
{% endcontent-ref %}


# Cashout Cancellation Endpoint

Learn how to use the Cashout Cancellation Endpoint to cancel cashouts when needed

## Cashout Cancellation Endpoint

<mark style="color:red;">`DELETE`</mark> `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

| Name                                                | Type   | Description        |
| --------------------------------------------------- | ------ | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>      | string | `application/json` |
| Payload-Signature<mark style="color:red;">\*</mark> | string | Control Signature  |

#### Request Body

| Name                                           | Type   | Description                                                                                          |
| ---------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| login<mark style="color:red;">\*</mark>        | string | Your Zimo-Pagos CASHOUTS API login key                                                               |
| pass<mark style="color:red;">\*</mark>         | string | Your Zimo-Pagos CASHOUTS API pass key                                                                |
| cashout\_id<mark style="color:red;">\*</mark>  | number | The ID of the cashout to cancel. It  is the one generated by Zimo-Pagos when the cashout was created |
| external\_id<mark style="color:red;">\*</mark> | string | The external ID of the cashout to cancel. It  is the one you sent when generating the cashout        |

{% tabs %}
{% tab title="200 Cashout cancelled" %}

```java
{
    "cashout_status": 2,
    "cashout_status_description": "Canceled"
}
```

{% endtab %}

{% tab title="412 Error while cancelling the cashout. It can be cancelled only if its status is Pending" %}

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

{% endtab %}
{% endtabs %}

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

{% hint style="info" %}
The method to use this endpoint has to be **DELETE**.
{% endhint %}

###

### Request Example

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

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

### Request Fields

| Field         | Format                | Description                                                                                                                                                         |
| ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `login`       | String. Length 32 max | Your Zimo-Pagos **CASHOUTS** API Key, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials                  |
| `pass`        | String. Length 32 max | Your Zimo-Pagos **CASHOUTS** API Passphrase, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials           |
| `cashout_id`  | Number                | Identifier of the cashout in the Zimo-Pagos end. Returned by the [Create Cashout Endpoint](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint)     |
| `external_id` | String                | The external ID of the cashout to cancel. It is the one you sent when [generating the cashout](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint) |

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

[Click here](/api-documentation/cashouts-api/technical-and-security-aspects/calculating-the-payload-signature) for further instructions.

## Cancel Cashout Response

### Response Example

```java
// Cashout cancelled successfully
{
    "cashout_status": 2,
    "cashout_status_description": "Canceled"
}

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

// The cashout can't be cancelled because its status is not Pending
{
    "code": 510,
    "message": "Invalid status transition"
}
```

**Response fields**

| Field                        | Format | Type    | Description                                                                                                           |
| ---------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `cashout_status`             | Number | Success | If shown, it is the new[ status code](/api-documentation/cashouts-api/api-codes#cashout-status-codes) of the cashout. |
| `cashout_status_description` | String | Success | If shown, it described the new status  of the cashout.                                                                |
| `code`                       | Number | Error   | Error code                                                                                                            |
| `message`                    | String | Error   | Error description                                                                                                     |


# Cashout Bank Codes

Learn how to use the Cashout Bank Codes Endpoint to retrieve the list of bank codes accepted for cashouts in each country

## Cashout Bank Codes

<mark style="color:blue;">`GET`</mark> `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

| Name                                      | Type   | Description      |
| ----------------------------------------- | ------ | ---------------- |
| country<mark style="color:red;">\*</mark> | string | Country ISO code |

#### Headers

| Name                                            | Type   | Description                                                  |
| ----------------------------------------------- | ------ | ------------------------------------------------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization Header. Format: "Bearer your\_read\_only\_key" |

{% tabs %}
{% tab title="200 Bank list successfully retrieved" %}

```java
[
    {
        "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"
    }
]
```

{% endtab %}

{% tab title="401 Invalid credentials error" %}

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

{% endtab %}
{% endtabs %}

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

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

// HEADERS
Authorization: Bearer EKiFOWiHnI 
```

### Request Fields

| Type        | Field           | Format             | Description                                                                                         |
| ----------- | --------------- | ------------------ | --------------------------------------------------------------------------------------------------- |
| Query Param | `country`       | String (length: 2) | [Country ISO code](/countries-specifications#countries-and-currencies)                              |
| Header      | `Authorization` | String             | Bearer Token Authentication. It is a concatenation of the word "Bearer" and your Read Only API Key. |

## Bank Codes Response

### Response Example

```java
[
    {
        "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**

| Field  | Format | Description                                                                                             |
| ------ | ------ | ------------------------------------------------------------------------------------------------------- |
| `code` | Number | Bank code. It is the value you must send in the field `bank_code` of the cashouts and deposits requests |
| `name` | String | Name of the bank                                                                                        |


# Countries Validations

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

## Introduction

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

### American Countries

* [Argentina](/api-documentation/cashouts-api/countries-validations/argentina)


# American Countries

Learn about the cashouts validations of the American countries


# Bolivia

Check the requirements and validations made over the cashouts on Bolivia

## Required fields

<table data-header-hidden><thead><tr><th>Field</th><th>Format</th><th width="249.33333333333331">Description</th></tr></thead><tbody><tr><td>Field</td><td>Format</td><td>Description</td></tr><tr><td><code>login</code></td><td>String</td><td>Cashouts login</td></tr><tr><td><code>pass</code></td><td>String</td><td>Cashouts pass</td></tr><tr><td><code>external_id</code></td><td>String (max length: 100)</td><td>Transaction's ID on your end</td></tr><tr><td><code>document_type</code></td><td>See <a href="/countries-specifications#documents-validations">document validations</a></td><td>Beneficiary's document type.</td></tr><tr><td><code>document_id</code></td><td>See <a href="/countries-specifications#documents-validations">document validations</a></td><td>Beneficiary's document ID.</td></tr><tr><td><code>country</code></td><td><code>BO</code></td><td>See <a href="/countries-specifications#countries-and-currencies">country codes</a></td></tr><tr><td><code>currency</code></td><td><code>BOB</code> / <code>USD</code></td><td>See <a href="/countries-specifications#countries-and-currencies">currency codes</a></td></tr><tr><td><code>amount</code></td><td>Number with up to 2 decimals</td><td>Cashout amount</td></tr><tr><td><code>bank_code</code></td><td>See <a href="#bank-codes">bank codes</a></td><td>Code specifying the beneficiary's bank</td></tr><tr><td><code>bank_account</code></td><td>See <a href="#bank-account-validations">validations below</a></td><td>Beneficiary's bank account</td></tr><tr><td><code>account_type</code></td><td>See <a href="#account-types">account type codes</a></td><td>Beneficiary's bank account type</td></tr><tr><td><code>beneficiary_name</code></td><td>String (max length: 100)</td><td>Beneficiary's name</td></tr></tbody></table>

## Bank Account Validations

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

| Bank name | Bank code | Format                                | Regex        | Example    |
| --------- | :-------: | ------------------------------------- | ------------ | ---------- |
| All       |     -     | Numeric. Between 4 and 30 characters. | `^\d{4,30}$` | 1234567890 |

## Account Types

The `account_type` is specified with only one character described below.

| `account_type` | Description       |
| :------------: | ----------------- |
|     **`C`**    | Checkings account |
|     **`S`**    | Savings account   |

## Example Request

{% tabs %}
{% tab title="Banks" %}

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "country": "BO",
    "currency": "BOB",
    "amount": 100,
    "document_type": "PASS",
    "document_id": "B225255",
    "beneficiary_name": "User",
    "bank_account": "1234567890",
    "bank_code": "001",
    "account_type": "C",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}
{% endtabs %}

## Bank Codes

| Bank                                                 | Code |
| ---------------------------------------------------- | ---- |
| Banco Nacional de Bolivia S.A.                       | 001  |
| Banco PYME Ecofuturo S.A.                            | 002  |
| Banco Mercantil Santa Cruz S.A.                      | 003  |
| Almacenes Internacionales S.A.                       | 004  |
| Banco de Crédito de Bolivia S.A.                    | 005  |
| Warrant Mercantil Santa Cruz S.A.                    | 006  |
| Banco de la Nación Argentina S. A.                  | 007  |
| Banco Do Brasil S.A.- Sucursal Bolivia               | 008  |
| Banco BISA S.A.                                      | 009  |
| E-fectivo ESPM S.A.                                  | 010  |
| Banco Unión S.A.                                    | 014  |
| Banco Económico S.A.                                | 016  |
| Banco Solidario S.A.                                 | 017  |
| Banco Ganadero S.A.                                  | 018  |
| Banco PYME de la Comunidad S.A.                      | 032  |
| Banco para el Fomento a Iniciativas Económicas S.A. | 033  |
| Banco Fortaleza S.A.                                 | 034  |
| Banco Fassil S.A.                                    | 035  |
| Banco Prodem S.A.                                    | 036  |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Brazil

Check the requirements and validations made over the cashouts on Brazil

## Required fields

| Field              | Format                                                                                                                            | Description                                                              |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`            | String                                                                                                                            | Cashouts login                                                           |
| `pass`             | String                                                                                                                            | Cashouts pass                                                            |
| `external_id`      | String (max length: 100)                                                                                                          | Transaction's ID on your end                                             |
| `document_id`      | See [document validations](/countries-specifications#documents-validations)                                                       | Beneficiary's CPF.                                                       |
| `country`          | `BR`                                                                                                                              | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`         | `BRL` / `USD`                                                                                                                     | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`           | Number with up to 2 decimals                                                                                                      | Cashout amount                                                           |
| `bank_code`        | See [bank codes](/api-documentation/cashouts-api/countries-validations/american-countries/brazil#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `bank_account`     | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/brazil#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_branch`      | See [validations below](#bank-branch-validations)                                                                                 | Beneficiary's bank branch                                                |
| `account_type`     | See [account type codes](/api-documentation/cashouts-api/countries-validations/american-countries/brazil#account-types)           | Beneficiary's bank account type                                          |
| `beneficiary_name` | String (max length: 100)                                                                                                          | Beneficiary's name                                                       |
| `phone`            | String (max length: 20 characters - up to 15 digits)                                                                              | Beneficiary's phone - Optional unless using PIX key phone.               |
| `email`            | String (max length: 100)                                                                                                          | Beneficiary's email - Optional unless using PIX key email.               |

## Bank Account Validations

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

| Bank name        | Bank code | Format                                                                                                                                               | Regex                 | Example                                                |
| ---------------- | :-------: | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------ |
| Banco do Brasil  |    001    | Format: DDDDDDDDD-X or DDDDDDDDDX where D are digits and X is a digit or the letter 'X'. The number of digits may change, but can't exceed 10 digits | `^\d{1,9}(-)?[\dxX]$` | 1234567890, 123456789-0, 123456789-X, 123456789X       |
| Santander        |    033    | Format: DDDDDDDDD, DDDDDDDDDD, DDDDDDDDD-D, DDDDDDDDD-D where D are digits. The number of digits has to be from 9 to 10                              | `^\d{7,10} (-)?[\d]$` | 12345678, 12345678-9                                   |
| Banrisul         |    041    | Format: DDDDDDDDD-D or DDDDDDDDDD where D are digits. The number of digits has to be 10                                                              | `^\d{9}(-)?[\d]$`     | 1234567890, 123456789-0                                |
| Caixa            |    104    | Format: DDDDDDDDD-D or DDDDDDDDDDDDDD-D where D are digits. The number of digits has to be between 1 and 15                                          | `^\d{1,14}(-)?[\d]$`  | <p>1234567890,</p><p>123456789-0, 12345678901234-5</p> |
| Bradesco         |    237    | Format: DDDDDDD-D or DDDDDDDD where D are digits. The number of digits may change, but can't exceed 8 digits                                         | `^\d{1,7}(-)?[\d]$`   | 12345678, 1234567-8                                    |
| Mercado Pago     |    323    | Format: DDDDDDDDDD-D or DDDDDDDDDDD where D are digits. The number of digits may change, but can't exceed 11 digits                                  | `^\d{1,9}(-)?[\d]$`   | 12345678910, 1234567891-0                              |
| Itaú             |    341    | Format: DDDDDD-D or DDDDDDD where D are digits. The number of digits may change but ranges from 6 to 7                                               | `^\d{1,7} (-)?[\d]$`  | 123456, 12345-6                                        |
| Pix Key Phone    |   10000   | Empty string                                                                                                                                         | `^$`                  |                                                        |
| Pix Key Email    |   10001   | Empty string                                                                                                                                         | `^$`                  |                                                        |
| Pix Key Document |   10002   | Empty string                                                                                                                                         | `^$`                  | ""                                                     |
| Others           |     -     | Format: DDDDDDDDDD-D or DDDDDDDDDDD where D are digits. The number of digits may change, but can't exceed 11 digits                                  | `^\d{1,9}(-)?[\d]$`   | 123456789, 123456789-0                                 |

## Bank Branch Validations

Use the Regex below to validate the valid (and invalid) bank branches on your end.

<table data-header-hidden><thead><tr><th>Bank name</th><th width="174" align="center">Bank code</th><th>Format</th><th width="216">Regex</th><th>Exceptions</th><th></th></tr></thead><tbody><tr><td>Bank name</td><td align="center">Bank code</td><td>Format</td><td>Regex</td><td>Exceptions</td><td>Example</td></tr><tr><td>Banco do Brasil</td><td align="center">001</td><td>Format: DDDD-X or DDDDX where D are digits and X is a digit or the letter 'X'. The number of digits may change, but can't exceed 5 digits</td><td><code>^\d{1,4}(-)?[\dxX]$</code></td><td><p>Can't have 4 zeros and a digit.</p><p></p><p><code>^0{0,4}(-)?[\dxX]$</code></p></td><td>1234-1, 1234-X, 12341, 1234X</td></tr><tr><td>Santander</td><td align="center">033</td><td>Format: DDDD where D are digits. The number of digits may change, but can't exceed 4 digits</td><td><code>^\d{1,4}$</code></td><td><p>Can't be 033</p><p></p><p><code>^033$</code></p></td><td>1234</td></tr><tr><td>Banrisul</td><td align="center">041</td><td>Format: DDDD-X or DDDDX where D are digits and X is a digit or the letter 'X'. The number of digits may change, but can't exceed 5 digits</td><td><code>^\d{1,4}(-)?[\dxX]$</code></td><td>N/A</td><td>1234-1, 1234-X, 12341, 1234X</td></tr><tr><td>Banco Inter</td><td align="center">077</td><td>Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits</td><td><code>^\d{1,4}(-)?[\d]$</code></td><td><p>Can't start with zeros followed by 77 </p><p></p><p><code>^0{0,3}77$</code></p></td><td>1234-1,  12341</td></tr><tr><td>Caixa</td><td align="center">104</td><td>Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits</td><td><code>^\d{1,4}(-)?[\d]$</code></td><td><p>Can't be: 001/013/023/104</p><p></p><p><code>^001$|^013$|^023$|^104$</code></p></td><td>1234-1, 12341</td></tr><tr><td>Banco Original</td><td align="center">212</td><td>Format: DDDDD-D or DDDDDD where D are digits. The number of digits may change, but can't exceed 5 digits</td><td><code>^\d{1,4}(-)?[\d]$</code></td><td><p>Can't start with zeros followed by 212</p><p></p><p><code>^0{0,2}212$</code></p></td><td>1234-1, 12341</td></tr><tr><td>Bradesco</td><td align="center">237</td><td>Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits</td><td><code>^\d{1,4}(-)?[\d]$</code></td><td><p>Can't be 237</p><p></p><p><code>^237$</code></p></td><td>1234-1, 12341</td></tr><tr><td>Banco Nu Pagamento</td><td align="center">260</td><td>Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits</td><td><code>^\d{1,4}(-)?[\d]$</code></td><td><p>Can't start with zeros followed by 260</p><p></p><p><code>^0{0,2}260$</code></p></td><td>1234-1, 12341</td></tr><tr><td>PagSeguro</td><td align="center">290</td><td>Format: DDD-D or DDDD where D are digits. The number of digits may change, but can't exceed 4 digits</td><td><code>^\d{3}(-)?[\d]$</code></td><td><p>Can't start with zeros followed by 290</p><p></p><p><code>^0{0,2}290$</code></p></td><td>123-4, 1234</td></tr><tr><td>Mercado Pago</td><td align="center">323</td><td><code>N/A</code></td><td><code>N/A</code></td><td><code>N/A</code></td><td>0001</td></tr><tr><td>Itau</td><td align="center">341</td><td>Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits</td><td><code>^\d{1,4}(-)?[\d]$</code></td><td><p>Can't be 314</p><p></p><p><code>^341$</code></p></td><td>1234-1, 12341</td></tr><tr><td>Pix Key Phone</td><td align="center">10000</td><td>Format: "+55 012 92345-1234"</td><td><code>^([+55]{3})([(]?[0]?[1-9]{2}[)]?)[9]?([1-9]{4})-?([0-9]{4})$</code></td><td>N/A</td><td>+55 66 666666666</td></tr><tr><td>Pix Key Email</td><td align="center">10001</td><td><code>N/A</code></td><td><code>^$</code></td><td>N/A</td><td>testuser@gmail.com</td></tr><tr><td>Pix Key Document</td><td align="center">10002</td><td><code>N/A</code></td><td><code>^$</code></td><td>N/A</td><td>N/A</td></tr><tr><td>Others</td><td align="center">-</td><td>Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits</td><td><code>^\d{1,4}(-)?[\d]$</code></td><td>N/A</td><td>1234-1, 12341</td></tr></tbody></table>

### Email validations <a href="#email-validations" id="email-validations"></a>

| Bank name | Bank code | Required | Example                |
| --------- | --------- | -------- | ---------------------- |
| iCash     | 998       | Yes      | <johnSmith1@gmail.com> |

## Account Types

The `account_type` is specified with only one character described below.

| `account_type` | Description           |
| :------------: | --------------------- |
|     **`C`**    | Checkings account     |
|     **`S`**    | Savings account       |
|     **`O`**    | Joint checkings       |
|     **`P`**    | Joint savings account |

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

### Banks<br>

```
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "country": "BR",
    "currency": "BRL",
    "amount": 100,
    "document_id": "01716001340",
    "beneficiary_name": "User",
    "bank_account": "3423422-7",
    "bank_code": "001",
    "bank_branch": "1234",
    "account_type": "C",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

### Type of keys

<table data-header-hidden><thead><tr><th width="209">Bank</th><th>Bank Code</th><th>Details</th></tr></thead><tbody><tr><td>Bank</td><td>Bank Code</td><td>Details</td></tr><tr><td>Pix Key Phone</td><td>10000</td><td><code>bank_account</code> and <code>bank_branch</code> must be empty. The field <code>acount_type</code> can have any value. The field <code>phone</code> must be sent </td></tr><tr><td>Pix Key Email</td><td>10001</td><td><code>bank_account</code> and <code>bank_branch</code> must be empty. The field <code>acount_type</code> can have any value. The field <code>email</code> must be sent </td></tr><tr><td>Pix Key Document</td><td>10002</td><td><code>bank_account</code> and <code>bank_branch</code> must be empty. The field <code>acount_type</code> can have any value. The field <code>document_id</code> must be sent </td></tr><tr><td>Pix Key Random</td><td>10003</td><td><code>bank_branch</code> must be empty. The field <code>account_type</code> can have any value. The field <code>bank_account</code> must be sent - this indicates the customer's PIX random key</td></tr></tbody></table>

If a payout is created without the mandatory fields, it will be rejected.<br>

{% tabs %}
{% tab title="Pix Key Phone" %}

```
{    
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "country": "BR",
    "currency": "BRL",
    "amount": 100,
    "document_id": "01716001340",
    "beneficiary_name": "User",
    "phone": "+5511666666666"
    "bank_code": "10000",
    "bank_account": "",
    "bank_branch": "",
    "account_type": "C",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}

{% tab title="Pix Key Email" %}

```
{    
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "country": "BR",
    "currency": "BRL",
    "amount": 100,
    "document_id": "01716001340",
    "email": "testuser@gmail.com",
    "beneficiary_name": "User",
    "bank_code": "10001",
    "bank_account": "",
    "bank_branch": "",
    "account_type": "C",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}

{% tab title="Pix Key Document" %}

```
{    
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "country": "BR",
    "currency": "BRL",
    "amount": 100,
    "document_id": "01716001340",
    "beneficiary_name": "User",
    "bank_code": "10002",
    "bank_account": "",
    "bank_branch": "",
    "account_type": "C",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}
{% endtabs %}

## Bank Codes

<table data-header-hidden><thead><tr><th width="334.5">Bank</th><th>Code</th></tr></thead><tbody><tr><td>Bank</td><td>Code</td></tr><tr><td>BANCO DO BRASIL S.A.</td><td>001</td></tr><tr><td>BANCO DA AMAZONIA S.A.</td><td>003</td></tr><tr><td>BANCO DO NORDESTE DO BRASIL S.A.</td><td>004</td></tr><tr><td>BANESTES S.A. BANCO DO ESTADO DO ESPIRITO SANTO</td><td>021</td></tr><tr><td>Banco Alfa S.A.</td><td>025</td></tr><tr><td>BANCO SANTANDER BRASIL S.A.</td><td>033</td></tr><tr><td>BANCO ABN AMRO S.A</td><td>075</td></tr><tr><td>BANCO DO ESTADO DO PARA S.A. - BANPARA</td><td>037</td></tr><tr><td>BANCO DO ESTADO DO RIO GRANDE DO SUL S.A. - BANRISUL</td><td>041</td></tr><tr><td>BANCO DO ESTADO DE SERGIPE S.A. - BANESE</td><td>047</td></tr><tr><td>BANCO DE BRASILIA S.A. - BRB</td><td>070</td></tr><tr><td>BANCO INTER</td><td>077</td></tr><tr><td>Banco Original do Agronegócio S.A.</td><td>079</td></tr><tr><td>Cooperativa Central de Crédito (VIACREDI)</td><td>085</td></tr><tr><td>POLOCRED SCMEPP</td><td>093</td></tr><tr><td>Credisis - Central de Cooperativas de Crédito Ltdav</td><td>097</td></tr><tr><td>XP INVESTIMENTOS S.A</td><td>102</td></tr><tr><td>CAIXA ECONOMICA FEDERAL - CEF</td><td>104</td></tr><tr><td>Banco BOCOM BBM S.A.</td><td>107</td></tr><tr><td>BANCO AGIPLAN S.A.</td><td>121</td></tr><tr><td>Confederação Nacional das Cooperativas Centrais Unicred</td><td>136</td></tr><tr><td>Stone Pagamentos S.A</td><td>197</td></tr><tr><td>Banco BTG Pactual S.A.</td><td>208</td></tr><tr><td>BANCO ORIGINAL</td><td>212</td></tr><tr><td>BANCO BONSUCESSO S.A.</td><td>218</td></tr><tr><td>Banco Fibra S.A.</td><td>224</td></tr><tr><td>BANCO BRADESCO S.A.</td><td>237</td></tr><tr><td>NU PAGAMENTOS</td><td>260</td></tr><tr><td>Will Financeira S.A.</td><td>280</td></tr><tr><td>PagSeguro Internet S.A</td><td>290</td></tr><tr><td>Banco BPP Instituição de Pagamento S/A</td><td>301</td></tr><tr><td>BANCO BMG S.A</td><td>318</td></tr><tr><td>China Construction Bank Banco Múltiplo S.A.</td><td>320</td></tr><tr><td>MERCADOPAGO.COM REPRESENTACOES LTDA.</td><td>323</td></tr><tr><td>BANCO BARI DE INVESTIMENTOS E FINANCIAMENTOS S.A</td><td>330</td></tr><tr><td>BAcesso Soluções de Pagamento S.A</td><td>332</td></tr><tr><td>Banco Digio S.A</td><td>335</td></tr><tr><td>BANCO C6 S.A</td><td>336</td></tr><tr><td>ITAU UNIBANCO S.A.</td><td>341</td></tr><tr><td>GERENCIANET S.A</td><td>364</td></tr><tr><td>Banco Société Générale Brasil S.A.</td><td>366</td></tr><tr><td>PICPAY SERVICOS S.A</td><td>380</td></tr><tr><td>BANCO MERCANTIL DO BRASIL S.A.</td><td>389</td></tr><tr><td>Banco Hub pagamentos SA</td><td>396</td></tr><tr><td>HSBC BANK BRASIL S.A. - BANCO MULTIPLO</td><td>399</td></tr><tr><td>CORA SCD S.A</td><td>403</td></tr><tr><td>Banco BV S.A.</td><td>413</td></tr><tr><td>BANCO SAFRA S.A.</td><td>422</td></tr><tr><td>CITIBANK N.A.</td><td>477</td></tr><tr><td>Deutsche Bank S.A. – Banco Alemão</td><td>487</td></tr><tr><td>JPMorgan Chase Bank, National Association</td><td>488</td></tr><tr><td>ING Bank N.V.</td><td>492</td></tr><tr><td>Banco Credit Suisse S.A.</td><td>505</td></tr><tr><td>Neon Pagamentos S.A. IP</td><td>536</td></tr><tr><td>Banco PAN S.A.</td><td>623</td></tr><tr><td>BANCO SOFISA</td><td>637</td></tr><tr><td>Banco Votorantim S.A.</td><td>655</td></tr><tr><td>BANCO DAYCOVAL S.A.</td><td>707</td></tr><tr><td>BANCO OURINVEST S.A</td><td>712</td></tr><tr><td>BANCO CITIBANK</td><td>745</td></tr><tr><td>BANCO MODAL S.A.</td><td>746</td></tr><tr><td>Banco Rabobank International Brasil S.A.</td><td>747</td></tr><tr><td>BANCO COOPERATIVO SICREDI S.A.</td><td>748</td></tr><tr><td>Banco BNP Paribas Brasil S.A.</td><td>752</td></tr><tr><td>BANCO COOPERATIVO DO BRASIL S/A - BANCOOB</td><td>756</td></tr><tr><td>iCash</td><td>998</td></tr><tr><td>Pix Key Phone</td><td>10000</td></tr><tr><td>Pix Key Email</td><td>10001</td></tr><tr><td>Pix Key Document</td><td>10002</td></tr></tbody></table>

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Canada

Check the requirements and validations made over the cashouts on Canada

## Required fields

| Field                  | Format                                                                                                                            | Description                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                            | Cashouts login                                                           |
| `pass`                 | String                                                                                                                            | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                          | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                       | Beneficiary's document ID                                                |
| `country`              | `CA`                                                                                                                              | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `CAD` / `USD`                                                                                                                     | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                      | Cashout amount                                                           |
| `bank_code`            | [Valid](/api-documentation/cashouts-api/countries-validations/american-countries/canada#bank-codes) bank code                     | Code specifying the beneficiary's bank                                   |
| `bank_account`         | [Valid](/api-documentation/cashouts-api/countries-validations/american-countries/canada#bank-account-validations) bank account    | Beneficiary's bank account                                               |
| `bank_branch`          | [Valid](/api-documentation/cashouts-api/countries-validations/american-countries/canada#bank-branch-validations) institute number | Beneficiary's institute number                                           |
| `email`                | [Valid](/countries-specifications#emails-validations) email address                                                               | Beneficiary's email address                                              |
| `beneficiary_name`     | String (max length: 100)                                                                                                          | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                          | Beneficiary's last name                                                  |

## Bank Account Validations

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

| Bank name | Bank code | Format                                                          | Regex        | Example      |
| --------- | :-------: | --------------------------------------------------------------- | ------------ | ------------ |
| Etransfer |   10000   | For Etransfer, the bank\_account must come empty: "" (Not null) | `^$`         |              |
| Others    |     -     | Numeric between 3 and 16 digits.                                | `^\d{3,16}$` | 738746356473 |

## Bank Branch Validations

Use the Regex below to validate the valid (and invalid) bank branches on your end.

| Bank name | Bank code | Format                                                        | Regex         | Example |
| --------- | :-------: | ------------------------------------------------------------- | ------------- | ------- |
| Etransfer |   10000   | For Etransfer, the bank\_branch must come empty: ""(Not null) | `^$`          |         |
| Others    |     -     | String of 5 characters                                        | `^[\s\S]{5}$` | 12345   |

## Email validations

| Bank name | Bank code | Required | Example                |
| --------- | :-------: | :------: | ---------------------- |
| Etransfer |   10000   |    Yes   | <johnSmith1@gmail.com> |
| Others    |     -     |    No    | -                      |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

{% tabs %}
{% tab title="Etransfer" %}

```java
{
    "login": "xxxxxxxx",
    "pass": "xxxxxxxx",
    "external_id": "30000000001",
    "country": "CA",
    "currency": "CAD",
    "amount": 100,
    "document_id": "5676586998",
    "bank_account": "",
    "bank_code": "10000",
    "bank_branch": "",
    "email": "johnSmith@gmail.com",
    "beneficiary_name": "John",
    "beneficiary_lastname": "Smith",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}

{% tab title="Banks" %}

```java
{
    "login": "xxxxxxxx",
    "pass": "xxxxxxxx",
    "external_id": "30000000001",
    "country": "CA",
    "currency": "CAD",
    "amount": 100,
    "document_id": "5676586998",
    "bank_account": "38749027362",
    "bank_code": "001",
    "bank_branch": "12345",
    "email": "johnSmith@gmail.com",
    "beneficiary_name": "John",
    "beneficiary_lastname": "Smith",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}
{% endtabs %}

## Bank Codes

{% hint style="success" %}

* **Etransfer approval time:** Up to one business day
* **Banks approval time:** Up to four business days
  {% endhint %}

| Bank Name                                                               | Code  |
| ----------------------------------------------------------------------- | ----- |
| Etransfer                                                               | 10000 |
| BANK OF MONTREAL                                                        | 001   |
| THE BANK OF NOVA SCOTIA                                                 | 002   |
| ROYAL BANK OF CANADA                                                    | 003   |
| THE TORONTO-DOMINION BANK                                               | 004   |
| BANQUE NATIONALE DU CANADA                                              | 006   |
| CANADIAN IMPERIAL BANK OF COMMERCE                                      | 010   |
| HSBC BANK CANADA                                                        | 016   |
| CANADIAN WESTERN BANK                                                   | 030   |
| BANQUE LAURENTIENNE DU CANADA                                           | 039   |
| BANK OF CANADA                                                          | 177   |
| CANADA SAVINGS BOND REDEMPTION CERTIFICATE                              | 187   |
| ATB FINANCIAL                                                           | 219   |
| BANK OF AMERICA NATIONAL ASSOCIATION                                    | 241   |
| THE BANK OF NEW YORK MELLON                                             | 242   |
| THE BANK OF TOKYO-MITSUBISHI UFJ LTD                                    | 245   |
| BARCLAYS BANK OF CANADA                                                 | 248   |
| BNP PARIBAS                                                             | 250   |
| CITIBANK CANADA                                                         | 260   |
| DEUTSCHE BANK AG                                                        | 265   |
| MEGA INTERNATIONAL COMMERCIAL BANK (CANADA)                             | 269   |
| JPMORGAN CHASE BANK, NATIONAL ASSOCIATION                               | 270   |
| KEB HANA BANK CANADA                                                    | 275   |
| MIZUHO CORPORATE BANK LTD CANADA BRANCH                                 | 277   |
| NATIONAL BANK OF GREECE (CANADA)                                        | 286   |
| UBS BANK (CANADA)                                                       | 290   |
| SBI CANADA BANK                                                         | 294   |
| SUMITOMO MITSUI BANKING CORPORATION CAN.                                | 301   |
| AMEX BANK OF CANADA                                                     | 303   |
| INDUSTRIAL AND COMMERCIAL BANK OF CHINA                                 | 307   |
| BANK OF CHINA (CANADA)                                                  | 308   |
| CITIZENS BANK OF CANADA                                                 | 309   |
| FIRST NATIONS BANK OF CANADA                                            | 310   |
| BOFA CANADA BANK                                                        | 311   |
| JP MORGAN BANK CANADA                                                   | 314   |
| CTBC BANK CORP. (CANADA)                                                | 315   |
| HABIB CANADIAN BANK                                                     | 321   |
| CAPITAL ONE BANK (CANADA BRANCH)                                        | 323   |
| STATE STREET                                                            | 327   |
| CITIBANK, NA                                                            | 328   |
| COMERICA BANK                                                           | 330   |
| FIRST COMMERCIAL BANK                                                   | 332   |
| VERSABANK                                                               | 334   |
| UNITED OVERSEAS BANK LIMITED                                            | 335   |
| CANADIAN TIRE BANK                                                      | 338   |
| ICICI BANK CANADA                                                       | 340   |
| ZAG BANK                                                                | 342   |
| HOLLIS CANADIAN BANK                                                    | 343   |
| SOCIETE GENERALE (CANADA BRANCH)                                        | 346   |
| DIRECTCASH BANK                                                         | 352   |
| SHINHAN BANK CANADA                                                     | 355   |
| HOME BANK                                                               | 361   |
| WELLS FARGO BANK NA CANADIAN BRANCH                                     | 362   |
| CHINA CONTRUCTION BANK (TORONTO BRANCH)                                 | 366   |
| WEALTH ONE BANK OF CANADA                                               | 370   |
| BANK OF CHINA (TORONTO BRANCH)                                          | 372   |
| TRUST GENERAL INC                                                       | 506   |
| COMMUNITY TRUST COMPANY LTD                                             | 507   |
| THE CANADA TRUST COMPANY                                                | 509   |
| TRUST LA LAURENTIENNE                                                   | 522   |
| THE EFFORT TRUST COMPANY                                                | 532   |
| HOME SAVINGS AND LOAN CORPORATION                                       | 535   |
| INVESTORS GROUP TRUST COMPANY LTD                                       | 536   |
| MANULIFE BANK OF CANADA                                                 | 540   |
| MONTREAL TRUST COMPANY                                                  | 544   |
| MENNONITE TRUST LIMITED                                                 | 547   |
| CIBC TRUST CORPORATION                                                  | 548   |
| MONTREAL TRUST COMPANY OF CANADA                                        | 550   |
| SUN LIFE FINANCIAL TRUST INC.                                           | 551   |
| PEACE HILLS TRUST COMPANY                                               | 568   |
| ROYAL TRUST COMPANY (THE)                                               | 570   |
| ROYAL TRUST COMPANY (THE)                                               | 580   |
| NATIONAL TRUST COMPANY                                                  | 590   |
| CS ALTERNA BANK                                                         | 608   |
| TANGERINE BANK                                                          | 614   |
| B2B BANK                                                                | 618   |
| PEOPLES TRUST COMPANY                                                   | 621   |
| EQUITABLE BANK                                                          | 623   |
| MANULIFE TRUST COMPANY                                                  | 626   |
| THE TORONTO-DOMINION BANK                                               | 715   |
| LATVIAN CREDIT UNION LTD                                                | 803   |
| DUCA FINANCIAL SERVICES CREDIT UNION LTD                                | 806   |
| CENTRAL 1 CREDIT UNION                                                  | 809   |
| ALL TRANS FINANCIAL SERVICES CREDIT UNION LTD                           | 810   |
| AAA GROUP CLEARER NOT UNIQUE                                            | 815   |
| CAISSE FINANCIAL GROUP                                                  | 819   |
| CREDIT UNIONS IN NOVA SCOTIA                                            | 821   |
| CENTRAL 1 CREDIT UNION                                                  | 828   |
| FEDERATION DES CAISSES POPULAIRES DE L'ONTARIO                          | 829   |
| CREDIT UNIONS IN NEW BRUNSWICK                                          | 831   |
| COMMUNITY FIRST - A DIVISION OF YOUR NEIGHBOURHOOD CREDIT UNION LIMITED | 834   |
| CAISSE POPULAIRE DE KAPUSKASING LIMITEE                                 | 836   |
| MERIDIAN CREDIT UNION LIMITED                                           | 837   |
| CREDIT UNION CENTRAL OF NOVA SCOTIA                                     | 839   |
| DUNDALK DISTRICT CREDIT UNION LTD                                       | 840   |
| CREDIT UNIONS IN QUEBEC                                                 | 841   |
| ALTERNA SAVINGS AND CREDIT UNION LTD                                    | 842   |
| RAPPORT CREDIT UNION                                                    | 846   |
| BRUNSWICK CREDIT UNION FEDERATION LTD                                   | 849   |
| CREDIT UNIONS IN ONTARIO                                                | 851   |
| CONCENTRA BANK                                                          | 853   |
| GOLDEN HORSESHOE CREDIT UNION LTD                                       | 854   |
| FEDERATION DES CAISSES POPULAIRES ACADIENNES                            | 865   |
| CREDIT UNION CENTRAL OF MANITOBA                                        | 879   |
| CREDIT UNION CENTRAL OF SASKATCHEWAN                                    | 889   |
| L'ALLIANCE DES CAISSES POPULAIRES DE L'ONTARIO                          | 890   |
| CENTRAL 1 CREDIT UNION ALBERTA                                          | 899   |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Chile

Check the requirements and validations made over the cashouts on Chile

## Required fields

| Field              | Format                                                                                                                           | Description                                                              |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`            | String                                                                                                                           | Cashouts login                                                           |
| `pass`             | String                                                                                                                           | Cashouts pass                                                            |
| `external_id`      | String (max length: 100)                                                                                                         | Transaction's ID on your end                                             |
| `document_id`      | See [document validations](/countries-specifications#documents-validations)                                                      | Beneficiary's document ID                                                |
| `country`          | `CL`                                                                                                                             | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`         | `CLP` / `USD`                                                                                                                    | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`           | Number with up to 2 decimals                                                                                                     | Cashout amount                                                           |
| `bank_code`        | See [bank codes](/api-documentation/cashouts-api/countries-validations/american-countries/chile#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `bank_account`     | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/chile#bank-account-validations) | Beneficiary's bank account                                               |
| `account_type`     | See [account type codes](/api-documentation/cashouts-api/countries-validations/american-countries/chile#account-types)           | Beneficiary's bank account type                                          |
| `beneficiary_name` | String (max length: 100)                                                                                                         | Beneficiary's name                                                       |

## Bank Account Validations

| Bank name | Bank code | Format  | Regex        | Example    |
| --------- | :-------: | ------- | ------------ | ---------- |
| All       |     -     | Numeric | `^\d{6,16}$` | 1234567890 |

## Account Types

The `account_type` is specified with only one character as described below.

| `account_type` | Description       |
| :------------: | ----------------- |
|     **`C`**    | Checkings account |
|     **`S`**    | Savings account   |
|     **`V`**    | Salary account    |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxxx",
    "pass": "xxxxxxxx",
    "external_id": "30000000001",
    "country": "CL",
    "currency": "CLP",
    "amount": 100,
    "document_id": "56765869",
    "bank_account": "56687456",
    "bank_code": "001",
    "account_type": "C",
    "beneficiary_name": "User",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

| Bank                        | Code |
| --------------------------- | ---- |
| Banco de Chile              | 001  |
| Banco Edwards               | 001  |
| Citi                        | 001  |
| Banco Internacional         | 009  |
| Banco del Estado de Chile   | 012  |
| Scotiabank Sud Americano    | 014  |
| Banco Crédito e Inversiones | 016  |
| Corpbanca Bank              | 027  |
| Banco Bice                  | 028  |
| HSBC Bank                   | 031  |
| Banco Santander- Santiago   | 037  |
| Banco Itaú                  | 039  |
| ABN Amor Bank Chile         | 046  |
| Banco Security              | 049  |
| Banco Falabella             | 051  |
| Deutsche Bank               | 052  |
| Banco Ripley                | 053  |
| Radobank Chile              | 054  |
| Consorcio                   | 055  |
| Banco Penta                 | 056  |
| Banco Paris                 | 057  |
| BCI (Mach)                  | 116  |
| BBVA Banco Bhif             | 504  |
| Banco del Desarrollo        | 507  |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Colombia

Check the requirements and validations made over the cashouts on Colombia

## Required fields

| Field                  | Format                                                                                                                                          | Description                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                                          | Cashouts login                                                           |
| `pass`                 | String                                                                                                                                          | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                                        | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#document-validations)              | Beneficiary's document ID                                                |
| `document_type`        | See [document validations](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#document-validations)              | Beneficiary's document type                                              |
| `country`              | `CO`                                                                                                                                            | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `COP` / `USD`                                                                                                                                   | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                                    | Cashout amount                                                           |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#bank-codes)                                  | Code specifying the beneficiary's bank                                   |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#bank-account-validations)             | Beneficiary's bank account                                               |
| `account_type`         | See [account type codes](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#account-types)                       | Beneficiary's bank account type                                          |
| `beneficiary_name`     | String (max length: 100)                                                                                                                        | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                                        | Beneficiary's last name                                                  |
| `address`              | String (max length: 255)                                                                                                                        | Beneficiary's address                                                    |
| `phone`                | String (max length: 20). [See validations](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#phone-validations) | Beneficiary's phone number                                               |
| `email`                | String (max length: 255)                                                                                                                        | Optional Field - Only required for Punto Red                             |

## Bank Account Validations

| Bank name | Bank code | Format                                       | Regex            | Example       |
| --------- | :-------: | -------------------------------------------- | ---------------- | ------------- |
| Nequi     |    1507   | Customer's mobile phone                      | `^[\s\S]{1,20}$` | 5715551234    |
| Daviplata |    1551   | Customer's mobile phone                      | `^[\s\S]{1,20}$` | 5715551234    |
| Efecty    |   10003   | Empty string                                 | `^$`             |               |
| Punto Red |   10006   | Customer's mobile phone and customer's email | `^[\s\S]{1,20}$` | 5715551234    |
| Transfiya |   10007   | Numeric                                      | `^\d{8,19}$`     | 1234567890123 |
| Others    |     -     | Numeric[^1]                                  | `^\d{8,19}$`     | 1234567890123 |

## Account Types

The `account_type` is specified with only one character as described below.

| `account_type` | Description       |
| :------------: | ----------------- |
|     **`C`**    | Checkings account |
|     **`S`**    | Savings account   |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Phone validations

| Bank name | Bank code | Format                                                              | Required | Example         |
| --------- | :-------: | ------------------------------------------------------------------- | :------: | --------------- |
| Efecty    |   10003   | <p>Numeric - Country code +57 plus 10 digits<br>+57 XXX XXXXXXX</p> |    Yes   | +57 310 4028587 |
| Transfiya |   10007   | <p>Numeric - Country code +57 plus 10 digits<br>+57 XXX XXXXXXX</p> |    Yes   | +57 310 4028587 |
| Punto Red |   10006   | <p>Numeric - Country code +57 plus 10 digits<br>+57 XXX XXXXXXX</p> |    Yes   | +57 310 4028587 |
| Others    |     -     | -                                                                   |    No    | -               |

## Example Request

{% tabs %}
{% tab title="Generic" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "login": "xxxxxxxx",
    "pass": "xxxxxxxx",
    "external_id": "30000000001",
    "country": "CO",
    "currency": "COP",
    "amount": 100,
    "document_id": "848392783",
    "document_type": "CC",
    "bank_account": "56687456",
    "bank_code": "001",
    "account_type": "C",
    "beneficiary_name": "User",
    "beneficiary_lastname": "Test",
    "address": "Calle 18, Colombia",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
</code></pre>

{% endtab %}

{% tab title="Efecty" %}

<pre class="language-json"><code class="lang-json">{
  "login": "xxxxxxxxx",
  "pass": "xxxxxxxxx",
  "external_id": "30000000002",
<strong>  "country": "CO",
</strong>  "currency": "COP",
  "amount": 100,
<strong>  "document_id": "24721498",
</strong>  "document_type": "CC",
  "cashout_type": "BANK",
  "bank_account": "",
  "bank_branch": "",
  "bank_code": 10003,
  "account_type": "S",
  "beneficiary_name": "User",
  "beneficiary_lastname": "Test",
  "address": "Calle 43"
  "email": "",
  "phone": "+57 310 4028587",
  "notification_url": "https://webhook.site/url",
}
</code></pre>

{% endtab %}

{% tab title="Transfiya " %}

<pre class="language-json"><code class="lang-json">{
  "login": "xxxxxxxxx",
  "pass": "xxxxxxxxx",
  "external_id": "30000000002",
<strong>  "country": "CO",
</strong>  "currency": "COP",
  "amount": 100,
<strong>  "document_id": "24721498",
</strong>  "document_type": "CC",
  "cashout_type": "BANK",
  "bank_account": "",
  "bank_branch": "",
  "bank_code": "10007",
  "account_type": "S",
  "beneficiary_name": "User",
  "beneficiary_lastname": "Test",
  "address": "Calle 43"
  "email": "",
  "phone": "+57 310 4028587",
  "notification_url": "https://webhook.site/url",
}
</code></pre>

{% endtab %}

{% tab title="Punto Red" %}

```json
{
  "login": "xxxxxxxxx",
  "pass": "xxxxxxxxx",
  "external_id": "30000000002",
  "country": "CO",
  "currency": "COP",
  "amount": 100,
  "document_id": "24721498",
  "document_type": "CC",
  "cashout_type": "BANK",
  "bank_account": "",
  "bank_branch": "",
  "bank_code": 10006,
  "account_type": "S",
  "beneficiary_name": "User",
  "beneficiary_lastname": "Test",
  "address": "Calle 43"
  "email": "useremail@gmail.com",
  "phone": "+57 310 4028587",
  "notification_url": "https://webhook.site/url",
}
```

{% endtab %}
{% endtabs %}

## Bank Codes

| Bank                                | Code  |
| ----------------------------------- | ----- |
| BANCO DE BOGOTÁ                     | 001   |
| BANCO POPULAR                       | 002   |
| ITAÚ - Antes CORPBANCA              | 006   |
| BANCOLOMBIA                         | 007   |
| CITIBANK                            | 009   |
| HSBC                                | 010   |
| BANCO SUDAMERIS                     | 012   |
| BBVA                                | 013   |
| ITAÚ (HELM)                         | 014   |
| BANCO COLPATRIA                     | 019   |
| BANCO DE OCCIDENTE                  | 023   |
| BANCOLDEX S.A.                      | 031   |
| BANCO CAJA SOCIAL BCSC              | 032   |
| BANCO AGRARIO                       | 040   |
| BANCO MUNDO MUJER                   | 047   |
| BANCO DAVIVIENDA                    | 051   |
| BANCO AV VILLAS                     | 052   |
| BANCO PROCREDIT                     | 058   |
| BANCAMIA S.A.                       | 059   |
| BANCO PICHINCHA                     | 060   |
| BANCOOMEVA                          | 061   |
| BANCO FALABELLA S.A                 | 062   |
| BANCO FINANDINA                     | 063   |
| BANCO SERFINANZA S.A.               | 069   |
| SANTANDER                           | 065   |
| LULO BANK S.A                       | 070   |
| J.P. MORGAN COLOMBIA                | 071   |
| COOPCENTRAL S.A.                    | 076   |
| Directa24                           | 100   |
| COOPERATIVA FINANCIERA DE ANTIOQUIA | 283   |
| COTRAFA COOPERATIVA FINANCIERA      | 289   |
| COOFINEP                            | 291   |
| CONFIAR                             | 292   |
| FINANCIERA JURISCOOP                | 296   |
| BANCO UNION                         | 303   |
| COLTEFINANCIERA                     | 370   |
| BANCO CREDIFINANCIERA S.A.          | 558   |
| IRIS                                | 637   |
| MOVII                               | 801   |
| RAPPIPAY                            | 811   |
| MIBANCO                             | 1067  |
| ASOPAGOSS                           | 1086  |
| JFK COOPERATIVA FINANCIERA          | 1286  |
| NEQUI                               | 1507  |
| DAVIPLATA                           | 1551  |
| BAN100 CREDIFINANCIERA              | 1558  |
| PIBANK                              | 1560  |
| DING TECNIPAGOS SA                  | 1802  |
| POWWI                               | 1803  |
| UALA                                | 1804  |
| BANCO BTG PACTUAL                   | 1805  |
| BOLD CF                             | 1808  |
| COINK                               | 1812  |
| GLOBAL66                            | 1814  |
| Efecty                              | 10003 |
| TPAGA Wallet                        | 10005 |
| PUNTO RED                           | 10006 |
| NUBANK                              | 809   |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}

[^1]: Numeric


# Ecuador

Check the requirements and validations made over the cashouts on Ecuador

## Required fields

| Field                  | Format                                                                                                                             | Description                                                              |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                             | Cashouts login                                                           |
| `pass`                 | String                                                                                                                             | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                           | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                        | Beneficiary's document ID                                                |
| `country`              | `EC`                                                                                                                               | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `USD`                                                                                                                              | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                       | Cashout amount                                                           |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/american-countries/ecuador#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/ecuador#bank-account-validations) | Beneficiary's bank account                                               |
| `account_type`         | See [account type codes](/api-documentation/cashouts-api/countries-validations/american-countries/ecuador#account-types)           | Beneficiary's bank account type                                          |
| `beneficiary_name`     | String (max length: 100)                                                                                                           | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                           | Beneficiary's last name                                                  |

## Bank Account Validations

| Bank name | Bank code | Format                                                    | Regex        | Example      |
| --------- | :-------: | --------------------------------------------------------- | ------------ | ------------ |
| All       |     -     | Numeric between 5 and 20 digits                           | `^\d{5,20}$` | 1234567890   |
| PayPhone  |   10007   | <p>593 (Ecuador Country code) + 9 digits<br>Cellphone</p> | `^\d{5,12}$` | 593985512345 |

## Account Types

The `account_type` is specified with only one character as described below.

| `account_type` | Description       |
| :------------: | ----------------- |
|     **`C`**    | Checkings account |
|     **`S`**    | Savings account   |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

{% tabs %}
{% tab title="Bank" %}

```json
{
    "login": "xxxxxxxx",
    "pass": "xxxxxxxx",
    "external_id": "30000000001",
    "country": "EC",
    "currency": "USD",
    "amount": 100,
    "document_id": "0809283023",
    "bank_account": "56687456387234",
    "bank_code": "001",
    "account_type": "C",
    "beneficiary_name": "John",
    "beneficiary_lastname": "Smith",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}

{% tab title="PayPhone" %}

```json
{
  "login": "xxxxxxxx",
  "pass": "xxxxxxxx",
  "country": "EC",
  "amount": 5,
  "currency": "USD",
  "external_id": "300000000001",
  "cashout_type": "BANK",
  "document_id": "***********",
  "beneficiary_name": "Test",
  "beneficiary_lastname": "Test",
  "email": "",
  "phone": "",
  "notification_url": "",
  "bank_code": 10007,
  "bank_branch": "",
  "bank_account": "593985512345",
  "account_type": "C",
  "document_type": "CC",
  "address": ""
}
```

{% endtab %}
{% endtabs %}

## Bank Codes

| Bank                                 | Code  |
| ------------------------------------ | ----- |
| Banco Central del Ecuador            | 001   |
| Banco Pichincha C.A.                 | 010   |
| Banco de Guayaquil S.A               | 017   |
| Banco City Bank                      | 024   |
| Banco Machala                        | 025   |
| Banco de Loja                        | 029   |
| Banco del Pacifico                   | 030   |
| Banco Internacional                  | 032   |
| Banco Amazonas                       | 034   |
| Banco del Austro                     | 035   |
| Produbanco / Promerica               | 036   |
| Banco Bolivariano                    | 037   |
| Comercial de Manabi                  | 039   |
| Banco General Ruminahui S.A.         | 042   |
| Banco del Litoral S.A.               | 043   |
| Banco Solidario                      | 059   |
| Banco Procredit S.A.                 | 060   |
| Banco Capital                        | 061   |
| Banco Desarrollo de Los Pueblos S.A. | 065   |
| Banecuador B.P.                      | 066   |
| Banco Delbank S.A.                   | 201   |
| PayPhone                             | 10007 |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Mexico

Check the requirements and validations made over the cashouts on Mexico

## Required fields

| Field                  | Format                                                                                                                            | Description                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `login`                | String                                                                                                                            | Cashouts login                                                                                  |
| `pass`                 | String                                                                                                                            | Cashouts pass                                                                                   |
| `external_id`          | String (max length: 100)                                                                                                          | Transaction's ID on your end                                                                    |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                       | Beneficiary's document ID                                                                       |
| `country`              | `MX`                                                                                                                              | See [country codes](/countries-specifications#countries-and-currencies)                         |
| `currency`             | `MXN` / `USD`                                                                                                                     | See [currency codes](/countries-specifications#countries-and-currencies)                        |
| `amount`               | Number with up to 2 decimals                                                                                                      | Cashout amount                                                                                  |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/american-countries/mexico#bank-codes)                      | Code specifying the beneficiary's bank. **Only mandatory if the bank\_account is a debit card** |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/mexico#bank-account-validations) | Beneficiary's bank account                                                                      |
| `beneficiary_name`     | String (max length: 100)                                                                                                          | Beneficiary's name                                                                              |
| `beneficiary_lastname` | String (max length: 100)                                                                                                          | Beneficiary's last name                                                                         |

## Bank Account Validations

| Bank name | Bank code | Format                                                                                                                                                                                                                                                                                                                 | Example            |
| --------- | :-------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| All       |     -     | [CLABE](https://en.wikipedia.org/wiki/CLABE): 18 digits long, applies verifier algorithm.                                                                                                                                                                                                                              | 021790064060296642 |
| All       |     -     | [DEBIT CARD](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint#cashouts-to-debit-cards): 15-16 digits long, applies verifier algorithm. Can only be sent through [the Cashout to Debit Cards Endpoint](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint#cashouts-to-debit-cards). | 5344867217683750   |
| Todito    |   10000   | 10 digits long.                                                                                                                                                                                                                                                                                                        | 2682883311         |
| Kiosko    |   10008   | Empty String                                                                                                                                                                                                                                                                                                           | -                  |

### CLABE validation algorithm

[Click here](https://en.wikipedia.org/wiki/CLABE) for more information about CLABE format.

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

{% tabs %}
{% tab title="Java" %}
{% code title="Mexico CLABE validation algorithm in Java" %}

```java
public final class Validations {
    static int CLABE_LENGTH = 18;
    
    private static boolean validateClabeLength(String bankAccount) {
        return bankAccount.length() == CLABE_LENGTH;
    }
    
    private static boolean validateClabe(String clabe) {
        if (!validateClabeLength(clabe)) {
            return false;
        } else {
            int sum = 0;
            String clabeWithoutCd = clabe.substring(0, 17);
            Integer[] array = new Integer[]{3, 7, 1};
    
            int checkDigitToVerify;
            for(checkDigitToVerify = 0; checkDigitToVerify < clabeWithoutCd.length(); ++checkDigitToVerify) {
                int digit = clabeWithoutCd.charAt(checkDigitToVerify);
                sum += digit * array[checkDigitToVerify % 3] % 10;
            }
    
            checkDigitToVerify = (10 - sum % 10) % 10;
            int checkDigit = Integer.parseInt(clabe.substring(17));
            return checkDigitToVerify == checkDigit;
        }
    }
}


```

{% endcode %}
{% endtab %}
{% endtabs %}

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxxx",
    "pass": "xxxxxxxx",
    "external_id": "30000000001",
    "country": "MX",
    "currency": "MXN",
    "amount": 100,
    "document_id": "848392783",
    "bank_account": "021790064060296642",
    "beneficiary_name": "User",
    "beneficiary_lastname": "Test",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank codes

{% hint style="info" %}
Notice that the bank\_code for Mexico is only mandatory if the bank\_account length is between 15 and 16 (Debit Card). In that case, [use the Credit Cards endpoint: https://cc-api-stg.directa24.com/v3/cashout](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint#cashouts-to-debit-cards)
{% endhint %}

| Bank                                | Code  |
| ----------------------------------- | ----- |
| BANAMEX                             | 002   |
| BANCOMEXT                           | 006   |
| BANOBRAS                            | 009   |
| BBVA BANCOMER                       | 012   |
| SANTANDER                           | 014   |
| BANJERCITO                          | 019   |
| HSBC                                | 021   |
| BAJIO                               | 030   |
| IXE                                 | 032   |
| INBURSA                             | 036   |
| INTERACCIONES                       | 037   |
| MIFEL                               | 042   |
| SCOTIABANK                          | 044   |
| BANREGIO                            | 058   |
| INVEX                               | 059   |
| BANSI                               | 060   |
| AFIRME                              | 062   |
| BANORTE                             | 072   |
| THE ROYAL BANK                      | 102   |
| AMERICAN EXPRESS                    | 103   |
| BAMSA                               | 106   |
| TOKYO                               | 108   |
| JP MORGAN                           | 110   |
| BMONEX                              | 112   |
| VE POR MAS                          | 113   |
| ING                                 | 116   |
| DEUTSCHE                            | 124   |
| CREDIT SUISSE                       | 126   |
| AZTECA                              | 127   |
| AUTOFIN                             | 128   |
| BARCLAYS                            | 129   |
| COMPARTAMOS                         | 130   |
| BANCO FAMSA                         | 131   |
| BMULTIVA                            | 132   |
| ACTINVER                            | 133   |
| WALMART                             | 134   |
| NAFIN                               | 135   |
| INTERBANCO                          | 136   |
| BANCOPPEL                           | 137   |
| ABC CAPITAL                         | 138   |
| UBS BANK                            | 139   |
| CONSUBANCO                          | 140   |
| VOLKSWAGEN                          | 141   |
| CIBANCO                             | 143   |
| BBASE                               | 145   |
| BANKAOOL                            | 147   |
| PAGATODO                            | 148   |
| INMOBILIARIO                        | 150   |
| DONDE                               | 151   |
| BANCREA                             | 152   |
| BANCO COVALTO                       | 154   |
| SABADELL                            | 156   |
| BANSEFI                             | 166   |
| HIPOTECARIA FEDERAL                 | 168   |
| MONEXCB                             | 600   |
| GBM                                 | 601   |
| MASARI                              | 602   |
| VALUE                               | 605   |
| ESTRUCTURADORES                     | 606   |
| TIBER                               | 607   |
| VECTOR                              | 608   |
| B\&B                                | 610   |
| MERRILL LYNCH                       | 615   |
| FINAMEX                             | 616   |
| VALMEX                              | 617   |
| UNICA                               | 618   |
| MAPFRE                              | 619   |
| PROFUTURO                           | 620   |
| CB ACTINVER                         | 621   |
| OACTIN                              | 622   |
| SKANDIA VIDA                        | 623   |
| CBDEUTSCHE                          | 626   |
| ZURICH                              | 627   |
| ZURICHVI                            | 628   |
| SU CASITA                           | 629   |
| CB INTERCAM                         | 630   |
| CI BOLSA                            | 631   |
| BULLTICK CB                         | 632   |
| STERLING                            | 633   |
| FINCOMUN                            | 634   |
| HDI SEGUROS                         | 636   |
| ORDER                               | 637   |
| NUBANK                              | 638   |
| CB JPMORGAN                         | 640   |
| REFORMA                             | 642   |
| STP                                 | 646   |
| TELECOMM                            | 647   |
| EVERCORE                            | 648   |
| SKANDIA OPERADORA                   | 649   |
| SEGMTY                              | 651   |
| ASEA                                | 652   |
| KUSPIT                              | 653   |
| SOFIEXPRESS                         | 655   |
| UNAGRA                              | 656   |
| OPCIONES EMPRESARIALES DEL NOROESTE | 659   |
| LIBERTAD                            | 670   |
| MERCADO PAGO W                      | 722   |
| CLS                                 | 901   |
| INDEVAL                             | 902   |
| Todito                              | 10000 |
| Kiosko                              | 10008 |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Peru

Check the requirements and validations made over the cashouts on Peru

## Required fields

| Field                  | Format                                                                                                                          | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                          | Cashouts login                                                           |
| `pass`                 | String                                                                                                                          | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                        | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                     | Beneficiary's document ID                                                |
| `document_type`        | See [document validations](/countries-specifications#documents-validations)                                                     | Beneficiary's document type                                              |
| `country`              | `PE`                                                                                                                            | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `PEN` / `USD`                                                                                                                   | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                    | Cashout amount                                                           |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/peru#bank-account-validations) | Beneficiary's bank account                                               |
| `account_type`         | See[ account types](/api-documentation/cashouts-api/countries-validations/american-countries/peru#account-types)                | Beneficiary's bank account type                                          |
| `beneficiary_name`     | String (max length: 100)                                                                                                        | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                        | Beneficiary's last name                                                  |

## Bank Account Validations

| Bank name | Bank code | Description                          | Format                                                                       | Example              |
| --------- | :-------: | ------------------------------------ | ---------------------------------------------------------------------------- | -------------------- |
| All       |     -     | CCI - Código de Cuenta Interbancaria | Length 20 (with verifying digits - a validation algorithm is ran over these) | 00219300153895206813 |

### CCI validation algorithm

Since the first three digits of the CCI are the bank code, it is not mandatory to send the `bank_code` field. However, we validate those 3 first digits to be a valid `bank_code`.

{% tabs %}
{% tab title="Java" %}
{% code title="Peru CCI validation algorithm in Java" %}

```java
public final class Validations {
   static Integer CCI_LENGTH_ST = 18;
   static Integer CCI_LENGTH_FST = 20;
   static String EMPTY_CHECK_DIGITS = "00";
    
   public static boolean validateBankAccount(String bankAccount) {
      if (!ValidationsUtils.validateOnlyNumbers(bankAccount)) {
         return false;
      } else {
         int accountLength = bankAccount.length();
         String lastDigits = bankAccount.substring(bankAccount.length() - 2);

         if (accountLength == CCI_LENGTH_ST && lastDigits.equals(EMPTY_CHECK_DIGITS)) {
            return true;
         }
         return validateCCI(bankAccount);
      }
   }

   //Validate CCI bank account
   public static boolean validateCCI(String cci) {
      if (validateCCILength(cci)) {
         String cciWithoutCheck = cci.substring(0, cci.length() - 2);
         String checkDigits = cci.substring(cci.length() - 2);
         String calculatedCheckDigits = getCciCheckDigits(cciWithoutCheck);

         return checkDigits.equals(calculatedCheckDigits);
      }
      return false;
   }

   public static boolean validateCCILength(String cci) {
      return cci.length() == CCI_LENGTH_FST;
   }

   public static String getCciCheckDigits(String cci) {
      int firstControlNumber = calculateCheckDigit(cci.substring(0, 6));
      int secondControlNumber = calculateCheckDigit(cci.substring(6, 18));

      return String.valueOf(firstControlNumber) + String.valueOf(secondControlNumber);
   }

   private static int calculateCheckDigit(String cci) {
      int total = 0;
      int factor = 1;

      for (int i = 0; i < cci.length(); i++) {
         String[] cciArray = cci.split("");
         int num = Integer.parseInt(cciArray[i]);

         if (num * factor < 10) {
            total += (num * factor);
         } else {
            int product = (num * factor);
            String product_str = Integer.toString(product);
            int firstDigit = Integer.parseInt(product_str.substring(0, 1));
            int lastDigit = product % 10;
            total += firstDigit + lastDigit;
         }

         factor = factor == 1 ? 2 : 1;
      }
      return (total % 10) > 0 ? 10 - (total % 10) : 0;
   }

}


```

{% endcode %}
{% endtab %}
{% endtabs %}

## Account Types

The `account_type` is specified with only one character as described below.

| `account_type` | Description       |
| :------------: | ----------------- |
|     **`C`**    | Checkings account |
|     **`S`**    | Savings account   |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "country": "PE",
    "currency": "PEN",
    "amount": 100,
    "document_id": "848392783",
    "document_type": "CE",
    "bank_account": "00219300153895206813",
    "account_type": "C",
    "beneficiary_name": "User",
    "beneficiary_lastname": "Test",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

| Bank                                         | Code |
| -------------------------------------------- | ---- |
| Banco de Crédito del Peru                    | 002  |
| Interbank                                    | 003  |
| Citibank                                     | 007  |
| Scotiabank                                   | 009  |
| BBVA Continental                             | 011  |
| Banco de la Nación                           | 018  |
| Banco de Comercio                            | 023  |
| Banco Financiero                             | 035  |
| Banco Interamericano de Finanzas (BIF)       | 038  |
| Crediscotia Financiera                       | 043  |
| Mi Banco                                     | 049  |
| Banco GNB Peru S.A                           | 053  |
| Banco Falabella                              | 054  |
| Santander                                    | 056  |
| Caja Metropolitana de Lima                   | 800  |
| Caja Municipal de Ahorro y Credito Piura SAC | 801  |
| Caja Municipal de Ahorro y Crédito Trujillo  | 802  |
| Caja Municipal de Ahorro y Crédito Arequipa  | 803  |
| Caja Municipal de Ahorro y Crédito Sullana   | 805  |
| Caja Municipal de Ahorro y Crédito Cuzco     | 806  |
| Caja Municipal de Ahorro y Crédito Huancayo  | 808  |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Paraguay

Check the requirements and validations made over the cashouts on Paraguay

## Required fields

<table data-header-hidden><thead><tr><th>Field</th><th>Format</th><th width="249.33333333333331">Description</th></tr></thead><tbody><tr><td>Field</td><td>Format</td><td>Description</td></tr><tr><td><code>login</code></td><td>String</td><td>Cashouts login</td></tr><tr><td><code>pass</code></td><td>String</td><td>Cashouts pass</td></tr><tr><td><code>external_id</code></td><td>String (max length: 100)</td><td>Transaction's ID on your end</td></tr><tr><td><code>document_type</code></td><td>See <a href="/countries-specifications#documents-validations">document validations</a></td><td>Beneficiary's document type.</td></tr><tr><td><code>document_id</code></td><td>See <a href="/countries-specifications#documents-validations">document validations</a></td><td>Beneficiary's document ID.</td></tr><tr><td><code>country</code></td><td><code>PY</code></td><td>See <a href="/countries-specifications#countries-and-currencies">country codes</a></td></tr><tr><td><code>currency</code></td><td>USD / PYG</td><td>See <a href="/countries-specifications#countries-and-currencies">currency codes</a></td></tr><tr><td><code>amount</code></td><td>Number with up to 2 decimals</td><td>Cashout amount</td></tr><tr><td><code>bank_code</code></td><td>See <a href="#bank-codes">bank codes</a></td><td>Code specifying the beneficiary's bank</td></tr><tr><td><code>bank_account</code></td><td>See <a href="#bank-account-validations">validations below</a></td><td>Beneficiary's bank account</td></tr><tr><td><code>account_type</code></td><td>See <a href="#account-types">account type codes</a></td><td>Beneficiary's bank account type</td></tr><tr><td><code>beneficiary_name</code></td><td>String (max length: 100)</td><td>Beneficiary's name</td></tr></tbody></table>

## Bank Account Validations

| Type    | Format                   |
| ------- | ------------------------ |
| Numeric | Between 3 and 20 digits. |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{noformat}{
"login": "xxxxxxx",
"pass": "xxxxxxx",
"external_id": "30000000001",
"country": "PY",
"currency": "PYG",
"amount": 100,
"document_type": "PASS",
"document_id": "1225255",
"beneficiary_name": "User",
"bank_account": "1234567890",
"bank_code": "1",
"notification_url": "https://webhook.site/url",
"type": "json"
}{noformat}
```

## Bank Codes

| BANCO CENTRAL DEL PARAGUAY       | 001  |
| -------------------------------- | ---- |
| BANCO NACIONAL DE FOMENTO        | 002  |
| BANCO DE LA NACION ARGENTINA     | 003  |
| BANCO GNB PARAGUAY               | 4    |
| BANCO DO BRASIL                  | 6    |
| SUDAMERIS BANK                   | 8    |
| BANCO ITAU PARAGUAY              | 17   |
| BANCO CONTINENTAL                | 20   |
| BANCO BASA (ex Amambay)          | 30   |
| VISION BANCO                     | 39   |
| BANCO RIO (Ex - Itapua)          | 40   |
| BANCO FAMILIAR                   | 41   |
| BANCO ATLAS                      | 42   |
| BANCOP                           | 43   |
| INTERFISA BANCO                  | 44   |
| FINANCIERA UENO                  | 6557 |
| CRISOL Y ENCARNACION FINANCIERA  | 6558 |
| FINLATINA S.A. DE FINANZAS       | 6559 |
| FINANCIERA PARAGUAYO-JAPONESA    | 6560 |
| FINANCIERA EXPORTADORA PARAGUAYA | 6561 |
| TU FINANCIERA                    | 6565 |
| FIC S.A. DE FINANZAS             | 7079 |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# African Countries

Learn about the cashouts validations of the African countries

{% content-ref url="/pages/-MD6yt16f4LmnEwUJmhY" %}
[Kenya](/api-documentation/cashouts-api/countries-validations/african-countries/kenya)
{% endcontent-ref %}

{% content-ref url="/pages/-MD6yspLjImjDFiGGRH5" %}
[Nigeria](/api-documentation/cashouts-api/countries-validations/african-countries/nigeria)
{% endcontent-ref %}

{% content-ref url="/pages/ggQkqlKfq4SncVYcjrW9" %}
[Ghana](/api-documentation/cashouts-api/countries-validations/african-countries/ghana)
{% endcontent-ref %}


# Kenya

Check the requirements and validations made over the cashouts on Kenya

## Required fields

| Field                  | Format                                                                                                                          | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                          | Cashouts login                                                           |
| `pass`                 | String                                                                                                                          | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                        | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                     | Beneficiary's document ID                                                |
| `country`              | `KE`                                                                                                                            | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `KES` / `USD`                                                                                                                   | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                    | Cashout amount                                                           |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/african-countries/kenya#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/african-countries/kenya#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `beneficiary_name`     | String (max length: 100)                                                                                                        | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                        | Beneficiary's last name                                                  |
| `phone`                | String (max length: 20 characters - up to 15 digits)                                                                            | Beneficiary Phone number                                                 |

## Bank Account Validations

| Bank name |                                                  Bank code                                                 | Format  | Example               |
| --------- | :--------------------------------------------------------------------------------------------------------: | ------- | --------------------- |
| All       | See [Bank Codes](/api-documentation/cashouts-api/countries-validations/african-countries/kenya#bank-codes) | Numeric | 123456789, 9283749293 |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

{% tabs %}
{% tab title="Mobile Money" %}

| Bank         | Bank Code | Details                                                                          |
| ------------ | --------- | -------------------------------------------------------------------------------- |
| Mobile Money | `10001`   | `bank_account`  must be empty.  The field `document_id` and `phone` must be sent |

```json
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "country": "KE",
    "amount": 100,
    "currency": "KES",
    "bank_account": "",
    "bank_code": "10001",
    "phone": "813462324",
    "document_id": "89237423",
    "beneficiary_name": "User",
    "beneficiary_lastname": "Test",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}
{% endtabs %}

## Bank Codes

| Bank                             | Code  |
| -------------------------------- | ----- |
| Kenya Commercial Bank KCB        | 001   |
| Standard Chartered Bank Kenya    | 002   |
| Absa Bank Kenya                  | 003   |
| Bank Of Baroda                   | 006   |
| Commercial Bank of Africa CBA    | 007   |
| Central Bank of Kenya            | 009   |
| Prime Bank Kenya                 | 010   |
| National Bank of Kenya           | 012   |
| M Oriental Bank Kenya            | 014   |
| Citi Bank Kenya                  | 016   |
| Habib Bank AG Zurich Kenya       | 017   |
| Middle East Bank Kenya           | 018   |
| Bank of Africa Kenya             | 019   |
| Consolidated Bank of Kenya       | 023   |
| Credit Bank Kenya                | 025   |
| Chase Bank Kenya                 | 030   |
| CFC Stanbic Bank Kenya           | 031   |
| NIC Bank Kenya                   | 041   |
| Bank Of India Kenya              | 042   |
| Ecobank Kenya                    | 043   |
| Paramount Universal Bank Kenya   | 050   |
| Jamii Bora Bank                  | 051   |
| Guaranty Trust GT Bank Kenya     | 053   |
| Victoria Commercial Bank Kenya   | 054   |
| Guardian Bank Kenya              | 055   |
| Development Bank of Kenya        | 059   |
| Housing Finance Company of Kenya | 061   |
| Diamond Trust Bank DTB Kenya     | 063   |
| Equity Bank Kenya                | 068   |
| Family Bank Kenya                | 070   |
| Gulf African Bank Kenya          | 072   |
| First Community Bank Kenya       | 074   |
| Mobile Money                     | 10001 |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Nigeria

Check the requirements and validations made over the cashouts on Nigeria

## Required fields

| Field                  | Format                                                                                                                            | Description                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                            | Cashouts login                                                           |
| `pass`                 | String                                                                                                                            | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                          | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                       | Beneficiary's document ID                                                |
| `country`              | `NG`                                                                                                                              | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `NGN` / `USD`                                                                                                                     | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                      | Cashout amount                                                           |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/african-countries/nigeria#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/african-countries/nigeria#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `beneficiary_name`     | String (max length: 100)                                                                                                          | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                          | Beneficiary's last name                                                  |

## Bank Account Validations

| Bank name | Bank code | Format  | Example               |
| --------- | :-------: | ------- | --------------------- |
| All       |     -     | Numeric | 123456789, 9283749293 |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "country": "NG",
    "amount": 100,
    "currency": "NGN",
    "bank_account": "123456789",
    "bank_code": "11", 
    "document_id": "892374233",
    "beneficiary_name": "User",
    "beneficiary_lastname": "Test",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

| Bank                       | Code |
| -------------------------- | ---- |
| First Bank of Nigeria Plc  | 016  |
| Heritage Bank              | 030  |
| Union Bank Nigeria Plc     | 032  |
| United Bank for Africa Plc | 033  |
| WEMA Bank Plc              | 035  |
| Access Bank Plc            | 044  |
| Ecobank Nigeria            | 050  |
| Zenith Bank International  | 057  |
| Guaranty Trust Bank Plc    | 058  |
| Fidelity Bank Plc          | 070  |
| Keystone Bank Ltd          | 082  |
| First City Monument Bank   | 214  |
| Unity Bank Plc             | 215  |
| Sterling Bank Plc          | 232  |
| Jaiz Bank                  | 301  |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# SOUTH AFRICA

Check the requirements and validations made over the cashouts on South Africa

## Required fields

| Field                  | Format                                                                                | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                | Cashouts login                                                           |
| `pass`                 | String                                                                                | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                              | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)           | Beneficiary's document ID                                                |
| `country`              | `ZA`                                                                                  | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `ZAR` / `USD`                                                                         | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                          | Cashout amount                                                           |
| `bank_account`         | See [validations below](broken://pages/-MCdJzGnzjFV3Ubq2WtV#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_code`            | See [bank codes](broken://pages/-MCdJzGnzjFV3Ubq2WtV#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `beneficiary_name`     | String (max length: 100)                                                              | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                              | Beneficiary's last name                                                  |

## Bank Account Validations

| Bank name | Bank code | Format  | Example                 |
| --------- | :-------: | ------- | ----------------------- |
| All       |     -     | Numeric | 1234567890, 92837492933 |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "40000000001",
    "country": "ZA",
    "amount": 500,
    "currency": "ZAR",
    "bank_account": "62102458345",
    "bank_code": "250655", 
    "document_id": "9308060142345",
    "beneficiary_name": "John",
    "beneficiary_lastname": "Doe",
    "account_type": "S",
    "phone": +27681234567
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

| Bank                            | Code   |
| ------------------------------- | ------ |
| Absa Bank Limited, South Africa | 632005 |
| Access Bank South Africa        | 410506 |
| African Bank                    | 430000 |
| Albaraka Bank                   | 800000 |
| Bank Zero                       | 888000 |
| Bidvest Bank Limited            | 462005 |
| Capitec Bank Limited            | 470010 |
| Capitec Business                | 450105 |
| CitiBank                        | 350005 |
| Discovery Bank Limited          | 679000 |
| Finbond EPE                     | 591000 |
| First National Bank             | 250655 |
| Firstrand Bank Limited          | 201419 |
| Grindrod Bank                   | 584000 |
| HBZ Bank (Westville)            | 570226 |
| HSBC South Africa               | 587000 |
| Investec Bank Ltd               | 580105 |
| JP Morgan South Africa          | 432000 |
| NedBank (South Africa)          | 198765 |
| Olympus Mobile                  | 585001 |
| Rand Merchant Bank              | 261251 |
| RMB Private Bank                | 222026 |
| SASFIN Bank                     | 683000 |
| Société Générale South Africa   | 351005 |
| South African Bank of Athens    | 410105 |
| Standard Bank South Africa      | 051001 |
| Standard Chartered Bank         | 730020 |
| TymeBank                        | 678910 |
| Ubank Ltd                       | 431010 |
| VBS Mutual Bank                 | 588000 |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Ghana

Check the requirements and validations made over the cashouts on Ghana

## Required fields

| Field                  | Format                                                                                                                          | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                          | Cashouts login                                                           |
| `pass`                 | String                                                                                                                          | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                        | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                     | Beneficiary's document ID                                                |
| `country`              | `GHS`                                                                                                                           | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | String `GHS` / `USD`                                                                                                            | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                    | Cashout amount                                                           |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/african-countries/kenya#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/african-countries/kenya#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `beneficiary_name`     | String (max length: 100)                                                                                                        | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                        | Beneficiary's last name                                                  |
| `phone`                | String (max length: 100)                                                                                                        | Beneficiary's Phone number                                               |

***

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

***

## Example Request

{% tabs %}
{% tab title="Bank Transfer" %}

````json
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id":"30000000001",
    "country": "GH",
    "currency": "GHS",
    "amount": 1000,
    "document_id": "01716001340",
    "beneficiary_name": "User",
    "beneficiary_lastname": "Test",
    "bank_account": "123456789",
    "bank_branch": "1",
    "notification_url": "https://webhook.site/url",
    "type": "json"
```
}
````

{% endtab %}

{% tab title="Mobile Money" %}

| Bank         | Bank Code | Details                                                                           |
| ------------ | --------- | --------------------------------------------------------------------------------- |
| Mobile Money | `10001`   | `bank_account`  must be empty.   The field `document_id` and `phone` must be sent |

```json
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "country": "GH",
    "amount": 100,
    "currency": "GHS",
    "bank_account": "",
    "bank_code": "10001",
    "phone": "256700000000",
    "document_id": "89237423",
    "beneficiary_name": "User",
    "beneficiary_lastname": "Test",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}
{% endtabs %}

***

## Bank Code

| Bank                                          | Code     |
| --------------------------------------------- | -------- |
| CENTRAL SECURITIES DEPOSITORY LIMITED         | 014      |
| ECOBANK GHANA                                 | 017      |
| TAKORADI INTERNATIONAL COMPANY                | 049      |
| UNITED BANK FOR AFRICA LTD                    | 050      |
| MTN Ghana                                     | 10000    |
| First National Bank Ghana Limited             | 11276282 |
| Omnibank Ghana Limited                        | 11299458 |
| GHL Bank Ltd                                  | 11319374 |
| Consolidated Bank Ghana Limited"              | 11350352 |
| Agricultural Development Bank Limited         | 20313200 |
| Bank of Ghana                                 | 20313400 |
| Barclays Bank of Ghana Limited                | 20313500 |
| GCB Bank Limited                              | 20313600 |
| Universal Merchant Bank                       | 20313800 |
| National Investment Bank Ltd                  | 20313900 |
| Societe Generale Ghana Limited                | 20314100 |
| Standard Chartered Bank Ghana Limited         | 20314200 |
| Cal Bank Limited                              | 22031960 |
| Arb Apex Bank Limited                         | 25544088 |
| Guaranty Trust Bank (Ghana) Ltd               | 25562284 |
| Fidelity Bank Ghana Ltd                       | 25570554 |
| Bsic Ghana Ltd                                | 25785380 |
| Bank of Baroda (Ghana) Limited                | 25892776 |
| Access Bank (Ghana) PLC                       | 26153374 |
| Social Security And National Insurance Trust  | 26545578 |
| Energy Bank Ghana Limited                     | 26675842 |
| Ghana Revenue Authority                       | 26699422 |
| Controller And Accountant-GeneralS Department | 26935088 |
| Premium Bank Ghana Limited                    | 27451510 |
| Prudential Bank Ltd                           | 60003190 |
| First Atlantic Bank Ltd                       | 60003191 |
| FBN Bank (Ghana) Limited                      | 60003193 |
| Ghana International Bank plc                  | 96788653 |
| Republic Bank (Ghana) Ltd                     | 96793657 |
| Stanbic Bank Ghana Limited                    | 97151844 |
| Bank of Africa - Ghana                        | 97155860 |
| Zenith Bank (Ghana) Limited                   | 98357706 |
| Mobile Money                                  | 10001    |


# Asian Countries

Learn about the cashouts validations of the Asian countries

{% content-ref url="/pages/-MD70wsOav-zReUGlOsm" %}
[India](/api-documentation/cashouts-api/countries-validations/asian-countries/india)
{% endcontent-ref %}

{% content-ref url="/pages/-MD78N9p4\_uAvNqbVMeD" %}
[Indonesia](/api-documentation/cashouts-api/countries-validations/asian-countries/indonesia)
{% endcontent-ref %}

{% content-ref url="/pages/-MVrmyj40HT8ybYwkDRi" %}
[Japan](/api-documentation/cashouts-api/countries-validations/asian-countries/japan)
{% endcontent-ref %}

{% content-ref url="/pages/-MD78NFXnQKELpB78535" %}
[Malaysia](/api-documentation/cashouts-api/countries-validations/asian-countries/malaysia)
{% endcontent-ref %}

{% content-ref url="/pages/-MD78NP6fQcPaXStfYKh" %}
[Philippines](/api-documentation/cashouts-api/countries-validations/asian-countries/philippines)
{% endcontent-ref %}

{% content-ref url="/pages/-MD78TlVNdXMQeMtuE6L" %}
[Thailand](/api-documentation/cashouts-api/countries-validations/asian-countries/thailand)
{% endcontent-ref %}

{% content-ref url="/pages/-MD78Memr7OP2LzaCIMc" %}
[Vietnam](/api-documentation/cashouts-api/countries-validations/asian-countries/vietnam)
{% endcontent-ref %}


# India

Check the requirements and validations made over the cashouts on India

## Required fields

<table data-header-hidden><thead><tr><th width="262.3333333333333">Field</th><th>Format</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Format</td><td>Description</td></tr><tr><td><code>login</code></td><td>String</td><td>Cashouts login</td></tr><tr><td><code>pass</code></td><td>String</td><td>Cashouts pass</td></tr><tr><td><code>external_id</code></td><td>String (max length: 100)</td><td>Transaction's ID on your end</td></tr><tr><td><code>document_id</code></td><td>See <a href="/countries-specifications#documents-validations">document validations</a></td><td>Beneficiary's document ID</td></tr><tr><td><code>country</code></td><td><code>IN</code></td><td>See <a href="/countries-specifications#countries-and-currencies">country codes</a></td></tr><tr><td><code>currency</code></td><td><code>INR</code> / <code>USD</code></td><td>See <a href="/countries-specifications#countries-and-currencies">currency codes</a></td></tr><tr><td><code>amount</code></td><td>Number with up to 2 decimals</td><td>Cashout amount</td></tr><tr><td><code>bank_account</code></td><td>See <a href="/api-documentation/cashouts-api/countries-validations/asian-countries/india#bank-account-validations">validations below</a></td><td>Beneficiary's bank account</td></tr><tr><td><code>bank_branch</code></td><td>See <a href="/api-documentation/cashouts-api/countries-validations/asian-countries/india#bank-branch-validations">validations below</a></td><td>Beneficiary's <a href="https://economictimes.indiatimes.com/wealth/ifsc-bank-code">IFSC</a></td></tr><tr><td><code>beneficiary_name</code></td><td>String (max length: 100)</td><td>Beneficiary's name</td></tr></tbody></table>

## Bank Account Validations

| Bank name | Bank code | Format                                                                            | Regex             | Example                     |
| --------- | :-------: | --------------------------------------------------------------------------------- | ----------------- | --------------------------- |
| Default   |     -     | Numeric values, not allowing spaces in between. Length between 9 and 18 inclusive | `^[0-9-.]{9,18}$` | 911010341747600, 9283749293 |

## Bank Branch Validations

The IFSC is short for Indian Financial System Code and this 11 characters code helps identify the individual bank branches that participate in the various online money transfer options like NEFT and RTGS. For more information and how to find a IFSC, please [click here.](https://economictimes.indiatimes.com/wealth/ifsc-bank-code)

| Bank | Description | Regex                              | Example                  |
| ---- | ----------- | ---------------------------------- | ------------------------ |
| All  | IFSC        | `^[A-Z\|a-z]{4}[0][a-zA-Z0-9]{6}$` | IDIB000M322, ANDB0000345 |

{% hint style="info" %}
**Note: We do not process Payouts to the following Banks/IFSC;**\
\- UCO Bank\
\- Paytm Payment Bank
{% endhint %}

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "document_id": "873839473",
    "beneficiary_name": "pruebaq",
    "country": "IN",
    "amount": 100,
    "currency": "INR",
    "bank_account": "234234323",
    "bank_branch": "IDIB000M322",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

{% hint style="warning" %}
The `bank_code` in India is not mandatory, and it is retrieved from the IFSC sent in the `bank_branch` instead.
{% endhint %}

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Indonesia

Check the requirements and validations made over the cashouts on Indonesia

## Required fields

| Field                  | Format                                                                                                                            | Description                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                            | Cashouts login                                                           |
| `pass`                 | String                                                                                                                            | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                          | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                       | Beneficiary's document ID                                                |
| `country`              | `ID`                                                                                                                              | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `IDR` / `USD`                                                                                                                     | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                      | Cashout amount                                                           |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/asian-countries/indonesia#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/asian-countries/indonesia#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `beneficiary_name`     | String (max length: 100)                                                                                                          | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                          | Beneficiary's last name                                                  |

## Bank Account Validations

| Bank name | Bank code | Format  | Example               |
| --------- | :-------: | ------- | --------------------- |
| All       |     -     | Numeric | 123456789, 9283749293 |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "document_id": "873839473",
    "beneficiary_name": "pruebaq",
    "beneficiary_lastname": "prueba",
    "country": "ID",
    "amount": 10,
    "currency": "IDR",
    "bank_code": "57",
    "bank_account": "16800026081",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

| Bank         | Code |
| ------------ | ---- |
| Bank Mandiri | 057  |
| KlikBCA      | 377  |
| CIMB Niaga   | 659  |
| BRI Bank     | 856  |
| BNI Bank     | 857  |
| Bank Permata | 890  |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Japan

Check the requirements and validations made over the cashouts on Japan

## Required fields

| Field                  | Format                                                                                                                        | Description                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                        | Cashouts login                                                           |
| `pass`                 | String                                                                                                                        | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                      | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                   | Beneficiary's document ID                                                |
| `country`              | `JP`                                                                                                                          | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `JPY` / `USD`                                                                                                                 | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                  | Cashout amount                                                           |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/asian-countries/japan#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_branch`          | See [validations below](/api-documentation/cashouts-api/countries-validations/asian-countries/japan#bank-branch-validations)  | Beneficiary's bank branch                                                |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/asian-countries/japan#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `account_type`         | See [account type codes](/api-documentation/cashouts-api/countries-validations/asian-countries/japan#account-types)           | Beneficiary's bank account type                                          |
| `beneficiary_name`     | String (max length: 100)                                                                                                      | Beneficiary's name in Katakana/Japanese Katakana                         |
| `beneficiary_lastname` | String (max length: 100)                                                                                                      | Beneficiary's last name in Katakana/Japanese Katakana                    |
| `email`                | String (max length: 100)                                                                                                      | User's email                                                             |

{% hint style="warning" %}
The name and last name (`beneficiary_name`, `beneficiary_lastname)` must respect the following rules:

* It should be **written** in Katakana, not Kanji, Hiragana, or English.
* It should be **typed** in Zenkaku.
* The small letters, such as 「ヤ」「ユ」「ヨ」should be written in capital (big) letter.
* When asking for the name and last name to the customer, use the phrase: "Bank Account Name"

{% endhint %}

Instructions in Japanese:

<figure><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/bcxTqtCvnSoZa27n2pZH/Screenshot%202024-04-04%20at%2010.59.29.png" alt=""><figcaption></figcaption></figure>

## Bank Account Validations

| Bank name | Bank code | Format  | Description                                                   | Regex       | Example |
| --------- | :-------: | ------- | ------------------------------------------------------------- | ----------- | ------- |
| TigerPay  |   10001   | Numeric | Numeric bank account. Length 6                                | `^\d{6}$`   |         |
| Others    |     -     | Numeric | Numeric bank account. Length between 6 and 8 digits inclusive | `^\d{6,8}$` | 3374856 |

## Bank Branch Validations

| Bank name | Bank code | Format  | Description                                    | Example |
| --------- | :-------: | ------- | ---------------------------------------------- | ------- |
| TigerPay  |   10001   | Empty   | Empty bank branch "                            | "       |
| Others    |     -     | Numeric | Bank branch number. Max. length: 3 characters. | 123     |

## Account Types

The `account_type` is specified with only one character as described below.

| `account_type` | Description             |
| :------------: | ----------------------- |
|     **`C`**    | Current account ("当座")  |
|     **`S`**    | Savings account ("貯蓄")  |
|     **`O`**    | Ordinary account ("普通") |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

{% tabs %}
{% tab title="Bank Account" %}

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "document_id": "873839473123",
    "country": "JP",
    "amount": 100,
    "currency": "JPY",
    "bank_code": "149",
    "bank_account": "2837493",
    "bank_branch": "123", 
    "account_type": "S",
    "beneificiary_name": "聡",
    "beneificiary_lastname": "中本",
    "email": "user@gmail.com",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}

{% tab title="TigerPay" %}

```
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "document_id": "873839473123",
    "country": "JP",
    "amount": 100,
    "currency": "JPY",
    "bank_code": "10001",
    "bank_account": "123456",
    "bank_branch": "", 
    "account_type": "S",
    "beneificiary_name": "聡", 
    "beneificiary_lastname": "中本",  
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}
{% endtabs %}

## Bank Codes

| Bank Name in Japanese | Bank Name in Latin Characters                         | Code  |
| --------------------- | ----------------------------------------------------- | ----- |
| ミズホ ギンコウ              | Mizuho Bank, Ltd.                                     | 001   |
| ミツビシユーエフジェイ ギンコウ      | MUFG Bank, Ltd.                                       | 005   |
| ミツイスミトモ　ギンコウ          | Sumitomo Mitsui Banking Corporation                   | 009   |
| リソナ ギンコウ              | Resona Bank, Limited                                  | 010   |
| サイタマリソナ ギンコウ          | Saitama Resona Bank, Limited                          | 017   |
| ペイペイ ギンコウ             | PayPay Bank                                           | 033   |
| セブン ギンコウ              | Seven Bank, Ltd.                                      | 034   |
| ソニー ギンコウ              | Sony Bank Inc.                                        | 035   |
| ラクテン ギンコウ             | Rakuten Bank, Ltd.                                    | 036   |
| スミシンエスビーアイ ギンコウ       | SBI Sumishin Net Bank, Ltd.                           | 038   |
| エーユージブン ギンコウ          | au Jibun Bank Corporation                             | 039   |
| イオン　ギンコウ              | AEON Bank, Ltd.                                       | 040   |
| トウホウギンコウ              | Toho Bank, Ltd                                        | 126   |
| ムサシノ ギンコウ             | The Musashino Bank, Ltd.                              | 133   |
| チバ ギンコウ               | The Chiba Bank, Ltd.                                  | 134   |
| ヨコハマ ギンコウ             | The Bank of Yokohama,Ltd.                             | 138   |
| 八十二銀行　ハチジユウニ          | Hachijuni banks                                       | 143   |
| ホクリク ギンコウ             | The Hokujriku Bank, Ltd.                              | 144   |
| シズオカ ギンコウ             | The Shizuoka Bank, Ltd.                               | 149   |
| スルガ ギンコウ              | Suruga Bank Ltd.                                      | 150   |
| 大垣共立銀行 オオガキキヨウリツ      | Oogaki Kyoritsu Bank                                  | 152   |
| 十六銀行                  | JIYUUROKU BANK                                        | 153   |
| キョウト ギンコウ             | The Bank of Kyoto, Ltd.                               | 158   |
| カンサイミライ ギンコウ          | Kansai Mirai Bank, Limited                            | 159   |
| イケダ センシュウギンコウ         | The Senshu Ikeda Bank, Ltd                            | 161   |
| 山陰合同銀行 サンインゴウドウ       | San-In Godo Bank                                      | 167   |
| ヒロシマ ギンコウ             | Hiroshima Bank, Ltd                                   | 169   |
| 阿波銀行                  | Awa Bank                                              | 172   |
| 伊予銀行 イヨ               | Iyo Bank                                              | 174   |
| フクオカ ギンコウ             | The Bank Of Fukuoka, Ltd.                             | 177   |
| 十八親和銀行 ジユウハチシンワ       | The Juhachi Shinwa Bank                               | 181   |
| 琉球銀行　リユウキユウ           | Bank of Ryukyu                                        | 187   |
| 三井住友信託銀行 ミツイスミトモシンタク  | SMBC Trust Bank                                       | 300   |
| ジーエムオーアオゾラネット ギンコウ    | GMO Aozora Net Bank, Ltd.                             | 310   |
| シンセイ ギンコウ             | Shinsei Bank, Ltd.                                    | 397   |
| 香港上海銀行 ホンコンシヤンハイ      | The Hongkong and Shanghai Banking Corporation Limited | 411   |
| 東京スター銀行 トウキヨウスター      | Tokyo Star Bank                                       | 526   |
| 長野銀行 ナガノ              | Nagano Bank                                           | 533   |
| ナゴヤギンコウ               | The Bank of Nagoya, Ltd.                              | 543   |
| ユウチョ ギンコウ             | Japan Post Bank (Yucho Bank)                          | 9900  |
| TigerPay              | TigerPay                                              | 10001 |
| みんなの銀行                | Minnano Bank                                          | 043   |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Malaysia

Check the requirements and validations made over the cashouts on Malaysia

## Required fields

| Field                  | Format                                                                                                                           | Description                                                              |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                           | Cashouts login                                                           |
| `pass`                 | String                                                                                                                           | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                         | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                      | Beneficiary's document ID                                                |
| `country`              | `MY`                                                                                                                             | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `MYR` / `USD`                                                                                                                    | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                     | Cashout amount                                                           |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/asian-countries/malaysia#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/asian-countries/malaysia#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `beneficiary_name`     | String (max length: 100)                                                                                                         | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                         | Beneficiary's last name                                                  |

## Bank Account Validations

| Bank name | Bank code | Format  | Example               |
| --------- | :-------: | ------- | --------------------- |
| All       |     -     | Numeric | 123456789, 9283749293 |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "document_id": "873839473",
    "beneficiary_name": "pruebaq",
    "beneficiary_lastname": "prueba",
    "country": "MY",
    "amount": 100,
    "currency": "MYR",
    "bank_code": "1",
    "bank_account": "16800026081",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

| Bank                    | Code |
| ----------------------- | ---- |
| CIMB Bank               | 001  |
| UOB Bank                | 008  |
| OCBC Bank               | 162  |
| Affin Bank              | 183  |
| Bank Simpanan National  | 229  |
| CITI bank               | 242  |
| Maybank                 | 268  |
| AM Bank                 | 312  |
| Standard Chartered Bank | 356  |
| Alliance Bank           | 421  |
| Bank Islam Malaysia     | 555  |
| Public Bank             | 634  |
| RHB Bank                | 785  |
| HSBC Bank               | 955  |
| Hong Leong Bank         | 961  |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Philippines

Check the requirements and validations made over the cashouts on Philippines

## Required fields

| Field                  | Format                                                                                                                              | Description                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                              | Cashouts login                                                           |
| `pass`                 | String                                                                                                                              | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                            | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                         | Beneficiary's document ID                                                |
| `country`              | `PH`                                                                                                                                | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `PHP` / `USD`                                                                                                                       | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                        | Cashout amount                                                           |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/asian-countries/philippines#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/asian-countries/philippines#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `beneficiary_name`     | String (max length: 100)                                                                                                            | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                            | Beneficiary's last name                                                  |

## Bank Account Validations

| Bank name                                          | Bank code | Format                   | Regex                |
| -------------------------------------------------- | :-------: | ------------------------ | -------------------- |
| BPI Family Bank                                    |     1     | Numeric. Length 10       | `^\d{10}$`           |
| Cebuana Lhuillier Cash Pick-up                     |     2     | Phone number             | `^\d{11}$`           |
| Gcash                                              |     3     | Phone number             | `^\d{11}$`           |
| LBC Cash Pick-up                                   |     4     | Phone number             | `^\d{11}$`           |
| Security Bank CA/SA                                |     8     | Numeric. Length 13       | `^\d{13}$`           |
| PNB individual CA/SA                               |     10    | Numeric. Length 12 or 16 | `^(\d{12}\|\d{16})$` |
| Chinabank CA/SA                                    |     13    | Numeric. Length 10 or 12 | `^(\d{10}\|\d{12})$` |
| RCBC CA/SA, RCBC Savings Bank CA/SA, RCBC MyWallet |     14    | Numeric. Length 10 or 16 | `^(\d{10}\|\d{16})$` |
| Robinsons Bank CA/SA                               |     15    | Numeric. Length 12 or 15 | `^(\d{12}\|\d{15})$` |
| BPI CA/SA                                          |     18    | Numeric. Length 10       | `^\d{10}$`           |
| Landbank CA/SA                                     |     25    | Numeric. Length 10       | `^\d{10}$`           |
| PayMaya ewallet                                    |    216    | Phone number             | `^(\d{11}\|\d{12})$` |
| Banco de Oro CA/SA                                 |    667    | Numeric. Length 10 or 12 | `^(\d{10}\|\d{12})$` |
| Metrobank CA/SA                                    |    996    | Numeric. Length 13       | `^\d{13}$`           |
| Others                                             |     -     | Numeric. Length 12       | `^\d{12}$`           |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "document_id": "873839473",
    "beneficiary_name": "Test",
    "beneficiary_lastname": "User",
    "country": "PH",
    "amount": 100,
    "currency": "PHP",
    "bank_code": "1",
    "bank_account": "8273909483",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

| Bank                                               | Code |
| -------------------------------------------------- | ---- |
| BPI Family Bank                                    | 001  |
| Cebuana Lhuillier Cash Pick-up                     | 002  |
| Gcash                                              | 003  |
| LBC Cash Pick-up                                   | 004  |
| Security Bank CA/SA                                | 008  |
| UCPB CA/SA                                         | 009  |
| PNB individual CA/SA                               | 010  |
| Asia United Bank CA/SA                             | 011  |
| Chinabank Savings                                  | 012  |
| Chinabank CA/SA                                    | 013  |
| RCBC CA/SA, RCBC Savings Bank CA/SA, RCBC MyWallet | 014  |
| Robinsons Bank CA/SA                               | 015  |
| Philippine Savings Bank                            | 016  |
| BPI CA/SA                                          | 018  |
| Landbank CA/SA                                     | 025  |
| Bank of Commerce                                   | 210  |
| Sterling Bank of Asia                              | 211  |
| PayMaya ewallet                                    | 216  |
| Maybank                                            | 226  |
| Unionbank CA/SA, EON                               | 295  |
| Philippine Bank of Communications                  | 416  |
| EastWest CA/SA                                     | 614  |
| Banco de Oro CA/SA                                 | 667  |
| Chinatrust                                         | 915  |
| Metrobank CA/SA                                    | 996  |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Thailand

Check the requirements and validations made over the cashouts on Thailand

## Required fields

| Field                  | Format                                                                                                                           | Description                                                              |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                           | Cashouts login                                                           |
| `pass`                 | String                                                                                                                           | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                         | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                      | Beneficiary's document ID                                                |
| `country`              | `TH`                                                                                                                             | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `THB` / `USD`                                                                                                                    | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                     | Cashout amount                                                           |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/asian-countries/thailand#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/asian-countries/thailand#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `beneficiary_name`     | String (max length: 100)                                                                                                         | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                         | Beneficiary's last name                                                  |

## Bank Account Validations

| Bank name | Bank code | Format  | Example               |
| --------- | :-------: | ------- | --------------------- |
| All       |     -     | Numeric | 123456789, 9283749293 |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "document_id": "873839473",
    "beneficiary_name": "pruebaq",
    "beneficiary_lastname": "prueba",
    "country": "TH",
    "amount": 100,
    "currency": "THB",
    "bank_code": "21",
    "bank_account": "16800026081",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

| Bank                            | Code |
| ------------------------------- | ---- |
| Bank of Ayudhya                 | 021  |
| CIMB Thai                       | 093  |
| Kiatnakin Bank                  | 168  |
| KTB Net Bank (Krunthai Bank)    | 215  |
| KasiKorn Bank                   | 278  |
| Bangkok Bank                    | 427  |
| Government Savings Bank         | 485  |
| Siam Commercial Bank            | 734  |
| TMB Bank Public Company Limited | 823  |
| United Oversees Bank            | 429  |
| Standard Chartered Bank         | 419  |
| Land And Houses Retail Bank PLC | 416  |
| Government Housing Bank         | 410  |
| HSBC                            | 423  |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# China

Check the requirements and validations made over the cashouts in China

## Required Fields

| Field                  | Format                                                                                                  | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                  | Cashouts login                                                           |
| `pass`                 | String                                                                                                  | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                             | Beneficiary's document ID                                                |
| `country`              | `CN`                                                                                                    | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `CNY` / `USD`                                                                                           | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                            | Cashout amount                                                           |
| `bank_account`         | -                                                                                                       | Beneficiary's bank account                                               |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/asian-countries/china#bank-code) | Code specifying the beneficiary's bank                                   |
| `beneficiary_name`     | String (max length: 100)                                                                                | Beneficiary's name in Chinese (中文)                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                | Beneficiary's last name in Chinese (中文)                                  |
| `email`                | String (max length: 100)                                                                                | User's email                                                             |
| `Phone`                | Numeric                                                                                                 | Beneficiary Valid Phone Number                                           |

## Bank Account Validations

<table data-header-hidden><thead><tr><th>Bank name</th><th align="center">Bank code</th><th width="187">Format</th><th>Description</th><th>Regex</th><th>Example</th></tr></thead><tbody><tr><td>Bank name</td><td align="center">Bank code</td><td>Format</td><td>Description</td><td>Regex</td><td>Example</td></tr><tr><td>Others</td><td align="center">-</td><td>Numeric</td><td>Numeric bank account. Length between 3 and 20 digits inclusive</td><td><code>^\d{3,20}$</code></td><td>3374856</td></tr></tbody></table>

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.<br>

## Example Request

```json
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "document_id": "873839473123",
    "country": "CN",
    "amount": 100,
    "currency": "USD",
    "bank_code": "149",
    "bank_account": "2837493",
    "bank_branch": "", 
    "beneificiary_name": "名",
    "beneificiary_lastname": "姓",
    "email": "user@email.com",
    "Phone": "+86 1212345678",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Code

| Bank Name in Japanese | Bank Name in Latin Characters             | Code |
| --------------------- | ----------------------------------------- | ---- |
| 人民银行                  | People s Bank of China                    | 1    |
| 工商银行                  | Industrial and Commercial Bank            | 102  |
| 农业银行                  | Agricultural Bank of China                | 103  |
| 中国银行                  | Bank of China                             | 104  |
| 建设银行                  | China Construction Bank                   | 105  |
|                       | China Development Bank                    | 201  |
| 进出口银行                 | Export-Import Bank of China               | 202  |
| 农业发展银行                | Agricultural Development of China         | 203  |
|                       | Guandong Development Bank                 | 234  |
| 交通银行                  | Bank of Communications                    | 301  |
| 中信银行                  | China CITIC Bank                          | 302  |
| 光大银行                  | China Everbright Bank                     | 303  |
|                       | Huaxia Bank                               | 304  |
| 民生银行                  | China Minsheng Bank                       | 305  |
|                       | Guangdong Development Bank                | 306  |
|                       | Shenzhen Development Bank                 | 307  |
| 招商银行                  | China Merchants Bank                      | 308  |
| 兴业银行                  | China s Industrial Bank                   | 309  |
| 浦发银行                  | Shanghai Pudong Development Bank          | 310  |
|                       | Dongguan Commercial Bank                  | 311  |
| 恒丰银行                  | Evergrowing Bank                          | 315  |
|                       | China Zheshang Bank                       | 316  |
| 渤海银行                  | Bohai Bank                                | 318  |
| 徽商银行                  | Huishang Bank                             | 319  |
| 邮储银行                  | Postal Savings Bank of China              | 403  |
|                       | Hongkong and Shanghai Banking Corporation | 501  |
| 东亚银行                  | Bank of East Asia                         | 502  |
|                       | Nanyang Commercial Bank                   | 503  |
|                       | Hang Seng Bank                            | 504  |
| 中国银行                  | Bank of China (Hongkong) Ltd              | 505  |
|                       | Chiyu Banking Corporation Limited         | 506  |
|                       | Chong Hing Bank                           | 507  |
|                       | DBS Bank (China)                          | 509  |
|                       | Wing Hang Bank                            | 510  |
|                       | Wing Lung Bank                            | 512  |
|                       | Citibank                                  | 531  |
|                       | Bank of America                           | 532  |
|                       | J.P. Morgan Chase                         | 533  |
|                       | Bank of Tokyo-Mitsubishi UFJ              | 561  |
|                       | Sumitomo Mitsui Banking Corporation       | 563  |
|                       | Mizuho Corporate Bank                     | 564  |
|                       | Japan Pass Bank                           | 565  |
|                       | Korea Exchange Bank                       | 591  |
|                       | Woori Bank                                | 593  |
|                       | Korea Development Bank                    | 594  |
|                       | ShinHan Bank                              | 595  |
|                       | Industrial Bank of Korea                  | 596  |
|                       | Hana Bank                                 | 597  |
|                       | Overseas Chinese Banking Corporation      | 621  |
|                       | United Overseas Bank                      | 622  |
|                       | HuaXia Bank                               | 623  |
|                       | Bangkok Bank                              | 631  |
|                       | Raiffeisen Zentralbank                    | 641  |
|                       | KBC Group                                 | 651  |
|                       | Fortis Bank                               | 652  |
|                       | ABN AMRO Bank                             | 661  |
|                       | ING Bank                                  | 662  |
|                       | Standard Chartered Bank                   | 671  |
|                       | The Royal Bank of Scotland                | 672  |
|                       | Societe Generate                          | 691  |
|                       | Banque Indosuez                           | 694  |
|                       | Natixis                                   | 695  |
|                       | Dresdner Bank AG                          | 711  |
|                       | Deutsche Bank                             | 712  |
|                       | Commerzbank                               | 713  |
|                       | Westdeutsche Landesbank                   | 714  |
|                       | Bayerische Landesbank AG                  | 715  |
|                       | Norddeutsche Landesbank                   | 716  |
|                       | Intesa Sanpaolo                           | 731  |
|                       | Credit Suisse                             | 741  |
|                       | Swiss Bank Corp                           | 742  |
|                       | Bank of Nova Scotia                       | 751  |
|                       | Bank of Montreal                          | 752  |
|                       | Australian and New Zealand Bank           | 761  |
|                       | Morgan Stanley International Bank         | 771  |
|                       | Rabobank                                  | 776  |
|                       | Xiamen International Bank                 | 781  |
|                       | BNP Paribas                               | 782  |
|                       | Chinese Mercantile Bank                   | 785  |
|                       | First Sino Bank                           | 787  |
|                       | Bank of Dongguan                          | 800  |
|                       | Bank of Shanghai                          | 838  |
|                       | Bank of Guangzhou                         | 861  |
| 平安银行                  | pingan bank                               | 903  |
| 广发银行                  | china guangfa bank                        | 904  |
| 北京银行                  | Bank Of Beijing                           | 905  |
|                       | HangZhou Of Bank                          | 926  |


# Vietnam

Check the requirements and validations made over the cashouts on Vietnam

## Required fields

| Field                  | Format                                                                                                                          | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `login`                | String                                                                                                                          | Cashouts login                                                           |
| `pass`                 | String                                                                                                                          | Cashouts pass                                                            |
| `external_id`          | String (max length: 100)                                                                                                        | Transaction's ID on your end                                             |
| `document_id`          | See [document validations](/countries-specifications#documents-validations)                                                     | Beneficiary's document ID                                                |
| `country`              | `VN`                                                                                                                            | See [country codes](/countries-specifications#countries-and-currencies)  |
| `currency`             | `VND` / `USD`                                                                                                                   | See [currency codes](/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                    | Cashout amount                                                           |
| `bank_account`         | See [validations below](/api-documentation/cashouts-api/countries-validations/asian-countries/vietnam#bank-account-validations) | Beneficiary's bank account                                               |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/countries-validations/asian-countries/vietnam#bank-codes)                      | Code specifying the beneficiary's bank                                   |
| `beneficiary_name`     | String (max length: 100)                                                                                                        | Beneficiary's name                                                       |
| `beneficiary_lastname` | String (max length: 100)                                                                                                        | Beneficiary's last name                                                  |

## Bank Account Validations

| Bank name | Bank code | Format  | Example               |
| --------- | :-------: | ------- | --------------------- |
| All       |     -     | Numeric | 123456789, 9283749293 |

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "document_id": "873839473",
    "beneficiary_name": "pruebaq",
    "beneficiary_lastname": "prueba",
    "country": "VN",
    "amount": 100,
    "currency": "VND",
    "bank_code": "400",
    "bank_account": "16800026081",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

| Bank                                           | Code |
| ---------------------------------------------- | ---- |
| SAIGON Bank                                    | 400  |
| Bank for Investment and Development of Vietnam | 401  |
| Sacom Bank                                     | 403  |
| Agribank                                       | 405  |
| DongA Joint Stock Commercial Bank              | 406  |
| Techcom Bank                                   | 407  |
| VietinBank                                     | 415  |
| Asia Commercial Bank                           | 416  |
| Eximbank Vietnam                               | 431  |
| Vietcom Bank                                   | 436  |
| Vietnam International Bank                     | 441  |

{% hint style="info" %}
For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes)
{% endhint %}


# Bangladesh

Check the requirements and validations made over the cashouts on Bangladesh

### Required Fields

<table data-header-hidden><thead><tr><th width="262.3333333333333">Field</th><th width="240">Format</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Format</td><td>Description</td></tr><tr><td><code>login</code></td><td>String</td><td>Cashout login</td></tr><tr><td><code>pass</code></td><td>String</td><td>Cashout pass</td></tr><tr><td><code>external_id</code></td><td>String (max length: 100)</td><td>Transaction's ID on your end</td></tr><tr><td><code>document_id</code></td><td>See <a href="/countries-specifications#documents-validations">document validations</a></td><td>Beneficiary's document ID</td></tr><tr><td><code>country</code></td><td><code>BD</code></td><td>See <a href="/countries-specifications#countries-and-currencies">country codes</a></td></tr><tr><td><code>currency</code></td><td><code>BDT</code> / <code>USD</code></td><td>See <a href="/countries-specifications#countries-and-currencies">currency codes</a></td></tr><tr><td><code>amount</code></td><td>Number with up to 2 decimals</td><td>Cashout amount</td></tr><tr><td><code>bank_account</code></td><td>See <a href="/api-documentation/cashouts-api/countries-validations/asian-countries/india#bank-account-validations">validations below</a></td><td>Beneficiary's bank account</td></tr><tr><td><code>beneficiary_name</code></td><td>String (max length: 100)</td><td>Beneficiary's name</td></tr><tr><td><code>beneficiary_lastname</code></td><td>String (max length: 100)</td><td>Beneficiary's Last name</td></tr><tr><td><code>Email</code></td><td>String (max length: 100)</td><td>User's email</td></tr></tbody></table>

### Bank Account validation

<table data-header-hidden><thead><tr><th width="133">Bank name</th><th width="105" align="center">Bank code</th><th width="101">Format</th><th width="142">Description</th><th width="119">Regex</th><th>Example</th></tr></thead><tbody><tr><td>Bank name</td><td align="center">Bank code</td><td>Format</td><td>Description</td><td>Regex</td><td>Example</td></tr><tr><td>All</td><td align="center">-</td><td>Numeric</td><td>Numeric bank account. Length between 3 and 20 digits inclusive</td><td><code>^\d{3,20}$</code></td><td><pre><code>01234567891
</code></pre></td></tr></tbody></table>

## Document Validations

[Click here](/countries-specifications#documents-validations) to check document types and validations.<br>

## Example Request

```json
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "document_id": "8738394731",
    "country": "BD",
    "amount": 1000,
    "currency": "BDT",
    "bank_code": "1",
    "bank_account": "01234567891", 
    "account_type": "S",
    "beneificiary_name": "Test Name",
    "beneificiary_lastname": "Last Name",
    "email": "user@email.com",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

### Account type

The `account_type` is specified with only one character as described below.

| `account_type` | Description     |
| :------------: | --------------- |
|     **`C`**    | Current account |
|     **`S`**    | Savings account |

### Bank Code

| Bank   | Code |
| ------ | ---- |
| BKash  | 001  |
| Nagad  | 002  |
| Upay   | 003  |
| Rocket | 004  |


# Oceania Countries

Learn about the cashouts validations of the Asian countries


# Australia

Check the requirements and validations made over the cashouts in Australia

### Required Fields <a href="#required-fields" id="required-fields"></a>

<table><thead><tr><th width="229">Field</th><th>Format</th><th>Description</th></tr></thead><tbody><tr><td><code>country</code></td><td><code>AUS</code></td><td>See <a href="https://docs.d24.com/knowledge-base/countries-specifications#countries-and-currencies">country codes</a></td></tr><tr><td><code>currency</code></td><td><code>AUS</code> / <code>USD</code></td><td>See <a href="https://docs.d24.com/knowledge-base/countries-specifications#countries-and-currencies">currency codes</a></td></tr><tr><td><code>amount</code></td><td>Number with up to 2 decimals</td><td>Cashout amount</td></tr><tr><td><code>document_id</code></td><td>Beneficiary's document ID</td><td>Beneficiary's document ID</td></tr><tr><td><code>bank_account</code></td><td>-</td><td>Beneficiary's bank account</td></tr><tr><td><code>bank_branch</code></td><td>BSB</td><td>In this field we <em>must</em> receive Beneficiary's <strong>BSB</strong> number. </td></tr><tr><td><code>beneficiary_name</code></td><td>String (max length: 100)</td><td>Beneficiary's name</td></tr><tr><td><code>benefitiary_lastname</code></td><td>String (max length: 100)</td><td>Beneficiary's last name</td></tr><tr><td><code>phone</code></td><td>String (max lenght: 10). </td><td>Beneficiary's phone number</td></tr><tr><td><code>email</code></td><td>String (max length: 255)</td><td>Beneficiary's email</td></tr></tbody></table>

### Additional Fields <a href="#required-fields" id="required-fields"></a>

<table><thead><tr><th width="229">Field</th><th>Format</th><th>Description</th></tr></thead><tbody><tr><td><code>document_id</code></td><td></td><td></td></tr><tr><td><code>account_type</code></td><td><code>AUS</code> / <code>USD</code></td><td>See <a href="https://docs.d24.com/knowledge-base/countries-specifications#countries-and-currencies">currency codes</a></td></tr></tbody></table>

### Example Request

<pre class="language-json"><code class="lang-json">{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
<strong>    "country": "AU",
</strong>    "amount": 100,
    "currency": "AUD",
    "external_id": "70000000001",
    "document_type": "ID", 
    "document_id": "123456789",
    "beneficiary_name": "Test",
    "beneficiary_lastname": "TestLastName",
    "email": "test@testemail.com";
    "bank_branch": "484799", 
    "bank_code": "22",
    "bank_account": "123439923",
    "account_type": "S", 
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
</code></pre>


# Argentina

Check the requirements and validations made over the cashouts on Argentina

### Required fields <a href="#required-fields" id="required-fields"></a>

| Field                  | Format                                                                                                                                                   | Description                                                                                                 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `login`                | String                                                                                                                                                   | Cashouts login                                                                                              |
| `pass`                 | String                                                                                                                                                   | Cashouts pass                                                                                               |
| `external_id`          | String (max length: 100)                                                                                                                                 | Transaction's ID on your end                                                                                |
| `document_id`          | See [document validations](https://docs.d24.com/knowledge-base/countries-specifications#documents-validations)                                           | Beneficiary's document ID                                                                                   |
| `country`              | `AR`                                                                                                                                                     | See [country codes](https://docs.d24.com/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | ARS/USD                                                                                                                                                  | See [currency codes](https://docs.d24.com/knowledge-base/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                                                                                             | Cashout amount                                                                                              |
| `bank_code`            | [Valid](https://docs.d24.com/api-documentation/cashouts-api/countries-validations/american-countries/argentina#bank-codes) bank code                     | Code specifying the beneficiary's bank                                                                      |
| `bank_account`         | [Valid](https://docs.d24.com/api-documentation/cashouts-api/countries-validations/american-countries/argentina#bank-account-validations) bank account    | Beneficiary's bank account                                                                                  |
| `bank_branch`          | [Valid](https://docs.d24.com/api-documentation/cashouts-api/countries-validations/american-countries/argentina#bank-branch-validations) institute number | Beneficiary's institute number                                                                              |
| `email`                | [Valid](https://docs.d24.com/knowledge-base/countries-specifications#emails-validations) email address                                                   | Beneficiary's email address                                                                                 |
| `beneficiary_name`     | String (max length: 100)                                                                                                                                 | Beneficiary's name                                                                                          |
| `beneficiary_lastname` | String (max length: 100)                                                                                                                                 | Beneficiary's last name                                                                                     |

### Bank Account Validations <a href="#bank-account-validations" id="bank-account-validations"></a>

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

| Bank name | Bank Description                                                                       | Format             |
| --------- | -------------------------------------------------------------------------------------- | ------------------ |
| All       | CBU - [Clave Bancaria Uniforme](https://es.wikipedia.org/wiki/Clave_Bancaria_Uniforme) | Numeric, Length 22 |

<figure><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/7k5w0jEo9WVnld9lxwma/image.png" alt=""><figcaption><p>CBU - Bank accounts format</p></figcaption></figure>

### CBU Validation Algorithm <a href="#email-validations" id="email-validations"></a>

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

```java
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 <a href="#document-validations" id="document-validations"></a>

[Click here](https://docs.d24.com/knowledge-base/countries-specifications#documents-validations) to check document types and validations.

### Example Request <a href="#example-request" id="example-request"></a>

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

{% hint style="info" %}
Notice that the bank code is not mandatory for Argentina as it's part of the bank account.
{% endhint %}

### Bank Codes <a href="#bank-codes" id="bank-codes"></a>

| Bank Name                                      | Code |
| ---------------------------------------------- | ---- |
| A.B.N Amro Bank                                | 005  |
| Banco de Galicia Y Buenos Aires                | 007  |
| Lloyds Tsb Bank                                | 010  |
| Banco de La Nación Argentina                   | 011  |
| Banco de La Provincia de Buenos Aires          | 014  |
| Industrial and Commercial Bank of China (ICBC) | 015  |
| Citibank                                       | 016  |
| BBVA Banco Frances                             | 017  |
| The Bank Of Tokyo - Mitsubishi                 | 018  |
| Banco de La Provincia de Cordoba               | 020  |
| Superville Bank                                | 027  |
| Banco de La Ciudad de Buenos Aires             | 029  |
| Banco Patagonia Sudameris                      | 034  |
| Banco Hipotecario                              | 044  |
| Banco de San Juan                              | 045  |
| Banco Do Brasil                                | 046  |
| Banco Del Tucuman                              | 060  |
| Banco Municipal de Rosario                     | 065  |
| Santander Río                                  | 072  |
| Banco Regional de Cuyo                         | 079  |
| Banco Del Chubut                               | 083  |
| Banco de Santa Cruz                            | 086  |
| Banco de La Pampa                              | 093  |
| Banco de Corrientes                            | 094  |
| Banco Provincia Del Neuquen                    | 097  |
| Banco Empresario de Tucuman Coop.              | 137  |
| Banco B. I. Creditanstalt                      | 147  |
| HSBC Bank Argentina                            | 150  |
| J P Morgan Chase Bank Sucursal Buenos Aires    | 165  |
| Banco Credicoop Coop.                          | 191  |
| Banco de Valores                               | 198  |
| Banco Roela                                    | 247  |
| Banco Mariva                                   | 254  |
| Banco Itau Buen Ayre                           | 259  |
| Bank Of America                                | 262  |
| Banca Nazionale Del Lavoro                     | 265  |
| Bnp Paribas                                    | 266  |
| Banco Provincia de Tierra Del Fuego            | 268  |
| Banco de La República Oriental Del Uruguay     | 269  |
| Banco Saenz                                    | 277  |
| Banco Meridian                                 | 281  |
| Banco Macro Bansud                             | 285  |
| Banco Mercurio                                 | 293  |
| Ing Bank                                       | 294  |
| American Express Bank Ltd.                     | 295  |
| Banco Banex                                    | 297  |
| Banco Comafi                                   | 299  |
| Banco de Inversión Y Comercio Exterior         | 300  |
| Banco Piano                                    | 301  |
| Banco Finansur                                 | 303  |
| Banco Julio                                    | 305  |
| Banco Privado de Inversiones                   | 306  |
| Nuevo Banco de La Rioja                        | 309  |
| Banco Del Sol                                  | 310  |
| Nuevo Banco Del Chaco                          | 311  |
| M. B. A. Banco de Inversiones                  | 312  |
| Banco de Formosa                               | 315  |
| Banco CMF                                      | 319  |
| Banco de Santiago Del Estero                   | 321  |
| Nuevo Banco Industrial de Azul                 | 322  |
| Deutsche Bank                                  | 325  |
| Nuevo Banco de Santa Fe                        | 330  |
| Banco Cetelem Argentina                        | 331  |
| Banco de Servicios Financieros                 | 332  |
| Banco Cofidis                                  | 335  |
| Banco Bradesco Argentina                       | 336  |
| Banco de Servicios Y Transacciones             | 338  |
| Rci Ba                                         | 339  |
| Bacs Banco de Crédito Y Securitización         | 340  |
| Nuevo Banco de Entre Rios                      | 386  |
| Nuevo Banco Suquia                             | 387  |
| Nuevo Banco Bisel                              | 388  |
| Banco Columbia                                 | 389  |


# API Codes

Learn about the API Codes returned by our Cashouts APIs

## **Cashout Status Codes**

<table data-full-width="true"><thead><tr><th align="center">Code</th><th align="center">Meaning</th><th>Description</th></tr></thead><tbody><tr><td align="center">0</td><td align="center"><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/x84M1Rzu2mq1QN3W8B0e/Untitled%20Diagram.svg" alt="" data-size="original"> </td><td>The cashout was accepted by Zimopagos but it wasn't sent to the bank yet. It can still be Canceled. See <a href="/api-documentation/cashouts-api/endpoints/cashout-cancel-endpoint">Cancel Cashout</a></td></tr><tr><td align="center">1</td><td align="center"><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/mbgGsYgmNYZPCGhfCL3r/COMPLETED.svg" alt="" data-size="original"> </td><td>The money reached the customer's account</td></tr><tr><td align="center">2</td><td align="center"><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/broVfspC5o0HcXmuzVmk/CANCELLED.svg" alt="" data-size="original"> </td><td>The cashout was cancelled by you</td></tr><tr><td align="center">3</td><td align="center"><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/ATHFV1nSai3AKSWvpuzG/REJECTED.svg" alt="" data-size="original"> </td><td>The cashout was rejected <strong>by the bank</strong> due to invalid bank account, account closed, etc.</td></tr><tr><td align="center">4</td><td align="center"><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/yx733ZARwGqAKnMKdr5R/DELIVERED.svg" alt="" data-size="original"> </td><td>The cashout was sent to the bank for processing. At this point it can't be cancelled anymore</td></tr><tr><td align="center">5</td><td align="center"><img src="https://content.gitbook.com/content/z5mrYH1MHPfy4P3M66mx/blobs/Uv1PDSzXZCqFDX5S4c9A/image.png" alt=""></td><td>Cashout set to on hold by you. It won't be processed until manually changed again to Pending status</td></tr></tbody></table>

## **Cashout Rejection Error Codes**

&#x20;The error information is the one (if) provided by the Bank.

<table data-full-width="true"><thead><tr><th width="268">Code</th><th width="416.3333333333333">Name</th><th>Description</th></tr></thead><tbody><tr><td>800</td><td><code>ERROR_ACCOUNT_INCORRECT</code></td><td> Invalid bank account</td></tr><tr><td>801</td><td><code>ERROR_ACCOUNT_CLOSED</code></td><td>Bank account is closed</td></tr><tr><td>802</td><td><code>ERROR_AMOUNT_INCORRECT</code></td><td>Invalid amount</td></tr><tr><td>803</td><td><code>ERROR_BANK_INVALID</code></td><td>Invalid bank code</td></tr><tr><td>804</td><td><code>ERROR_BANK_BRANCH_INCORRECT</code></td><td>Invalid bank branch</td></tr><tr><td>805</td><td><code>ERROR_BENEFICIARY_DOCUMENT_ID_INVALID</code></td><td>Invalid beneficiary document</td></tr><tr><td>806</td><td><code>ERROR_BENEFICIARY_NAME_INCORRECT</code></td><td>Beneficiary name doesn't match bank details</td></tr><tr><td>807</td><td><code>ERROR_REJECTED_BY_BANK</code></td><td>Rejected by bank</td></tr><tr><td>808</td><td><code>ERROR_OTHER</code></td><td>Other error</td></tr><tr><td>809</td><td><code>WITHDRAWAL_EXPIRED</code></td><td>Withdrawal expired</td></tr><tr><td>810</td><td><code>LIMIT_EXCEEDED</code></td><td>Beneficiary limit exceeded</td></tr><tr><td>811</td><td><code>RISK_POLICY</code></td><td>Violates bank risk policy</td></tr><tr><td>812</td><td><code>BLOCKED_FROZEN_ACCOUNT</code></td><td>Bank account blocked/frozen</td></tr><tr><td>813</td><td><code>DOCUMENT_ACCOUNT_MISMATCH</code></td><td>Beneficiary document doesn't match bank details</td></tr><tr><td>814</td><td><code>INVALID_PIX_KEY</code></td><td>Invalid Pix Key</td></tr><tr><td>815</td><td><code>INVALID_IFSC_CODE</code></td><td>Invalid IFSC code</td></tr><tr><td>816</td><td><code>INVALID_ACCOUNT_OR_IFSC_CODE</code> </td><td>Invalid bank account or IFSC code</td></tr><tr><td>817</td><td><code>INVALID_NBIN</code></td><td>Invalid NBIN</td></tr><tr><td>818</td><td><code>ACCOUNT_UNABLE</code></td><td>The bank account is unable to receive transfers</td></tr><tr><td>819</td><td><code>INVALID_ACCOUNT_TYPE</code></td><td>Invalid bank account type</td></tr><tr><td>820</td><td><code>REJECTED_BY_MERCHANT_REQUEST</code></td><td>Rejected by  merchant's request</td></tr><tr><td>821</td><td><code>MONTHLY_LIMIT_EXCEEDED_FOR_USER</code></td><td>Monthly limit exceeded for user</td></tr><tr><td>822</td><td><code>ACCOUNT_NAME_REQUIRED_TO_BE_IN_KATAKANA</code></td><td>Account name required to be in Katakana</td></tr><tr><td>824</td><td><code>REJECTED_BY_THIRD_PARTY_CONTROL</code></td><td>Rejected by third party control</td></tr><tr><td>826</td><td><code>WITHDRAWAL_REVERSED</code></td><td>Withdrawal reversed</td></tr></tbody></table>

## **Cashout Internal Error Codes**

<table data-full-width="true"><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody><tr><td>300</td><td>Invalid params + [param name] + [reason]</td></tr><tr><td>302</td><td>Invalid control string. <a href="/api-documentation/cashouts-api/technical-and-security-aspects/calculating-the-payload-signature">Click here for instructions</a></td></tr><tr><td>303</td><td>Invalid bank code</td></tr><tr><td>401</td><td>Invalid credentials</td></tr><tr><td>402</td><td>Unregistered IP address (Go to API Access to whitelist the IP in the Merchant Panel)</td></tr><tr><td>502</td><td>Invalid request body  -  Please check that the JSON is well formatted</td></tr><tr><td>503</td><td>The transaction cannot be completed due to regulatory limits applied to the beneficiary account.</td></tr><tr><td>504</td><td>User unauthorized due to cadastral situation.</td></tr><tr><td>508</td><td>Limit exceeded: {TRANSACTION|DAILY|MONTHLY|USER MONTHLY QUANTITY}</td></tr><tr><td>509</td><td>Cashout not found with this ID</td></tr><tr><td>510</td><td>Invalid status: cashout is not Pending</td></tr><tr><td>511</td><td>External ID already used</td></tr><tr><td>514</td><td>Insufficient funds</td></tr><tr><td>515</td><td>Invalid user status: {BLACKLISTED|BLOCKED|SUSPENDED}</td></tr><tr><td>518</td><td>Country not available</td></tr><tr><td>519</td><td>Merchant not enabled. Contact your Account Manager</td></tr><tr><td>524</td><td>Invalid Credentials. Contact integration@eroninternational.com</td></tr><tr><td>525</td><td>Close loop rejection</td></tr><tr><td>526</td><td>Invalid currency</td></tr><tr><td>533</td><td>Invalid Amount. The minimum amount is {currency} {amount} or equivalent in USD</td></tr><tr><td>537</td><td>Could not make the cashout. Contact integration@eroninternational.com</td></tr><tr><td>538</td><td>Invalid account status: {BLACKLISTED}</td></tr><tr><td>539</td><td>Payout method unavailable. The country and/or bank selected is not available. Please check with your Account Manager</td></tr><tr><td>540</td><td>Beneficiary email or phone is required</td></tr><tr><td>541</td><td>email already used by another beneficiary</td></tr><tr><td>542</td><td>phone already used by another beneficiary</td></tr><tr><td>543</td><td>must be a<a href="/countries-specifications#phone-numbers-validations"> valid phone number</a></td></tr><tr><td>702</td><td>Could not cancel cashout</td></tr><tr><td>703</td><td>Could not make the cashout. Contact integration@eroninternational.com</td></tr></tbody></table>

### Fraud Reason Codes for KYC Errors&#x20;

<table data-full-width="true"><thead><tr><th width="179" align="center">Reason Code</th><th width="128" align="center">HTTP Code</th><th width="203" align="center">Type</th><th width="162">Message</th><th width="162">Description</th></tr></thead><tbody><tr><td align="center">101</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Transaction related to blacklisted user.</td><td>The transaction was rejected because one of its attributes was related to a blacklisted user</td></tr><tr><td align="center">102</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Email risk</td><td>High risk detected by our fraud prevention engine related to the user's email address</td></tr><tr><td align="center">103</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Credit card risk</td><td>High risk detected by our fraud prevention engine related to the credit card used</td></tr><tr><td align="center">104</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>User rejected after KYC check</td><td>User rejected by our KYC controls</td></tr><tr><td align="center">105</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Underage user detected</td><td>User does not meet the minimum age requirement</td></tr><tr><td align="center">106</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Mismatch between user name and document name</td><td>The user's name does not match the name associated with the document provided</td></tr><tr><td align="center">107</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Document status is not OK</td><td>Some irregularities have been detected while validating the document information</td></tr><tr><td align="center">108</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>PEP user detected</td><td>The user is a Politically Exposed Person (PEP)</td></tr><tr><td align="center">109</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>High risk detected</td><td>High risk detected by our fraud prevention engine</td></tr><tr><td align="center">110</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Failed biometric check</td><td>Something went wrong while performing the biometric check on the user</td></tr><tr><td align="center">111</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Failed OTP verification</td><td>Something went wrong while performing the OTP check on the user</td></tr><tr><td align="center">112</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>3DS Authentication failed</td><td>Transaction rejected due to failed 3DS</td></tr><tr><td align="center">113</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Document does not exist</td><td>Invalid Document</td></tr><tr><td align="center">114</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>User rejected after CNPJ validations</td><td>Invalid/Irregular CNPJ (Brasil Only)</td></tr><tr><td align="center">115</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Invalid document format</td><td>Format of the provided document is invalid. (Mexico Only)</td></tr><tr><td align="center">116</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Regulatory reasons</td><td>Rejected due to regulatory reasons</td></tr></tbody></table>

## **Cashout Status Rejection Error Codes**

The error information is the one (if) provided by the Bank.

<table data-full-width="true"><thead><tr><th>Code</th><th>Name</th><th>Description</th></tr></thead><tbody><tr><td>510</td><td><code>Invalid status transition</code></td><td>Status transition does not meet cashout status workflow</td></tr><tr><td>509</td><td><code>Cashout not found with this ID</code></td><td>There is no cashout under provided ID</td></tr><tr><td>521</td><td><code>Status ... not supported for this type of request</code></td><td>Provided Status does not exist</td></tr></tbody></table>


# Fragment (SDK)


# Overview

Learn the technical aspects about our Cards SDK, in order to have the ultimate native checkout experience.

### What is Cards SDK about?

Our SDK is designed to simplify the process of integrating payments into your application, allowing you to handle payments securely and efficiently without needing to meet strict PCI requirements. We offer two integration modes:

1. **With User Interface**: Ideal for quick and easy integration with a ready-to-use user interface, and very customizable.
2. **Without User Interface**: Perfect for those who need a more customized integration and full control over the payment process.

### Benefits of Using Our SDK

* **Easy to Integrate**: With straightforward instructions and code examples, you can have the payment system up and running in no time.
* **Secure**: Our system complies with the highest security standards, eliminating the need for your application to be PCI compliant.
* **Customizable**: We offer customization options to match the look and feel of your application.

### Select the SDK type that suits best for you!


# All-in-one

This document provides a detailed technical reference for all components, methods, and properties available in the D24 Credit Card SDK.

## SDK Constructor

The SDK is instantiated using a constructor that takes a public key and an options object.

```javascript
new SDK(publicKey, options)
```

#### Parameters <a href="#parameters" id="parameters"></a>

<br>

| `publicKey`           | `string`   | Your unique public key provided by D24.     | **true** |                  |
| --------------------- | ---------- | ------------------------------------------- | -------- | ---------------- |
| `options`             | `object[]` | An object containing configuration options. | **true** |                  |
| `options.environment` | `string`   | Specifies the operating environment.        | **true** | `stg`, `prod`    |
| `options.locale`      | `string`   | Sets the language for the UI components.    | **true** | `en`, `es`, `pt` |

#### Instantiation Errors

Attempting to instantiate or use the SDK incorrectly will result in one of the following errors:

| SDK was already instantiated.                                  | You are trying to call `new SDK(...)` more than once.                                                          |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| The environment \[config.environment] is not supported.        | The value for `options.environment` is not `'stg'` or `'prod'`.                                                |
| You must instantiate D24CreditCardSDK before using SDK methods | You attempted to use a component or method like `CreditCardForm` before the SDK was successfully instantiated. |

## &#x20;`<CreditCardForm />` Component

This is the primary UI component for collecting and processing credit card information.

#### Properties <a href="#properties" id="properties"></a>

| `authToken`              | `string`   | The unique `checkout_token` returned by your call to the Deposit Creation Endpoint.          | **true**  |
| ------------------------ | ---------- | -------------------------------------------------------------------------------------------- | --------- |
| `country`                | `string`   | The two-letter ISO 3166-1 alpha-2 country code.                                              | **true**  |
| `onSuccess`              | `function` | Callback function executed when the payment is successful.                                   | **true**  |
| `onError`                | `function` | Callback function executed when an error occurs during the payment.                          | **true**  |
| `onBack`                 | `function` | Callback function executed when the user clicks the "Go Back" button.                        | **true**  |
| `onTokenGenerationError` | `function` | Callback function executed when an internal error occurs while generating the payment token. | **true**  |
| `messages`               | `object[]` | An object for defining custom text on the payment completion screens.                        | **false** |

#### `messages` Object Structure

You can override the default text for the success and error screens by providing a `messages` object.

| `messages.paymentComplete.success.title`       | `string` | The title displayed on the success screen.            |
| ---------------------------------------------- | -------- | ----------------------------------------------------- |
| `messages.paymentComplete.success.description` | `string` | The description text displayed on the success screen. |
| `messages.paymentComplete.error.title`         | `string` | The title displayed on the error screen.              |
| `messages.paymentComplete.error.description`   | `string` | The description text displayed on the error screen.   |

### Callbacks <a href="#callbacks" id="callbacks"></a>

**`onTokenGenerationError`**

This callback function will be executed when an error occurs generating token.

```javascript
function handleTokenErrorCallback(error: string) {
	console.log(error);
}
```

**`onBack`**

This callback function will be executed when the user clicks on the Go Back button.

```javascript
function handleGoBackCallback() {
	console.log('Go back');
}
```


# Customize the UI

Elevate your user experience with our advanced color customization feature. We provide a bespoke version of the theme to perfectly match the unique style of your website's UI.\
To fine-tune the colors, simply add a `colorSchema[]` object as illustrated in the example.

{% hint style="success" %}
You don't need to send the entire object, you can include the sections you would like to change.
{% endhint %}

#### `colorSchema[]` object <a href="#colorschema-object" id="colorschema-object"></a>

```
const colorSchema = {
  //primary button is to complete the action like "Complete payment" and "Continue"
  "button": {
    "primary": {
      "background": {
        "default": "#3C5BFC",
        "hover": "#7087FF",
        "active": "#2E47C9"
      },
      "text": {
        "color": {
          "default": "#FFFFFF"
        }
      }
    },
    //this is the link button like "go back"
    "tertiary": {
      "text": {
        "color": {
          "default": "#3C5BFC"
        }
      }
    }
  },
  //This affect the inputs and select
  "input": {
    "background": {
      "default": "#FFFFFF",
      "locked": "#E6E7EB"
    },
    "border": {
      "color": {
        "default": "#373840",
        "locked": "#D5D6DE",
        "active": "#3C5BFC",
        "error": "#CF3434"
      }
    },
    "text": {
      "color": {
        "label": "#B0B3BF",
        "input": "#0B1130",
        "placeholderHint": "#B0B3BF"
      }
    }
  },
  //This affects the text that is not related to the inputs.
  "text": {
    "color": "#373840"
  },
  //This is the background color of the label on the input and select when add some value
  "label": {
    "background": "#FFFFFF"
  }
};
```

#### Visual references <a href="#visual-references" id="visual-references"></a>

In the images below you will find the visual references of the colorSchema parameters and color customization possibilities.

\
![](https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2Fh9gTaPFNYbOUGLtGksB8%2Fimage.png?alt=media\&token=e0d31a1a-d444-49c0-9228-f265ea3a4af1)![](https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2FSpM0DhuLg6ToOdwqlfns%2Fimage.png?alt=media\&token=d8ca2ce0-8d0b-4fe5-8c95-359e9b0dc00a)![](https://3250621082-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz5mrYH1MHPfy4P3M66mx%2Fuploads%2F1AIJMdhNGeknFDfwt1CM%2Fimage.png?alt=media\&token=f0394f15-2c0c-4fc3-8fe0-c19cb29f5ee0)


# Lite

## **Installation**

**NPM**

```bash
npm install @d24/sdk-minimal
```

**HTML Script Tag**

```html
<script type="module" src="https://d24sdk.s3.amazonaws.com/releases/d24-minimal-1.0.19.es.js"></script>
```

## **Constructor**

Initializes the SDK. This must be called before any other methods.

`new SDK(publicKey, options)`

**Parameters**

| `publicKey`           | `string` | Your public API key provided by D24. | Yes |                         |
| --------------------- | -------- | ------------------------------------ | --- | ----------------------- |
| `options`             | `object` | Configuration options for the SDK.   | Yes |                         |
| `options.environment` | `string` | The environment to use.              | Yes | `'stg'`, `'production'` |

### **Usage**

```javascript
// NPM/ESM
import SDK from '@d24/sdk-minimal';
new SDK('as1i2nxal12bvd', { environment: 'stg' });

// UMD/Script Tag
new window.D24.SDK('as1i2nxal12bvd', { environment: 'stg' });
```

#### **Errors**

| `SDK was already instantiate.`                    | The SDK constructor was called more than once.         |
| ------------------------------------------------- | ------------------------------------------------------ |
| `The environment [environment] is not supported.` | An invalid value was passed for `options.environment`. |


# Countries Specifications

Learn how to validate the country's specific details

## Countries and currencies

* The country codes are in **ISO 3166-1 alpha-2** format.&#x20;
* The currencies are in **ISO 4217** format.

| Country            | Country code&#xA;(ISO 3166-1 alpha-2 code) | Currency code &#xA;(ISO 4217) |
| ------------------ | :----------------------------------------: | :---------------------------: |
| Argentina          |                     AR                     |           USD / ARS           |
| Australia          |                     AU                     |           USD / AUS           |
| Brazil             |                     BR                     |           USD / BRL           |
| Bangladesh         |                     BD                     |            USD/BDT            |
| Bolivia            |                     BO                     |           USD / BOB           |
| Cameroon           |                     CM                     |           USD / XAF           |
| Canada             |                     CA                     |           USD / CAD           |
| Chile              |                     CL                     |           USD / CLP           |
| China              |                     CN                     |            USD/CNY            |
| Colombia           |                     CO                     |           USD / COP           |
| Costa Rica         |                     CR                     |           USD / CRC           |
| Côte d'Ivoire      |                     CI                     |           USD / XOF           |
| Dominican Republic |                     DO                     |           USD / DOP           |
| Ecuador            |                     EC                     |              USD              |
| El Salvador        |                     SV                     |           USD / SVC           |
| Ghana              |                     GH                     |           USD / GHS           |
| Guatemala          |                     GT                     |           USD / GTQ           |
| Honduras           |                     HN                     |           USD / HNL           |
| India              |                     IN                     |           USD / INR           |
| Indonesia          |                     ID                     |           USD / IDR           |
| Japan              |                     JP                     |           USD / JPY           |
| Kenya              |                     KE                     |           USD / KES           |
| Malaysia           |                     MY                     |           USD / MYR           |
| Mexico             |                     MX                     |           USD / MXN           |
| Nicaragua          |                     NI                     |           USD / NIO           |
| Nigeria            |                     NG                     |           USD / NGN           |
| Panama             |                     PA                     |              USD              |
| Peru               |                     PE                     |           USD / PEN           |
| Paraguay           |                     PY                     |           USD / PYG           |
| Philippines        |                     PH                     |           USD / PHP           |
| Singapore          |                     SG                     |           USD / SGD           |
| South Africa       |                     ZA                     |           USD / ZAR           |
| Tanzania           |                     TZ                     |           USD / TZS           |
| Thailand           |                     TH                     |           USD / THB           |
| Uganda             |                     UG                     |           USD / UGX           |
| Uruguay            |                     UY                     |           USD / UYU           |
| Venezuela          |                     VE                     |           USD / VES           |
| Vietnam            |                     VN                     |           USD / VND           |

## Documents validations

The `document` sent must follow the validations for its respective `document_type`  described below.

| Country            | Document type                                    | Validation                                                                                                                                                                 |
| ------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Argentina          | DNI                                              | Numeric. Length 7-9                                                                                                                                                        |
| Argentina          | CUIT / CUIL                                      | Numeric. Length between 7 and 9 inclusive or equal to 11                                                                                                                   |
| Bangladesh         | ID                                               | Numeric. Length: 10 digits                                                                                                                                                 |
| Bangladesh         | PASS                                             | <p>Length 9 digits,<br>Starting with 2 alphanumerical character (i.e: AB1234567)</p>                                                                                       |
| Bangladesh         | DL (Driving license)                             | <p>Length: 15,<br>Starting with 2 alphanumerical characters, followed by 7 numerical digits, 1 alphanumerical character and finally 5 numerical (i.e: AB1234567C12345)</p> |
| Brazil             | CPF                                              | Numeric. Length 11 (Validate verifier-digits)                                                                                                                              |
| Bolivia            | CI                                               | Numeric. Length: 7                                                                                                                                                         |
| Bolivia            | CIE                                              | Alphanumeric. One character followed by 8 digits                                                                                                                           |
| Bolivia            | PASS                                             | Alphanumeric. One character followed by 6 digits                                                                                                                           |
| Bolivia            | NIT                                              | Numeric. Length:12                                                                                                                                                         |
| Cameroon           | PASS                                             | Numeric. Length between 9 and 11 inclusive                                                                                                                                 |
| Cameroon           | CI                                               | Numeric. Length between 8 and 12 inclusive                                                                                                                                 |
| Cameroon           | DL (Driving License)                             | Numeric. Length between 8 and 10 inclusive                                                                                                                                 |
| Canada             | DL (Driving License)                             | Numeric and length between 6 and 9 inclusive or string between 10 and 15 inclusive                                                                                         |
| Canada             | HC (Health Card)                                 | Numeric. Length 10                                                                                                                                                         |
| Canada             | PASS (Passport)                                  | Length between 8 and 12 inclusive                                                                                                                                          |
| Chile              | ID / RUN / RUT                                   | Length 8 or 9                                                                                                                                                              |
| China              | ID                                               | Numeric. Length between 3 and 20 inclusive                                                                                                                                 |
| Colombia           | CC                                               | Numeric. Length between 6 and 10 inclusive                                                                                                                                 |
| Colombia           | NIT                                              | Numeric. Length between 8 and 15                                                                                                                                           |
| Colombia           | CE                                               | Numeric. Length between 6 and 10 inclusive.                                                                                                                                |
| Colombia           | PASS                                             | Length between 6 and 10 inclusive                                                                                                                                          |
| Colombia           | PPT                                              | Length between 6 and 10 inclusive                                                                                                                                          |
| Costa Rica         | CI                                               | Length: 9                                                                                                                                                                  |
| Côte d'Ivoire      | ID                                               | Length between 8 and 12 inclusive                                                                                                                                          |
| Dominican Republic | CIE                                              | Numeric. Length 11                                                                                                                                                         |
| Ecuador            | CC                                               | Numeric. Length between 9 and 10 inclusive                                                                                                                                 |
| Ecuador            | DL                                               | Numeric. Length 10                                                                                                                                                         |
| Ecuador            | RUC                                              | Numeric. Length between 12 and 13 inclusive and ends with 001                                                                                                              |
| Ecuador            | PASS                                             | Alphanumeric. Length between 8 and 13 inclusive and ends with 001                                                                                                          |
| El Salvador        | DUI                                              | Length between 6 and 18 inclusive                                                                                                                                          |
| Ghana              | ID                                               | Length between 8 and 12 inclusive                                                                                                                                          |
| Guatemala          | DPI                                              | Length between 6 and 18 inclusive                                                                                                                                          |
| India              | ID (PAN)                                         | Length between 8 and 12 inclusive                                                                                                                                          |
| India              | DL (Driver's License)                            | Length between 15 and 16 inclusive                                                                                                                                         |
| India              | UID (Aadhar Card)                                | Numeric. Length 12                                                                                                                                                         |
| Indonesia          | NIK / KTP                                        | Numeric. Length between 14 and 18 inclusive                                                                                                                                |
| Japan              | DL / ID / PASS / RD (Resident Registration Card) | Length between 9 and 12 inclusive                                                                                                                                          |
| Kenya              | ID                                               | Length between 7 and 12 inclusive                                                                                                                                          |
| Malaysia           | ID                                               | Numeric. Length between 10 and 14 inclusive                                                                                                                                |
| Mexico             | CURP / RFC / IFE / PASS                          | Length between 8 and 18 inclusive                                                                                                                                          |
| Nicaragua          | CI                                               | Length between 8 and 18 inclusive                                                                                                                                          |
| Nigeria            | ID                                               | Length between 9 and 12 inclusive                                                                                                                                          |
| Panama             | CIP                                              | Numeric. Length between 5 and 10 inclusive                                                                                                                                 |
| Panama             | PASS                                             | Length between 8 and 11 inclusive                                                                                                                                          |
| Paraguay           | CRC / CRP / DNI / PASS / RUC                     | Length Between 3 and 15 characters                                                                                                                                         |
| Paraguay           | CIC                                              | Length between 6 to 8 characters                                                                                                                                           |
| Peru               | CE/CPP                                           | Numeric. Length 9                                                                                                                                                          |
| Peru               | DNI                                              | Numeric. Length 8-9                                                                                                                                                        |
| Peru               | PASS                                             | Numeric. Length 12                                                                                                                                                         |
| Peru               | RUC                                              | Length 11                                                                                                                                                                  |
| Philippines        | PSN                                              | Numeric. Length between 9 and 13 inclusive                                                                                                                                 |
| Singapore          | NRIC                                             | Length 9                                                                                                                                                                   |
| Singapore          | PASS                                             | Length 9                                                                                                                                                                   |
| South Africa       | ID                                               | Numeric. Length between 9 and 14 inclusive                                                                                                                                 |
| Tanzania           | ID                                               | Length between 8 and 20 inclusive                                                                                                                                          |
| Thailand           | ID                                               | Numeric. Length between 10 and 14 inclusive                                                                                                                                |
| Uganda             | RIC / NID                                        | Numeric. Length between 11 and 15 inclusive                                                                                                                                |
| Uruguay            | CI                                               | Numeric. Length between 6 and 8 inclusive                                                                                                                                  |
| Venezuela          | CI                                               | Numeric. Length between 3 and 20 inclusive                                                                                                                                 |
| Venezuela          | RIF                                              | Numeric. Length between 3 and 20 inclusive                                                                                                                                 |
| Vietnam            | ID                                               | Numeric. Length between 9 and 13 inclusive                                                                                                                                 |

## Postal code validations

The validation for the postal codes dependes up on the country sent. Make sure you validate them with the regex in the table below to avoid errors due to Invalid postal Code.

| Country            | Regex                                  |  Example  |
| ------------------ | -------------------------------------- | :-------: |
| Argentina          | `^\d{4}\|[A-Za-z]\d{4}([a-zA-Z]{3})?$` |  A1234ABC |
| Brazil             | `^\d{5}[\s-/]?\d{3}$`                  | 12345-678 |
| Cameroon           | N/A                                    |    N/A    |
| Canada             | `^[a-zA-Z]\d[a-zA-Z]\s?\d[a-zA-Z]\d$`  |  A1A 2B2  |
| Chile              | `^\d{3}[\s-/]?\d{4}$`                  |  123-4567 |
| Colombia           | `^\d{5,6}$`                            |   12345   |
| Côte d'Ivoire      | N/A                                    |    N/A    |
| Dominican Republic | `^\d{5}$`                              |   12345   |
| Ecuador            | `^\d{6}$`                              |   123456  |
| El Salvador        | N/A                                    |    N/A    |
| Ghana              | `^[A-Za-z]{2}\d{3,5}$`                 |   AB1234  |
| Guatemala          | N/A                                    |    N/A    |
| India              | `^\d{3}[\s-/]?\d{3}$`                  |  123-456  |
| Japan              | N/A                                    |    N/A    |
| Indonesia          | `^\d{5}$`                              |   12345   |
| Kenya              | `^\d{5}$`                              |   12345   |
| Malaysia           | `^\d{5}$`                              |   12345   |
| Mexico             | `^\d{5}$`                              |   12345   |
| Nicaragua          | N/A                                    |    N/A    |
| Nigeria            | `^\d{6}$`                              |   123456  |
| Panama             | `^\d{4,6}$`                            |   12345   |
| Paraguay           | `^\d{4}$`                              |    1234   |
| Peru               | `^\d{5}$`                              |   12345   |
| Philippines        | `^\d{3,4}$`                            |    1234   |
| Singapore          | N/A                                    |    N/A    |
| South Africa       | `^\d{4}$`                              |    2345   |
| Tanzania           | `^\d{5}$`                              |   12345   |
| Thailand           | `^\d{5}$`                              |   12345   |
| Uganda             | N/A                                    |    N/A    |
| Uruguay            | `^\d{5}$`                              |   12345   |
| Venezuela          | N/A                                    |    N/A    |
| Vietnam            | `^\d{5}$`                              |   12345   |

## Phone numbers validations

We use the Google's common library for parsing, formatting, and validating international phone numbers. Validating the phone numbers on your end could help preventing `Invalid phone number` errors.

{% embed url="<https://github.com/google/libphonenumber>" %}

## Emails validations

We suggest you using the following regex to validate email addresses on your end and prevent `invalid email` errors.

```
(?i)[a-z0-9!#$%&'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+\/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])
```


# CVU Offline

### What is CVU Offline?

The **CVU Offline** feature offers a streamlined deposit process for your customers in Argentina. It allows them to make payments by directly transferring funds to the merchant’s assigned CVU/CBU account, completely bypassing the standard checkout flow.

When a customer makes a transfer, our system is instantly notified. We then analyze the transaction details to create a formal deposit record, which is sent to you for approval or rejection. This provides a faster, more convenient payment experience for repeat customers.

### How It Works

1. A customer transfers money to the merchant's unique CVU/CBU account number.
2. We receive a notification of the incoming transfer.
3. We send a `POST` request to a webhook URL that you provide, containing all the transaction details.
4. Your system receives the request and returns a response to either **approve** or **reject** the deposit.

### Getting started

{% stepper %}
{% step %}

#### Contact your account manager

To enable this feature, please reach out to your designated Account Manager or Technical Account Manager.
{% endstep %}

{% step %}

#### Provide a webhook URL

You must provide us with a secure URL endpoint that can accept `POST` requests from our system. This URL will be used to notify you of every new CVU Offline transaction.

When we detect a new deposit, we will send a `POST` request to your URL with the following JSON body:

```json
{
  "deposit_id": 123456789,
  "payer_account_number": "0000003100012345678901",
  "country": "AR",
  "document": "40947043",
  "full_name": "John Doe",
  "date_of_birth": "19871027",
  "address": "Ruta 13, Argentina",
  "email": "jon.doe@example.com",
  "amount": 20000,
  "currency": "ARS",
  "payment_method": "CVUO"
}

```

<table><thead><tr><th width="223.3359375">Field</th><th width="102.53125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>deposit_id</code></td><td>Integer</td><td>Our unique identifier for the payment deposit.</td></tr><tr><td><code>payer_account_number</code></td><td>String</td><td>The CVU/CBU of the customer who made the payment.</td></tr><tr><td><code>country</code></td><td>String</td><td>The country of the transaction. Always "AR".</td></tr><tr><td><code>document</code></td><td>String</td><td>The identification document of the payer.</td></tr><tr><td><code>full_name</code></td><td>String</td><td>The full name of the payer.</td></tr><tr><td><code>date_of_birth</code></td><td>String</td><td>The payer's date of birth in <code>YYYYMMDD</code> format.</td></tr><tr><td><code>address</code></td><td>String</td><td>The address of the payer.</td></tr><tr><td><code>email</code></td><td>String</td><td>The email address of the payer.</td></tr><tr><td><code>amount</code></td><td>Number</td><td>The transaction amount.</td></tr><tr><td><code>currency</code></td><td>String</td><td>The currency of the payment. Always "ARS".</td></tr><tr><td><code>payment_method</code></td><td>String</td><td>The payment method used. Always "CVUO" for CVU Offline.</td></tr></tbody></table>

{% endstep %}

{% step %}

#### Handle deposit notifications

Your webhook URL must be configured to handle our requests and send back a response indicating your decision.

**Approving or rejecting a deposit**

Your system's response determines the status of the payment:

* **To Approve:** Return an <mark style="color:$success;">**HTTP**</mark><mark style="color:$success;">**&#x20;**</mark><mark style="color:$success;">**`200`**</mark> status code.
* **To Reject:** Return an <mark style="color:$danger;">**HTTP**</mark><mark style="color:$danger;">**&#x20;**</mark><mark style="color:$danger;">**`400`**</mark> status code.

{% hint style="danger" %}
*Any other HTTP status code will be treated as a rejection.*
{% endhint %}

{% endstep %}

{% step %}
***(Optional)*****&#x20;Overriding default information**

By default, we generate a random **`invoice_id`** and use your account's default notification URL for these deposits. However, you can override these values by including them in the body of your `200` (Approve) response.

If you wish to provide your own identifiers, your response body should look like this:

```json
{
   "invoice_id" : "YOUR_CUSTOM_INVOICE_ID",
   "notification_url" : "https://merchant.com/notifications/deposit/YOUR_ID"
}
```

If this body is returned, we will use the `invoice_id` and `notification_url` you provide instead of our defaults.
{% endstep %}
{% endstepper %}