# Welcome to LimePay API Docs

Welcome to Lime-Pay 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="/pages/-M7EsY5DfFpxd1LnXhL7">/pages/-M7EsY5DfFpxd1LnXhL7</a></td><td><a href="/files/flwjzN7nCfwXD44d50fW">/files/flwjzN7nCfwXD44d50fW</a></td></tr><tr><td align="center"><strong>Cashouts API</strong></td><td>S2S API. Develop your own checkout page where you will collect and send us all the details required to process the cashouts.</td><td><a href="/pages/-M8big5Sd0w_zMCIpDJP">/pages/-M8big5Sd0w_zMCIpDJP</a></td><td><a href="/files/4lOCCIbhQ6gtuc56AYvY">/files/4lOCCIbhQ6gtuc56AYvY</a></td></tr></tbody></table>

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

{% hint style="info" %}
Bear 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 %}


# Getting Started with Lime-Pay

Get started with Lime-Pay by creating your own account on our Merchant Panel!

In order to get started with us, you must Sign Up in our Merchant Panel to get you created a Merchant Account you will use along the way!

## Merchant Account

### Sign Up

<figure><img src="/files/VUZChGFcHEFhdb7HI6wk" alt=""><figcaption></figcaption></figure>

Once the Sign Up form was completed with your company information, we will contact you to work on the next steps.

### Account Creation

As soon as we are ready to start the technical integration, you will receive an email to configure your account in our STG environment.

<figure><img src="/files/cbE7D257CMgwCUFVosuP" alt=""><figcaption><p>Email to activate your account</p></figcaption></figure>

### Environments

Our STG environment is a safe environment you can use to test your integration and any new features you need to test risk-free.

<figure><img src="/files/EAi1k8i55kICvczKaFjm" alt=""><figcaption><p>Login Form</p></figcaption></figure>

### Integration

Integrate the solution you are looking for and make sure everything is working smoothly :nerd:&#x20;

### Go Live

Once you are done with the integration, Request the Go Live and we will create your account in Production.

We will receive your request, review your tests and if everything is fine, you will receive an email to activate your account in production.


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

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

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](#hosted-checkout-experience-not-available-for-new-integrations): We take the user to a checkout page to complete missing payment details manually. This flow is triggered as Oneshot experience fallback flow.

{% 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;

![](/files/kOboSlCJBcEPzwo4NNSk)

## Hosted Checkout Experience

{% hint style="warning" %}
Please contact your AM/TAM for instructions on how to enable this API Experience.
{% endhint %}

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

![](/files/VWvI7SwlBoTDmDFhQioM)

#### Getting Started

Follow this steps to start processing payments with the Lime-Pay Deposits API:

**1 - Sign Up:** [Create your merchant](/getting-started-with-lime-pay) 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](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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 **Lime-pay**!

Don't get stuck! In case you have any technical doubts not covered on this documentation, reach out to <support@lime-pay.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 offer

[![Run In Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/34627642-89340d44-5692-40e3-80b7-ffa805a9101d?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D34627642-89340d44-5692-40e3-80b7-ffa805a9101d%26entityType%3Dcollection%26workspaceId%3Db17cccc0-ffb1-4858-9176-a041e92b6817)

{% 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 **STG 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                                 |
| ----------- | -------------------------------------- |
| Staging     | `https://api-stg.lime-pay.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. Treat it as a password.

## Headers

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

<table><thead><tr><th>Header</th><th width="168" align="center">Format</th><th width="129" align="center">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td align="center">String</td><td align="center">Yes</td><td><code>"LIMEPAY "</code> plus a hash HMAC256 to verify request integrity</td></tr><tr><td>X-Login</td><td align="center">String</td><td align="center">Yes</td><td>Merchant <code>API Key</code></td></tr><tr><td>X-Date</td><td align="center">String</td><td align="center">Yes</td><td> ISO8601 Datetime: <code>yyyy-MM-dd'T'HH:mm:ssZ</code>. E.g.: <code>2023-08-21T22:52:23Z</code></td></tr><tr><td>Content-Type</td><td align="center">String</td><td align="center">Yes</td><td><code>application/json</code></td></tr><tr><td>X-Idempotency-Key</td><td align="center">String</td><td align="center">No</td><td>Unique value generated by the client which the server uses to recognize subsequent retries of the same request</td></tr></tbody></table>

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

If you use a Proxy or any other setup that could generate a delay between your client and our servers, please take that in consideration.
{% 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="" %}

```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 LimePay\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 %}

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

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

Continue to the next page to learn how to generate the requests signatures  to verify the integrity of the requests you send and receive.


# 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 "LIMEPAY " plus the hash generated, in the following format:

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

Example:

> Authorization: LIMEPAY 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.

{% 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 LIMEPAY_AUTHORIZATION_SCHEME = "LIMEPAY ";

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 LIMEPAY_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(payload.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 LimePayExample 
    {
    
        public readonly static string LIMEPAY_AUTHORIZATION_SCHEME = "LIMEPAY ";
        
        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 LIMEPAY_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 LimePayExample {
 
	const LIMEPAY_AUTHORIZATION_SCHEME = "LIMEPAY ";
	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 "LIMEPAY " in front of the hash
		return  self::LIMEPAY_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/LZ5qdKkHLT2Pdn3T1xgZ" path="/deposits" method="post" %}
[LimepayOpenAPI.yml](https://4143087822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQwMHQLA98rN2pqEMJgaj%2Fuploads%2Fmkjvcd7pkBezApH9iuTn%2FLimepayOpenAPI.yml?alt=media\&token=c0ff535a-7125-4d8a-89ff-54df9fa4fb2a)
{% 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" %}

```json
{
    "invoice_id" : "{{invoiceId}}",
    "amount": "5000",
    "country": "NG",
    "currency": "NGN",
    "payment_method": "TR",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "document_type": "ID",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+23485266942",
        "email": "Johndoe@hotmail.com",
        "address": {
            "street": "Lekki 13",
            "city": "Lagos",
            "zip_code": "100210"
        }
    },
    "description": "test description",
    "client_ip": "123.123.123.123",
    "back_url": "https://www.lime-pay.com/deposit_cancelled",
    "success_url": "https://www.lime-pay.com/deposit_completed",
    "error_url": "https://www.lime-pay.com/deposit_error",
    "notification_url": "https://lime-pay.com/limepay/notify",
    "logo": "https://www.lime-pay.com/limepay.png",
    "test": true,
    "mobile": false,
    "language": "en"
}
```

{% endtab %}

{% tab title="cURL" %}

```java
curl --location --request POST 'https://api-stg.lime-pay.com/v3/deposits' \
--header 'X-Login: xxxxxxx' \
--header 'X-Date: 2020-06-09T19:42:51Z' \
--header 'Authorization: LIMEPAY a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38' \
--header 'Content-Type: application/json' \
--data-raw '{
    "invoice_id" : "{{invoiceId}}",
    "amount": "5000",
    "country": "NG",
    "currency": "NGN",
    "payment_method": "TR",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "document_type": "ID",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+23485266942",
        "email": "Johndoe@hotmail.com",
        "address": {
            "street": "Lekki 13",
            "city": "Lagos",
            "zip_code": "100210"
        }
    },
    "description": "test description",
    "client_ip": "123.123.123.123",
    "back_url": "https://www.lime-pay.com/deposit_cancelled",
    "success_url": "https://www.lime-pay.com/deposit_completed",
    "error_url": "https://www.lime-pay.com/deposit_error",
    "notification_url": "https://lime-pay.com/limepay/notify",
    "logo": "https://www.lime-pay.com/limepay.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\": \"5000\",\n    \"country\": \"NG\",\n    \"currency\": \"NGN\",\n    \"payer\": {\n        \"id\": \"1122\",\n        \"document\": \"84932568207\",\n       \"first_name\": \"John\",\n        \"last_name\": \"Doe\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"johndoe@hotmail.com\",\n        \"address\": {\n            \"street\": \"Lekki 13\",\n            \"city\": \"LAgos\",\n            \"state\": \"LG\",\n            \"zip_code\": \"100210\"\n        }\n    },\n    \"payment_method\": \"TR\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.lime-pay.com/deposit_cancelled\",\n    \"success_url\": \"https://www.lime-pay.com/deposit_completed\",\n    \"error_url\": \"https://www.lime-pay.com/deposit_error\",\n    \"notification_url\": \"https://www.lime-pay.com/limepay/notify\",\n    \"logo\": \"https://www.lime-pay.com/limepay.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"en\"\n}");
    Request request = new Request.Builder()
      .url("https://api-stg.lime-pay.com/v3/deposits")
      .method("POST", body)
      .addHeader("X-Login", "xxxxxxx")
      .addHeader("X-Date", "2020-06-09T19:42:51Z")
      .addHeader("Authorization", "LIMEPAY 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.lime-pay.com/v3/deposits');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "invoice_id" : "{{invoiceId}}",
    "amount": "5000",
    "country": "NG",
    "currency": "NGN",
    "payment_method": "TR",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "document_type": "ID",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+23485266942",
        "email": "Johndoe@hotmail.com",
        "address": {
            "street": "Lekki 13",
            "city": "Lagos",
            "zip_code": "100210"
        }
    },
    "bonus_amount": 1.50,
    "bonus_relative": true,
    "strikethrough_price": 1.50,
    "description": "test description",
    "client_ip": "123.123.123.123",
    "back_url": "https://www.lime-pay.com/deposit_cancelled",
    "success_url": "https://www.lime-pay.com/deposit_completed",
    "error_url": "https://www.lime-pay.com/deposit_error",
    "notification_url": "https://lime-pay.com/limepay/notify",
    "logo": "https://www.lime-pay.com/limepay.png",
    "test": true,
    "mobile": false,
    "language": "en"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'X-Login' => 'xxxxxxxx',
  'X-Date' => '2020-06-09T19:42:51Z',
  'Authorization' => 'LIMEPAY 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.lime-pay.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", "LIMEPAY a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38");
            request.AddHeader("Content-Type", "application/json");
            request.AddParameter("application/json", "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"5000\",\n    \"country\": \"NG\",\n    \"currency\": \"NGN\",\n    \"payer\": {\n        \"id\": \"1122\",\n        \"document\": \"84932568207\",\n       \"first_name\": \"John\",\n        \"last_name\": \"Doe\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"johndoe@hotmail.com\",\n        \"address\": {\n            \"street\": \"Lekki 13\",\n            \"city\": \"LAgos\",\n            \"state\": \"LG\",\n            \"zip_code\": \"100210\"\n        }\n    },\n    \"payment_method\": \"TR\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.lime-pay.com/deposit_cancelled\",\n    \"success_url\": \"https://www.lime-pay.com/deposit_completed\",\n    \"error_url\": \"https://www.lime-pay.com/deposit_error\",\n    \"notification_url\": \"https://www.lime-pay.com/limepay/notify\",\n    \"logo\": \"https://www.lime-pay.com/limepay.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"en\"\n}",  ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}


```

{% endtab %}

{% tab title="Python" %}

<pre class="language-python"><code class="lang-python">import requests

url = "https://api-stg.lime-pay.com/v3/deposits"
<strong>
</strong>payload = "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"5000\",\n    \"country\": \"NG\",\n    \"currency\": \"NGN\",\n    \"payer\": {\n        \"id\": \"1122\",\n        \"document\": \"84932568207\",\n       \"first_name\": \"John\",\n        \"last_name\": \"Doe\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"johndoe@hotmail.com\",\n        \"address\": {\n            \"street\": \"Lekki 13\",\n            \"city\": \"LAgos\",\n            \"state\": \"LG\",\n            \"zip_code\": \"100210\"\n        }\n    },\n    \"payment_method\": \"TR\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.lime-pay.com/deposit_cancelled\",\n    \"success_url\": \"https://www.lime-pay.com/deposit_completed\",\n    \"error_url\": \"https://www.lime-pay.com/deposit_error\",\n    \"notification_url\": \"https://www.lime-pay.com/limepay/notify\",\n    \"logo\": \"https://www.lime-pay.com/limepay.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"en\"\n}"
headers = {
  'X-Login': 'xxxxxxx',
  'X-Date': '2020-06-09T19:42:51Z',
  'Authorization': 'LIMEPAY a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38',
  'Content-Type': 'application/json'
}

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

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


</code></pre>

{% 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.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  QR natively on your site   |
| `secondary_metadata.digitable_line` | string | Plain text string line the user can use to manually pay for the instead of scanning the QR |

{% 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 %}

{% 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 %}

### 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.](/api-documentation/deposits-api/endpoints/payment-methods-endpoint#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.lime-pay.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI1NjU3ODQ2NCIsImlhdCI6MTU5MTgyOTYzNiwiZXhwIjoxNTkzMTI1NjM2LCJsYW5ndWFnZSI6bnVsbH0.XIlYyskFpE_rh1-8sA0Bs3JzB2iMmqAXdovClPzorrZXmzol69JqkeU7TR5FMBRn",
    "deposit_id": 300000011,
    "user_id": "11",
    "merchant_invoice_id": "test123456789",
    "payment_info": {
        "type": "VOUCHER",
        "payment_method": "QRT",
        "payment_method_name": "Thai QR",
        "amount": 700,
        "currency": "THB",
        "expiration_date": "2024-06-15 22:53:56",
        "created_at": "2024-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" : "{{invoiceId}}",
    "amount": "5000",
    "country": "NG",
    "currency": "NGN",
    "payment_method": "TR",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "email": "Johndoe@hotmail.com",
    },
    "description": "test description",
    "client_ip": "123.123.123.123",
    "back_url": "https://www.lime-pay.com/deposit_cancelled",
    "success_url": "https://www.lime-pay.com/deposit_completed",
    "error_url": "https://www.lime-pay.com/deposit_error",
    "notification_url": "https://lime-pay.com/limepay/notify",
    "logo": "https://www.lime-pay.com/limepay.png",
    "test": true,
    "mobile": false,
    "language": "en"
}
```

{% endtab %}

{% tab title="cURL" %}

```java
curl --location --request POST 'https://api-stg.lime-pay.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": "500",
    "country": "TH",
    "currency": "THB",
    "payment_types": ["BANK_TRANSFER", "BANK_DEPOSIT"]
}
'


```

{% 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{
    OkHttpClient client = new OkHttpClient().newBuilder()
      .build();
    MediaType mediaType = MediaType.parse("application/json");
<strong>    RequestBody body = RequestBody.create(mediaType, "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"5000\",\n    \"country\": \"NG\",\n    \"currency\": \"NGN\",\n    \"payer\": {\n        \"id\": \"1122\",\n        \"document\": \"84932568207\",\n       \"first_name\": \"John\",\n        \"last_name\": \"Doe\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"johndoe@hotmail.com\",\n        \"address\": {\n            \"street\": \"Lekki 13\",\n            \"city\": \"LAgos\",\n            \"state\": \"LG\",\n            \"zip_code\": \"100210\"\n        }\n    },\n    \"payment_method\": \"TR\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.lime-pay.com/deposit_cancelled\",\n    \"success_url\": \"https://www.lime-pay.com/deposit_completed\",\n    \"error_url\": \"https://www.lime-pay.com/deposit_error\",\n    \"notification_url\": \"https://www.lime-pay.com/limepay/notify\",\n    \"logo\": \"https://www.lime-pay.com/limepay.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"en\"\n}");
</strong>    Request request = new Request.Builder()
      .url("https://api-stg.lime-pay.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());
  }
}


</code></pre>

{% 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.lime-pay.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\" : \"1000000001\",\n    \"amount\": \"5000\",\n    \"country\": \"NG\",\n    \"currency\": \"NGN\",\n    \"payer\": {\n        \"id\": \"1122\",\n        \"document\": \"84932568207\",\n       \"first_name\": \"John\",\n        \"last_name\": \"Doe\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"johndoe@hotmail.com\",\n        \"address\": {\n            \"street\": \"Lekki 13\",\n            \"city\": \"LAgos\",\n            \"state\": \"LG\",\n            \"zip_code\": \"100210\"\n        }\n    },\n    \"payment_method\": \"TR\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.lime-pay.com/deposit_cancelled\",\n    \"success_url\": \"https://www.lime-pay.com/deposit_completed\",\n    \"error_url\": \"https://www.lime-pay.com/deposit_error\",\n    \"notification_url\": \"https://www.lime-pay.com/limepay/notify\",\n    \"logo\": \"https://www.lime-pay.com/limepay.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"en\"\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.lime-pay.com")
payload = "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"5000\",\n    \"country\": \"NG\",\n    \"currency\": \"NGN\",\n    \"payer\": {\n        \"id\": \"1122\",\n        \"document\": \"84932568207\",\n       \"first_name\": \"John\",\n        \"last_name\": \"Doe\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"johndoe@hotmail.com\",\n        \"address\": {\n            \"street\": \"Lekki 13\",\n            \"city\": \"LAgos\",\n            \"state\": \"LG\",\n            \"zip_code\": \"100210\"\n        }\n    },\n    \"payment_method\": \"TR\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.lime-pay.com/deposit_cancelled\",\n    \"success_url\": \"https://www.lime-pay.com/deposit_completed\",\n    \"error_url\": \"https://www.lime-pay.com/deposit_error\",\n    \"notification_url\": \"https://www.lime-pay.com/limepay/notify\",\n    \"logo\": \"https://www.lime-pay.com/limepay.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"en\"\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.](/files/pECsqVhnY4BojdJXRDKy) ![Fill the missing information required.](/files/SFzBFx5eCbDHykzoGdaZ) ![Payment created! ](/files/aCCRNUQCyO2wvB4ynT48)

### 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 Lime-Pay 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="/pages/-M7hYaOywHqgj2bMbee9">refunds</a>)</td></tr></tbody></table>

#### Response Example

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

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

### Error Response examples

```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: CM|CN|GH|IN|ID|KE|MY|NG|PH|TH|TZ|UG|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"
}

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

```

## 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](/knowledge-base/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](/knowledge-base/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 (max length: 255)  | 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](/api-documentation/deposits-api/endpoints/payment-methods-endpoint#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](/api-documentation/deposits-api/endpoints/payment-methods-endpoint#payment-types)    |
| `sub_merchant_id`                                                                     | integer                   | Used to specify for which SubMerchant ID the deposit will be created.                                                                                                                                                                                        |         |                                                                                                                   |
| `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)  |
| `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, id, fr]`                                 |
| `back_url`                                                                            | string (max length: 2048) | Valid URL over HTTPS used to redirect the customer.                                                                                                                                                                                                          |         |                                                    `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]`                                                  |
| `expiration`                                                                          | numeric                   | <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.<br></p>                                                                                             |         |                                     <p>Number, up to 5 integers</p><p><br></p>                                    |

{% 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.lime-pay.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.lime-pay.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": "UI",
        "payment_method_name": "UPI",
        "amount": 571.03,
        "currency": "INR",
        "expiration_date": "2021-03-24 22:29:37",
        "created_at": "2021-03-24 17:29:37",
        "metadata": {
            "reference": 23432423,
            "beneficiary_name": "Lime-Pay LLP",
            "qr": "base64 code"
        }
    }
}

```

{% endtab %}
{% endtabs %}

## Request Objects

### Payer Object

<table data-full-width="true"><thead><tr><th width="184">Field name</th><th>Format</th><th>Description</th><th width="111" align="center">Default</th><th width="181" 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="/pages/-M8muWcG4tmJbnohBWM5#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="/pages/-M8muWcG4tmJbnohBWM5#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="/pages/-M7hYU7T42-pbXYXjrnh#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="/pages/-M8muWcG4tmJbnohBWM5#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 |     Valid state code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format.    |
| `zip_code` | string (max length: 16)  | Customer's zip code                               | [zip\_code validations](/knowledge-base/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.

<table data-header-hidden><thead><tr><th>Field name</th><th width="184">Format</th><th>Description</th><th align="center">Validations</th></tr></thead><tbody><tr><td>Field name</td><td>Format</td><td>Description</td><td align="center">Validations</td></tr><tr><td><code>bank_account_number</code></td><td>string (max length: 45)</td><td>Bank account number of the customer</td><td align="center">String of up to 45 characters</td></tr><tr><td><code>bank_branch</code></td><td>string (max length: 45)</td><td>Bank branch of the customer's bank account</td><td align="center">String of up to 45 characters</td></tr><tr><td><code>bank_beneficiary</code></td><td>string (max length: 255)</td><td> Bank account owner name</td><td align="center">String of up to 255 characters</td></tr><tr><td><code>bank_account_type</code></td><td>string (max length: 16)</td><td>Bank account type of the customer</td><td align="center"><a href="/pages/-M7hYU7T42-pbXYXjrnh#account-types">List of account types</a></td></tr></tbody></table>

## 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**](/api-documentation/deposits-api/endpoints/deposit-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 %}

## STG Testing

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

![Approve/Cancel from the Deposits view.](/files/zpJ6os7OuMT9LvEbAGJD) ![You can also Approve/Cancel deposits from the Transaction details](/files/2NQCpS80J1ZJYm8g2rkb)

## Notifications fields

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

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

![](/files/-M9_UqvQBGblaqYL1-oD)

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

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

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

![](/files/-M9zU27QNwGCCPG-JJEq)


# Deposit Status Endpoint

Retrieve the status of a previously created deposit

## Deposit Status

<mark style="color:blue;">`GET`</mark> `https://api-stg.lime-pay.com/v3/deposits/{deposit_id}`

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

#### Path Parameters

| Name                                          | Type    | Description                                                   |
| --------------------------------------------- | ------- | ------------------------------------------------------------- |
| deposit\_id<mark style="color:red;">\*</mark> | integer | LimePay deposit\_id. It is obtained when creating the deposit |

#### 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 Deposit status successfully retrieved." %}

```json

{
    "user_id": "a78d40c0-9f7c-40f0-93c2-9df76547f319",
    "deposit_id": 301423824,
    "invoice_id": "388433169",
    "country": "TH",
    "currency": "THB",
    "usd_amount": 56.10,
    "local_amount": 2000.00,
    "bonus_amount": 1.50,
    "bonus_relative": true,
    "payment_method": "QRT",
    "payment_type": "VOUCHER",
    "status": "COMPLETED",
    "payer": {
        "document": "1234567890123",
        "document_type": "PASS",
        "email": "Test@gmail.com",
        "first_name": "Test",
        "last_name": "Testing",
        "address": {
            "street": "This street",
            "city": "That City",
            "state": "MH",
            "zip_code": "110123"
         },
        "phone": "+661234567890"
    },
    "fee_amount": 2.78,
    "fee_currency": "USD",
    "refunded": false,
    "current_payer_verification": "NO_CURRENT_PAYER_DATA",
    "provider_external_reference": "741231231234",
    "completed_payment_method_code": "QRT"
}

```

{% endtab %}

{% tab title="208 The deposit\_id specified is not valid" %}

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

{% endtab %}
{% endtabs %}

## Request

You can trigger the check of the status of a deposit at any moment you consider pertinent. However, every time a deposit changes its status, we will send you a [notification](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint/notifications) containing the ID of the deposit so that you can check its status back to retrieve the new deposit's status.

### Example request

In the status endpoint, all the request have to be sent as GET, containing the [usual headers](/api-documentation/deposits-api/technical-and-security-aspects#headers).

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" %}

```bash
curl --location --request GET 'https://api-stg.lime-pay.com/v3/deposits/301423824' \
--header 'X-Login: xxxxxxx' \
--header 'X-Date: 2020-06-24T17:13:21Z' \
--header 'Authorization: LIMEPAY e339247fb57b10c053159cf87d3a88415f9be567beb46a93f6839d9fc45d2c8a' \
--data-raw ''


```

{% 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();
    Request request = new Request.Builder()
      .url("https://api-stg.lime-pay.com/v3/deposits/301423824")
      .method("GET", null)
      .addHeader("X-Login", "xxxxxxx")
      .addHeader("X-Date", "2020-06-24T17:13:21Z")
      .addHeader("Authorization", "LIMEPAY e339247fb57b10c053159cf87d3a88415f9be567beb46a93f6839d9fc45d2c8a")
      .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.lime-pay.com/v3/deposits/301423824");
            client.Timeout = -1;
            var request = new RestRequest(Method.GET);
            request.AddHeader("X-Login", "xxxxxxx");
            request.AddHeader("X-Date", "2020-06-24T17:13:21Z");
            request.AddHeader("Authorization", "LIMEPAY e339247fb57b10c053159cf87d3a88415f9be567beb46a93f6839d9fc45d2c8a");
            request.AddParameter("application/json", "",  ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}


```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.lime-pay.com/v3/deposits/301423824",
  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: xxxxxxxx",
    "X-Date: 2020-06-24T17:13:21Z",
    "Authorization: LIMEPAY e339247fb57b10c053159cf87d3a88415f9be567beb46a93f6839d9fc45d2c8a"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


```

{% endtab %}
{% endtabs %}

## Example response

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

```json

{
    "user_id": "a78d40c0-9f7c-40f0-93c2-9df76547f319",
    "deposit_id": 301423824,
    "invoice_id": "388433169",
    "country": "TH",
    "currency": "THB",
    "usd_amount": 56.10,
    "local_amount": 2000.00,
    "bonus_amount": 1.50,
    "bonus_relative": true,
    "payment_method": "QRT",
    "payment_type": "VOUCHER",
    "status": "COMPLETED",
    "payer": {
        "document": "1234567890123",
        "document_type": "PASS",
        "email": "Test@gmail.com",
        "first_name": "Test",
        "last_name": "Testing",
        "address": {
            "street": "This street",
            "city": "That City",
            "state": "MH",
            "zip_code": "110123"
         },
        "phone": "+661234567890"
    },
    "fee_amount": 2.78,
    "fee_currency": "USD",
    "refunded": false,
    "current_payer_verification": "NO_CURRENT_PAYER_DATA",
    "provider_external_reference": "741231231234",
    "completed_payment_method_code": "QRT"
}

```

{% endtab %}

{% tab title="PENDING" %}

```json
{
    "deposit_id": 301423817,
    "invoice_id": "postmanTest315819867",
    "country": "TH",
    "currency": "THB",
    "usd_amount": 56.10,
    "local_amount": 2000.00,
    "bonus_amount": 1.50,
    "bonus_relative": true,
    "payment_method": "QRT",
    "payment_type": "VOUCHER",
    "status": "PENDING",
    "payer": {
        "document": "1234567890123",
        "document_type": "PASS",
        "email": "performtest5676874@gmail.com",
        "first_name": "Test",
        "last_name": "Testing",
        "phone": "+662234567890"
    },
    "fee_amount": 2.78,
    "fee_currency": "USD",
    "refunded": false,
    "current_payer_verification": "NO_CURRENT_PAYER_DATA"
}

```

{% endtab %}

{% tab title="CREATED" %}

```json
{
    "deposit_id": 301423924,
    "invoice_id": "postmanTest323497269",
    "country": "TH",
    "currency": "THB",
    "usd_amount": 56.11,
    "local_amount": 2000.00,
    "bonus_amount": 1.50,
    "bonus_relative": true,
    "status": "CREATED",
    "payer": {
        "document": "1234567890123",
        "document_type": "PASS",
        "email": "performtest5676874@gmail.com",
        "first_name": "Test",
        "last_name": "Testing",
        "phone": "+662234567890"
    },
    "fee_amount": 2.78,
    "fee_currency": "USD",
    "refunded": false,
    "current_payer_verification": "NO_CURRENT_PAYER_DATA"
}
```

{% endtab %}
{% endtabs %}

### Response fields

<table data-full-width="true"><thead><tr><th width="307.3333333333333">Field name</th><th width="204">Format</th><th>Description</th></tr></thead><tbody><tr><td><code>user_id</code></td><td>String</td><td>ID generated for the user on LIME-PAY end</td></tr><tr><td><code>deposit_id</code></td><td>Number</td><td>ID of the deposit on LIME-PAY end</td></tr><tr><td><code>invoice_id</code></td><td>String</td><td>ID of the deposit on the merchant end</td></tr><tr><td><code>country</code></td><td>String</td><td><a href="/pages/-M8muWcG4tmJbnohBWM5#countries-and-currencies">Country ISO code</a></td></tr><tr><td><code>currency</code></td><td>String</td><td><a href="/pages/-M8muWcG4tmJbnohBWM5#countries-and-currencies">Local currency code</a></td></tr><tr><td><code>local_amount</code></td><td>Number</td><td>Amount in local currency</td></tr><tr><td><code>usd_amount</code></td><td>Number</td><td>Amount in USD</td></tr><tr><td><code>bonus_amount</code></td><td>Number</td><td>The amount specified as bonus in the request</td></tr><tr><td><code>bonus_relative</code></td><td>Boolean</td><td>Specifies if the <code>bonus_amount</code> is absolute or relative. It will be shown only if the <code>bonus_amount</code> is not null</td></tr><tr><td><code>payment_method</code></td><td>String</td><td><a href="/pages/-M7EyIJfwI7M7iTDXAkL">Payment method code</a> specified on the deposit request or selected by the user on our checkout. It will be shown only if the user has selected a payment method</td></tr><tr><td><code>payment_type</code></td><td>String</td><td><a href="/pages/-M7hYgDIPRyR1p3XGmws#payment-types">Type of the payment method</a>. It will be shown only if the user has selected a payment method</td></tr><tr><td><code>status</code></td><td>String</td><td><a href="/pages/-M8MAwZ0r4Szs2f_lbbI#deposits-status-codes">Status of the deposit</a></td></tr><tr><td><code>payer[]</code></td><td>Object</td><td>Object containing information about the payer. Only the values you've sent or we've collected will be shown.</td></tr><tr><td><code>payer.document</code></td><td>String</td><td>Payer's document of identity</td></tr><tr><td><code>payer.document_type</code></td><td>String</td><td>Payer's type of their document of identity</td></tr><tr><td><code>payer.email</code></td><td>String</td><td>Payer's email</td></tr><tr><td><code>payer.first_name</code></td><td>String</td><td>Payer's first name</td></tr><tr><td><code>payer.last_name</code></td><td>String</td><td>Payer's last name</td></tr><tr><td><code>payer.address[]</code></td><td>Object</td><td>Object containing the address details about the payer. Only the values you've sent or we've collected will be shown.</td></tr><tr><td><code>payer.address.city</code></td><td>String</td><td>Payer's city</td></tr><tr><td><code>payer.address.state</code></td><td>String</td><td>Payer's state ISO code</td></tr><tr><td><code>payer.address.street</code></td><td>String</td><td>Payer's street</td></tr><tr><td><code>payer.address.zip_code</code></td><td>String</td><td>Payer's zip code</td></tr><tr><td><code>fee_amount</code></td><td>Number</td><td>Fee of the deposit in the currency of your balance. It will be shown only if the payment_method was sent by you or selected by the customer</td></tr><tr><td><code>fee_currency</code></td><td>String</td><td>Currency of your balance. It will be shown only if the payment_method was sent by you or selected by the customer</td></tr><tr><td><code>refunded</code></td><td>Boolean</td><td>It shows if the deposit it was refunded or not.</td></tr><tr><td><code>current_payer_verification</code></td><td>String</td><td><a href="#current_payer_verification">It shows if the current payer is the same person who creates the deposit</a>. It will be shown only if it is not null. </td></tr><tr><td><code>bank_account.bank_code</code></td><td>String</td><td>The <a href="/pages/-MD6pLKfyLfm1wA5187i">Cashout Bank Code</a> of the bank from which the deposit was completed.</td></tr><tr><td><code>bank_account.account_number</code></td><td>String</td><td>The account number from which the deposit was completed.</td></tr><tr><td><code>bank_account.account_holder</code></td><td>String</td><td>The account holder's name from which the deposit was completed</td></tr><tr><td><code>provider_external_reference</code></td><td>String</td><td>Alphanumeric code that uniquely identifies financial transactions on the local banking system</td></tr></tbody></table>

## Parameter `current_payer_verification` <a href="#current_payer_verification" id="current_payer_verification"></a>

Through the parameter current\_payer\_verification you can check if the current payer is the same person who created the deposit. Below you can see the possible results for this parameter:\
\
Match --> The document of the person who paid is the same as the one of the person who created the payment.\
\
Unmatch --> The documents are different.\
\
No client document -> It is when there is no document of the person who proceed with the payment (Current payer).\
\
No current payer data -> It is when there is no document of the person who proceed with the payment (Current payer)

{% 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 to avoid any issues.
{% endhint %}

{% hint style="success" %}
If you are not sending all the payer details in the deposit request, make sure you store the details we collect and share with this endpoint so that in future attempts you can re-use them instead of having the payers to fill in the same details every time they deposit.
{% endhint %}

## 🏦 Bank\_Account (Object)

The `bank_account` object provides details about the bank account from which the deposit was made.\
This field is currently available for **Bank Transfer payments in Nigeria**, and is intended to support identification and reconciliation of incoming transactions.

If the bank code is not available, a default code of `41800` will be returned.

```json
{
  "user_id": "a78d40c0-9f7c-40f0-93c2-9df76547f319",
  "deposit_id": 301423824,
  "invoice_id": "388433169",
  "country": "NG",
  "currency": "NGN",
  "usd_amount": 20,
  "local_amount": 30000,
  "bonus_amount": 1.50,
  "bonus_relative": true,
  "payment_method": "TR",
  "payment_type": "BANK_TRANSFER",
  "status": "COMPLETED",
  "payer": {
    "document": "1234567890123",
    "document_type": "ID",
    "email": "johndoe@gmail.com",
    "first_name": "John",
    "last_name": "DOe",
    "address": {
      "street": "This street",
      "city": "That City",
      "state": "LG",
      "zip_code": "110123"
    },
    "phone": "+2348123456789"
  },
  "fee_amount": 0.5,
  "fee_currency": "USD",
  "refunded": false,
  "current_payer_verification": "NO_CURRENT_PAYER_DATA",
  "provider_external_reference": "741231231234",
  "bank_account": {
    "bank_code": 305,
    "account_number": "0189230918",
    "account_holder": "John Doe"
  }
}
```

## Status Flow

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

### Hosted Checkout Status Flow

&#x20;

![Hosted Checkout Status Flow Diagram](/files/-MAmeg3u4xX0qi35vFPw)

### OneShot Checkout Status Flow

&#x20;

![OneShot Status Flow Diagram](/files/-MAmeEV0RUvkskAe1Aji)

{% hint style="info" %}

1. 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. COMPLETED and CANCELLED\* are final status.
3. \*There are cases in which the users pays after the deposit expired, or paid an incorrect amount and the deposit gets expired. When that happens manual intervention is required to approve the deposit hence a deposit could change its status from EXPIRED or CANCELLED to COMPLETED.
4. EARLY RELEASED will only be used if you specified it in the deposit request.
5. FOR REVIEW is a transient status we use to specify that the deposit is under revision.
6. If the user doesn't pays, the transaction will be marked as EXPIRED. After 7 days it will change to CANCELLED.
   {% 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 Endpoint

The Payment Methods endpoint allows you to retrieve the complete list of payment methods you have available for the country specified

## Payment Methods

<mark style="color:blue;">`GET`</mark> `https://api-stg.lime-pay.com/v3/payment_methods?country={country}`

## Description

The **`payment_methods`** endpoint will show you all the payment methods your account has enabled for the country specified as **query params** in the request.

It will also show details about each payment method like the `payment method code`, the `payment method name`, the[`payment method type`](/api-documentation/deposits-api/endpoints/payment-methods-endpoint#payment-types) as well as the `payment method logo` and others.

{% hint style="info" %}
In case of integrating the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#full-request-streamline) and displaying the payment methods on your cashier, make sure you check the **payment methods** with this API multiple times per day to make sure that in case a new payment method becomes available or unavailable, you will also automatically update it on your cashier without requiring manual intervention from either side.
{% endhint %}

#### Query Parameters

| Name    | Type   | Description      |
| ------- | ------ | ---------------- |
| country | string | Country ISO code |

#### Headers

| Name          | Type   | Description                   |
| ------------- | ------ | ----------------------------- |
| Authorization | string | "Bearer " + Read-Only API Key |

{% hint style="success" %}
Please find all the country codes in the [Countries Specifications](/knowledge-base/countries-specifications#countries-and-currencies) section.
{% endhint %}

## Request

In order to start using the payment methods endpoint, you need to:

1. Send the request with **GET** method.
2. Specify a [valid country code](/knowledge-base/countries-specifications#countries-and-currencies) in the request as **QUERY PARAMS**.
3. Send the **Authorization** header with your read-only API Key as Bearer as follows:

> Authorization: Bearer *your\_read\_only\_key\_here*

### Example request

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

```bash
curl --location --request GET 'https://api-stg.lime-pay.com/v3/payment_methods?country=MY' \
--header 'Authorization: Bearer your_read_only_key_here'


```

{% 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();
    Request request = new Request.Builder()
      .url("https://api-stg.lime-pay.com/v3/payment_methods?country=MY")
      .method("GET", null)
      .addHeader("Authorization", "Bearer your_read_only_key_here")
      .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.lime-pay.com/v3/payment_methods?country=MY");
            client.Timeout = -1;
            var request = new RestRequest(Method.GET);
            request.AddHeader("Authorization", "Bearer your_read_only_key_here");
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}


```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.lime-pay.com/v3/payment_methods?country=MY",
  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(
    "Authorization: Bearer your_read_only_key_here"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


```

{% endtab %}
{% endtabs %}

#### Example Response

{% tabs %}
{% tab title="200 Payment methods successfully retrieved" %}

```json
[
    {
        "country": "MY",
        "code": "MB",
        "name": "AmBank",
        "type": "BANK_DEPOSIT",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/MB.svg"
    },
    {
        "country": "MY",
        "code": "TR",
        "name": "Bank Transfer",
        "type": "BANK_TRANSFER",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/TR.svg"
    },
    {
        "country": "MY",
        "code": "BST",
        "name": "Boost",
        "type": "WALLET",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/BST.svg",
        "daily_average": 216,
        "monthly_average": 142
    },
    {
        "country": "MY",
        "code": "BY",
        "name": "CIMB Bank",
        "type": "BANK_DEPOSIT",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/BY.svg",
        "daily_average": 50,
        "monthly_average": 50
    },
    {
        "country": "MY",
        "code": "FPX",
        "name": "FPX",
        "type": "BANK_TRANSFER",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/FPX.svg"
    },
    {
        "country": "MY",
        "code": "GRB",
        "name": "Grab",
        "type": "WALLET",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/GRB.svg",
        "daily_average": 300,
        "monthly_average": 300
    },
    {
        "country": "MY",
        "code": "MY",
        "name": "Maybank",
        "type": "BANK_DEPOSIT",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/MY.svg",
        "daily_average": 17,
        "monthly_average": 17
    },
    {
        "country": "MY",
        "code": "PU",
        "name": "Public Bank",
        "type": "BANK_DEPOSIT",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/PU.svg",
        "daily_average": 32,
        "monthly_average": 32
    },
    {
        "country": "MY",
        "code": "RH",
        "name": "RHB Bank",
        "type": "BANK_DEPOSIT",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/RH.svg",
        "daily_average": 15,
        "monthly_average": 15
    },
    {
        "country": "MY",
        "code": "SPAY",
        "name": "ShopeePay",
        "type": "WALLET",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/SPAY.svg",
        "daily_average": 101,
        "monthly_average": 101
    },
    {
        "country": "MY",
        "code": "TNG",
        "name": "Touch n Go",
        "type": "WALLET",
        "status": "OK",
        "logo": "https://resources.lime-pay.com/cashin/payment_method/square/TNG.svg",
        "daily_average": 73,
        "monthly_average": 73
    }
]
```

{% endtab %}

{% tab title="210 The country specified was incorrect" %}

```json
{
    "code": 210,
    "description": "Invalid country",
    "type": "INVALID_COUNTRY"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

### Response Fields

The response will return an object different for each payment method. You should be able to iterate though it no matter how many payment methods are returned.

| Field             | Format | Description                                                                                                                                                                                                   |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `country`         | String | [Country code](/knowledge-base/countries-specifications#countries-and-currencies)                                                                                                                             |
| `code`            | String | Payment method code that should be used when creating a [deposit request](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint)                                                                |
| `name`            | String | Payment method name                                                                                                                                                                                           |
| `type`            | String | Payment method type. Check the [Payment Types](/api-documentation/deposits-api/payment-methods) section for further details                                                                                   |
| `status`          | String | Status of the payment method. It will be updated in case a payment methods becomes momentaneously unavailable                                                                                                 |
| `logo`            | String | URL containing the payment method logo                                                                                                                                                                        |
| `daily_average`   | Number | Daily average time for the approval of the deposits with this payment method in seconds. \*Note that in case the method is new, we may not have daily average information so this field won't be returned     |
| `monthly_average` | Number | Monthly average time for the approval of the deposits with this payment method in seconds. \*Note that in case the method is new, we may not have monthly average information so this field won't be returned |

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

## Payment types

| payment\_type     | Description                     |
| ----------------- | ------------------------------- |
| *`BANK_DEPOSIT`*  | Bank deposits                   |
| *`BANK_TRANSFER`* | Electronic Funds Transfer (TEF) |
| *`WALLET`*        | Wallet solutions                |
| *`VOUCHER`*       | Cash solutions                  |
| *`MOBILE MONEY`*  | Mobile Money Solutions          |

## Payment Methods

Check the Payment Methods page for the full list of payment methods.

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


# Currency Exchange Endpoint

The Currency Exchange endpoint allows you to get the exchange of any local currency compared against USD

## Currency Exchange

<mark style="color:blue;">`GET`</mark> `https://api-stg.lime-pay.com/v3/exchange_rates?country={country}&amount={amount}`

The **`exchange_rates`** endpoint allow you to get the exchange of any currency compared against **USD**.

#### Query Parameters

| Name    | Type   | Description                                                               |
| ------- | ------ | ------------------------------------------------------------------------- |
| country | string | Country ISO code in whose local currency the amount will be converted to. |
| amount  | number | Amount to convert in USD. If none is specified, **`1`** will be assumed.  |

#### Headers

| Name          | Type   | Description                   |
| ------------- | ------ | ----------------------------- |
| Authorization | string | "Bearer " + Read-Only API Key |

### Example request

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

```bash
curl --location --request GET 'https://api-stg.lime-pay.com/v3/exchange_rates?country=VN&amount=1' \
--header 'Authorization: Bearer your_read_only_key_here'


```

{% 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();
    Request request = new Request.Builder()
      .url("https://api-stg.lime-pay.com/v3/exchange_rates?country=VN&amount=10")
      .method("GET", null)
      .addHeader("Authorization", "Bearer your_read_only_key_here")
      .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.lime-pay.com/v3/exchange_rates?country=VN&amount=10");
            client.Timeout = -1;
            var request = new RestRequest(Method.GET);
            request.AddHeader("Authorization", "Bearer your_read_only_key_here");
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}


```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.lime-pay.com/v3/exchange_rates?country=TH&amount=10",
  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(
    "Authorization: Bearer your_read_only_key_here"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;



```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200 Currency exchange correctly returned." %}

```java
{
    "fx_rate": 26118.7500,
    "currency": "VND",
    "converted_amount": 26118.7500
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

{% hint style="success" %}
Please find all the country codes in the [Countries Specifications](/knowledge-base/countries-specifications#details) section.
{% endhint %}

### Response fields

| Field name         | Format | Description                                                                                           |
| ------------------ | ------ | ----------------------------------------------------------------------------------------------------- |
| `fx_rate`          | Number | Currency exchange                                                                                     |
| `currency`         | String | [Currency](/knowledge-base/countries-specifications#countries-and-currencies) used for the conversion |
| `converted_amount` | Number | Amount resulting from multiplying the `amount` you sent with the `fx_rate`                            |


# Refund Status Endpoint

Retrieve the status of a previously created refund

## Refund Status

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

## 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](broken://pages/-MDNQRy5MPN_6WtjgIx9) containing the ID of the refund so that you can check its status back to retrieve the new refund's status.

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

* Send the request with **GET** method.
* Use the headers described [here](/api-documentation/deposits-api/technical-and-security-aspects#headers).
* Specify a valid `refund_id` in the URL of the request as PATH PARAMETERS.
* Send the Authorization header, as [explained here](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature).

#### Path Parameters

<table><thead><tr><th>Name</th><th width="184">Type</th><th>Description</th></tr></thead><tbody><tr><td>refund_id</td><td>integer</td><td>Lime-Pay refund_id. It is obtained when creating the refund</td></tr></tbody></table>

#### Headers

<table><thead><tr><th width="224">Name</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td>X-Date</td><td>string</td><td>ISO8601 Datetime with Timezone: <code>yyyy-MM-dd'T'HH:mm:ssZ</code></td></tr><tr><td>X-Login</td><td>string</td><td>Merchant X-Login API Key</td></tr><tr><td>Authorization</td><td>string</td><td>Authentication signature hash</td></tr></tbody></table>

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" %}

```bash
curl --location --request GET 'https://api-stg.lime-pay.com/v3/refunds/1682844' \
--header 'X-Login: {{X-Login}}' \
--header 'X-Date: {{X-Date}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Content-Type: application/json' \
--data-raw ''

```

{% 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();
    Request request = new Request.Builder()
      .url("https://api-stg.lime-pay.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());
  }
}


```

{% 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.lime-pay.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);
        }
    }
}


```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.lime-pay.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;


```

{% 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

| Field name            | Format  | Description                                                                                                                           |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `deposit_id`          | Integer | ID of the deposit refunded                                                                                                            |
| `merchant_invoice_id` | String  | Merchant invoice id of the deposit refunded                                                                                           |
| `status`              | Enum    | Status of the refund. [Click here for the full list of refund codes.](/api-documentation/deposits-api/api-codes#refunds-status-codes) |
| `amount`              | Number  | Amount of the refund                                                                                                                  |

{% 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 %}

## Status Flow

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

### Refund Status Flow

&#x20;

![](/files/-ME_j2yrI--6DukQU-9L)

{% 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/-M7EzpcNUPkNApVJ8G46" %}
[Africa](/api-documentation/deposits-api/payment-methods/africa)
{% endcontent-ref %}

{% content-ref url="/pages/-M7Ey\_UxoSGYAezpzpst" %}
[Asia](/api-documentation/deposits-api/payment-methods/asia)
{% 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.](/api-documentation/deposits-api/endpoints/payment-methods-endpoint)

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;

### 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.       |
| `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 %}


# Africa

Check the list of Payment Methods available on each African country

{% content-ref url="/pages/Vm87TgwaxY9HFFcrVF8d" %}
[Cameroon](/api-documentation/deposits-api/payment-methods/africa/cameroon)
{% endcontent-ref %}

{% content-ref url="/pages/-M7Ezy-SGBbGL31ebpoe" %}
[Ghana](/api-documentation/deposits-api/payment-methods/africa/ghana)
{% endcontent-ref %}

{% content-ref url="/pages/0nb3cSphlyO6EIMO1B62" %}
[Ivory coast](/api-documentation/deposits-api/payment-methods/africa/ivory-coast)
{% endcontent-ref %}

{% content-ref url="/pages/-M7Ezx4QcmA8\_5vfjQlu" %}
[Kenya](/api-documentation/deposits-api/payment-methods/africa/kenya)
{% endcontent-ref %}

{% content-ref url="/pages/-M7EzwgSNiBZTpSLr\_70" %}
[Nigeria](/api-documentation/deposits-api/payment-methods/africa/nigeria)
{% endcontent-ref %}

{% content-ref url="/pages/RpSYWPyUiuLll5v39OCA" %}
[Uganda](/api-documentation/deposits-api/payment-methods/africa/uganda)
{% endcontent-ref %}

{% content-ref url="/pages/hmYe1KdFDtj6zoFP2zmV" %}
[South Africa](/api-documentation/deposits-api/payment-methods/africa/south-africa)
{% endcontent-ref %}

{% content-ref url="/pages/OC6FONkaptzPFj4FHnq5" %}
[Tanzania](/api-documentation/deposits-api/payment-methods/africa/tanzania)
{% endcontent-ref %}

{% content-ref url="/pages/uUfTHBuPzAljD0ACWNKO" %}
[Zambia](/api-documentation/deposits-api/payment-methods/africa/zambia)
{% endcontent-ref %}


# Cameroon

Check the list of Payment Methods available in cameroon

## Payment Methods

<table><thead><tr><th width="111" align="center">Icon</th><th width="127.875" align="center">payment_method</th><th width="97">Name</th><th width="127" align="center">Flow</th><th width="164" align="center">Payment Type</th><th width="170" align="center">Available for test</th></tr></thead><tbody><tr><td align="center"><div><figure><img src="/files/x3CGX3QyYrc956GdIqH5" alt=""><figcaption></figcaption></figure></div></td><td align="center"><code>ORM</code></td><td>Orange Money</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/GpnNufVv3pTrB3d1uy0w" alt="" data-size="line"></td><td align="center"><code>MT</code></td><td>MTN</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td><td align="center">Yes</td></tr></tbody></table>

***

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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

<table><thead><tr><th width="178.4271240234375">Payment Method Name</th><th align="center">document</th><th align="center">email</th><th align="center">first_name</th><th align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Mandatory</td></tr></tbody></table>

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


# Egypt

Check the list of Payment Methods available on Egypt

## Payment Methods

<table><thead><tr><th width="138" align="center">Icon</th><th width="169" align="center">payment_method</th><th width="139">Name</th><th width="125" align="center">Flow</th><th align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"> <img src="/files/3QxOmLOmk8fXpxszKEr5" alt="" data-size="line"></td><td align="center"><code>VO</code></td><td>Vodafone</td><td align="center"><code>ONE_SHOT</code><br><code>REDIRECT</code></td><td align="center"><code>MOBILE MONEY</code></td></tr><tr><td align="center"><img src="/files/OAEevqI974yM9O2zBpCm" alt="" data-size="line"></td><td align="center"><code>ETI</code></td><td>Etisalat</td><td align="center"><code>ONE_SHOT</code><br><code>REDIRECT</code></td><td align="center"><code>MOBILE MONEY</code></td></tr><tr><td align="center"><img src="/files/XAkvbP0qzGohQ8Rjy8wL" alt="" data-size="line"></td><td align="center"><code>ORM</code></td><td>Orange Money</td><td align="center"><code>ONE_SHOT</code><br><code>REDIRECT</code></td><td align="center"><code>MOBILE MONEY</code></td></tr><tr><td align="center"><img src="/files/rZC0xHI2IEFGRpRiJeXy" alt="" data-size="line"></td><td align="center"><code>FAW</code></td><td>Fawry</td><td align="center"><code>ONE_SHOT</code><br><code>REDIRECT</code></td><td align="center"><code>WALLET</code></td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="136" align="center">country</th><th width="119" align="center">amount</th><th width="133" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>country</code></td><td align="center"><code>amount</code></td><td align="center"><code>payer[]</code></td><td align="center"><code>payment_method</code></td></tr><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="159.2291259765625" align="center">document</th><th width="131.7291259765625" align="center">email</th><th width="131.3333740234375" align="center">first_name</th><th align="center">last_name</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>document</code></td><td align="center"><code>email</code></td><td align="center"><code>first_name</code></td><td align="center"><code>last_name</code></td></tr><tr><td>All</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 %}


# Ghana

Check the list of Payment Methods available on Ghana

Payment Methods

<table><thead><tr><th width="82" align="center">Icon</th><th width="197.385498046875" align="center">payment_method</th><th width="149.744873046875">Name</th><th width="127" align="center">Flow</th><th width="164" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><div><figure><img src="/files/XKce9DucuHk3yAxnMyDK" alt="" width="188"><figcaption></figcaption></figure></div></td><td align="center"><code>MT</code></td><td>MTN</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td></tr><tr><td align="center"><div><figure><img src="/files/xFjVft2bOzIbYG8LHfc0" alt="" width="150"><figcaption></figcaption></figure></div></td><td align="center"><code>VO</code></td><td>Vodafone</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td></tr><tr><td align="center"><div><figure><img src="/files/rr7mIxCGKRCsEpfhF3O1" alt="" width="67"><figcaption></figcaption></figure></div></td><td align="center"><code>ATG</code></td><td>AirtelTigo</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td></tr></tbody></table>

***

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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

<table><thead><tr><th width="179.890625">Payment Method Name</th><th width="116.421875" align="center">document</th><th width="109.7186279296875" align="center">email</th><th width="120.7916259765625" align="center">first_name</th><th align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</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 %}


# Ivory coast

Check the list of Payment Methods available in ivory coast

## Payment Methods

<table><thead><tr><th width="111" align="center">Icon</th><th align="center">payment_method</th><th width="97">Name</th><th width="127" align="center">Flow</th><th width="164" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/PHLxDzoKmG29mqw9iQPi" alt="" data-size="line"></td><td align="center"><code>ORM</code></td><td>Orange Money</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td></tr><tr><td align="center"><img src="/files/GpnNufVv3pTrB3d1uy0w" alt="" data-size="line"></td><td align="center"><code>MT</code></td><td>MTN</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td></tr><tr><td align="center"><img src="/files/t4fkZBExb9kWtfhsL8x2" alt="" data-size="line"></td><td align="center"><code>WV</code></td><td>WAVE</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td></tr></tbody></table>

***

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table><thead><tr><th width="189.46881103515625">Payment Method Name</th><th width="140.786376953125" align="center">country</th><th width="97.1510009765625" align="center">amount</th><th width="142.364501953125" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table><thead><tr><th width="186.57293701171875">Payment Method Name</th><th width="146.90625" align="center">document</th><th width="106.625" align="center">email</th><th width="113.65625" align="center">first_name</th><th width="103.734375" align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</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 %}


# Kenya

Check the list of Payment Methods available on Kenya

## Payment Methods

<table><thead><tr><th width="96" align="center">Icon</th><th align="center">payment_method</th><th>Name</th><th align="center">Flow</th><th align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/0qjnDC8ybu9VQAi3zxfX" alt="" data-size="line"></td><td align="center"><code>MP</code></td><td>M-Pesa</td><td align="center"><p><code>REDIRECT</code></p><p><code>ONE_SHOT</code></p></td><td align="center">MOBILE_MONEY</td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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 |   phone   |
| ------------------- | :------: | :---: | :---------: | :--------: | :-------: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    | Mandatory |

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


# Nigeria

Check the list of Payment Methods available on Nigeria

## Payment Methods

<table><thead><tr><th width="99" align="center">Icon</th><th width="152" align="center">payment_method</th><th>Name</th><th width="168" align="center">Flow</th><th width="206" align="center">Payment Type</th><th align="center">Available for test</th></tr></thead><tbody><tr><td align="center"><img src="/files/6Rw2SE0wsPHEgRQlryLH" alt="" data-size="line"></td><td align="center"><code>TR</code></td><td>Bank Transfer</td><td align="center"><p><code>REDIRECT</code></p><p><code>ONE_SHOT</code></p></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/ovBdRA1WDVu86PRcGHi5" alt="" data-size="line"></td><td align="center"><code>OPAY</code></td><td>Opay</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">No</td></tr><tr><td align="center"><img src="/files/ihzLwPfVEX9rGEAdkAFD" alt="" data-size="line"></td><td align="center"><code>PALM</code></td><td>Palmpay</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">No</td></tr></tbody></table>

Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details.

## 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 | phone |
| ------------------- | :------: | :---: | :---------: | :--------: | :---: |
| All                 |    Yes   |  Yes  |     Yes     |     Yes    |  Yes  |

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

{% hint style="info" %}
We now return Bank account information that provides information about the bank account from which the deposit was paid. You can see more information here [Deposit Status Endpoint](/api-documentation/deposits-api/endpoints/deposit-status-endpoint#bank_account-object)

```
"bank_account": {
        "bank_code": 11,
        "account_number": "0189230918"
    }
```

{% endhint %}

***

### Discover the Payment Flows Behind Our Top Methods! 🚀

#### &#x20;Bank Transfer:

<figure><img src="/files/ZczlwwJmNBn7AIlY5xaz" alt=""><figcaption><p>Bank Transfer Flow</p></figcaption></figure>

#### Palmpay:

<figure><img src="/files/qnfp65vd92wcIFw9sbe2" alt=""><figcaption><p>Palmpay Flow</p></figcaption></figure>

#### Opay:

<figure><img src="/files/38kIapTaaZCGWh6eqT7a" alt=""><figcaption><p>Opay Flow</p></figcaption></figure>


# Bank Transfer Offline

The **Bank Transfer Offline** feature will allow customers in Nigeria to create deposits without going through the standard checkout flow. Instead, they can make a direct payment by transferring funds to their previously assigned unique bank account number.

When we receive a notification about a transfer that was not yet recorded in our system, we will process it and create the corresponding record based on internal validation rules to determine whether the payment should be accepted or rejected.

To activate this functionality, please contact your Account Manager or Technical Account Manager.

```
{
  "deposit_id": 874239561,
  "payer_account_number": "7650351175",
  "country": "NG",
  "document": "98765432109",
  "full_name": "Oluwaseun Adeyemi",
  "date_of_birth": "19930614",
  "address": "12 Ahmadu Bello Way, Victoria Island, Lagos",
  "email": "oluwaseun.adeyemi@example.com",
  "amount": 15750,
  "currency": "NGN",
  "payment_method": "TROF"
}
```

***

#### Field Descriptions

**deposit\_id**\
Unique identifier for the deposit.

**payer\_account\_number**\
The Nigerian bank account number of the payer.

**country**\
"NG" – indicating Nigeria.

**document**\
Payer’s identification document&#x20;

**full\_name**\
Full legal name of the payer.

**date\_of\_birth**\
Date of birth in YYYYMMDD format.

**address**\
Payer’s residential address.

**email**\
Email of the payer.

**amount**\
Transaction amount.

**currency**\
Currency of the payment – "NGN".

**payment\_method**\
Payment method – "TROF" (Bank Transfer Offline).

***

#### Responses

The provided URL should return:

* **200 HTTP Status** → Deposit is approved.
* **400 HTTP Status** → Deposit is rejected.
* Any other response status is treated as rejection.


# Uganda

## Payment Methods

<table><thead><tr><th width="111" align="center">Icon</th><th align="center">payment_method</th><th width="97">Name</th><th width="127" align="center">Flow</th><th width="164" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/wIVgljFQnyfZC7FUSgrE" alt="" data-size="line"></td><td align="center"><code>AL</code></td><td>Airtel</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td></tr><tr><td align="center"><img src="/files/GpnNufVv3pTrB3d1uy0w" alt="" data-size="line"></td><td align="center"><code>MT</code></td><td>MTN</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td></tr></tbody></table>

***

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table><thead><tr><th width="189.46881103515625">Payment Method Name</th><th width="140.786376953125" align="center">country</th><th width="97.1510009765625" align="center">amount</th><th width="142.364501953125" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table><thead><tr><th width="186.57293701171875">Payment Method Name</th><th width="146.90625" align="center">document</th><th width="106.625" align="center">email</th><th width="113.65625" align="center">first_name</th><th width="103.734375" align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</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 %}


# South Africa

Check the list of Payment Methods available on South Africa

## Payment Methods

<table><thead><tr><th width="120" align="center">Icon</th><th width="124" align="center">payment_method</th><th width="170">Name</th><th width="123" align="center">Flow</th><th width="233" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/shCQVTAlSs1NVXdNfhnP" alt="" data-size="line"></td><td align="center"><code>EFT</code></td><td>Electronic Funds Transfer</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td></tr></tbody></table>

{% hint style="warning" %}
Banks Supported on EFT : FNB, Standard bank, ABSA, NedBank, Tymebank, Investec, Bidvest Bank, African bank&#x20;
{% endhint %}

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table><thead><tr><th width="183.3228759765625">Payment Method Name</th><th width="108" align="center">country</th><th width="158.307373046875" align="center">amount</th><th width="102.802001953125" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table><thead><tr><th>Payment Method Name</th><th width="129.614501953125" align="center">document</th><th width="103.1041259765625" align="center">email</th><th align="center">first_name</th><th align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Optional</td></tr></tbody></table>

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


# Tanzania

Check the list of Payment Methods available on Tanzania

## Payment Methods

<table><thead><tr><th width="100.75518798828125" align="center">Icon</th><th width="208.510498046875" align="center">payment_method</th><th width="129.66015625">Name</th><th width="127" align="center">Flow</th><th width="164" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/Lg9cQOOdOdiZ9SJyttAZ" alt="" data-size="line"></td><td align="center"><code>YAS</code></td><td>Mixx by Yas</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center"><code>MOBILE_MONEY</code></td></tr><tr><td align="center"><img src="/files/JQpIWuL9dz6fuA4B3sJk" alt="" data-size="line"></td><td align="center"><code>AL</code></td><td>Airtel</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center"><code>MOBILE_MONEY</code></td></tr><tr><td align="center"><img src="/files/WAxX7hdE6vN2JgQaGuBA" alt="" data-size="line"></td><td align="center"><code>MP</code></td><td>M-Pesa</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center"><code>MOBILE_MONEY</code></td></tr><tr><td align="center"><img src="/files/LLTZXOTnYnxc7Ik2sRdR" alt="" data-size="line"></td><td align="center"><code>ATG</code></td><td>AirtelTigo</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center"><code>MOBILE_MONEY</code></td></tr><tr><td align="center"><img src="/files/5TPm5puXvmLSjl8emkhy" alt="" data-size="line"></td><td align="center"><code>HLP</code></td><td>Halopesa</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center"><code>MOBILE_MONEY</code></td></tr></tbody></table>

***

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table><thead><tr><th width="174">Payment Method</th><th width="137" align="center">country</th><th width="116" align="center">amount</th><th width="127" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table><thead><tr><th width="140.85418701171875">Payment Method</th><th align="center">document</th><th width="113.9635009765625" align="center">email</th><th align="center">first_name</th><th align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Mandatory</td></tr></tbody></table>

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


# Zambia

Check the list of Payment Methods available on Zambia

## Payment Methods

<table><thead><tr><th width="82" align="center">Icon</th><th width="213" align="center">payment_method</th><th width="97">Name</th><th width="127" align="center">Flow</th><th width="164" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/H0y8VkuEnLbelvwGI6XE" alt="" data-size="line"></td><td align="center"><code>AL</code></td><td>Airtel</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td></tr><tr><td align="center"><img src="/files/q9cvQqGDEFlv6jNVDnoj" alt="" data-size="line"></td><td align="center"><code>MT</code></td><td>MTN</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center">MOBILE_MONEY</td></tr></tbody></table>

***

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table><thead><tr><th width="174">Payment Method</th><th width="137" align="center">country</th><th width="116" align="center">amount</th><th width="127" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table><thead><tr><th width="152.4010009765625">Payment Method</th><th width="109.640625" align="center">document</th><th width="98.755126953125" align="center">email</th><th align="center">first_name</th><th align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Mandatory</td></tr></tbody></table>

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


# Asia

Check the list of Payment Methods available on each Asian country

{% content-ref url="/pages/bM4KmQ4lsnJ7tQTrkCd1" %}
[Bangladesh](/api-documentation/deposits-api/payment-methods/asia/bangladesh)
{% endcontent-ref %}

{% content-ref url="/pages/8c6h162JYODg5zRp5rLs" %}
[China](/api-documentation/deposits-api/payment-methods/asia/china)
{% endcontent-ref %}

{% content-ref url="/pages/-M9RAFzo3DZ6q-HeilLh" %}
[India](/api-documentation/deposits-api/payment-methods/asia/india)
{% endcontent-ref %}

{% content-ref url="/pages/-M9RAFREp5p0Cu2Az9zs" %}
[Indonesia](/api-documentation/deposits-api/payment-methods/asia/indonesia)
{% endcontent-ref %}

{% content-ref url="/pages/-M9RAEnPitFAhysMsr1c" %}
[Malaysia](/api-documentation/deposits-api/payment-methods/asia/malaysia)
{% endcontent-ref %}

{% content-ref url="/pages/OgObhoW8PolAE5qn7pxA" %}
[Pakistan](/api-documentation/deposits-api/payment-methods/asia/pakistan)
{% endcontent-ref %}

{% content-ref url="/pages/-M9RBukpdEhoMjRiCOxS" %}
[Thailand](/api-documentation/deposits-api/payment-methods/asia/thailand)
{% endcontent-ref %}

{% content-ref url="/pages/-M9RBvWPtFjdpRBuwVM\_" %}
[Vietnam](/api-documentation/deposits-api/payment-methods/asia/vietnam)
{% endcontent-ref %}


# Bangladesh

Check the list of Payment Methods available on Bangladesh

## Payment Methods

<table><thead><tr><th width="97" align="center">Icon</th><th width="223" align="center">payment_method</th><th width="127">Name</th><th width="119" align="center">Flow</th><th width="172" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/kWSKFq1xbAPRMmS5YQ5l" alt="" data-size="line"></td><td align="center"><code>BKH</code></td><td>Bkash</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td></tr><tr><td align="center"><img src="/files/VVspUVVNcRymakuqTvJ9" alt="" data-size="line"></td><td align="center"><code>NAD</code></td><td>Nagad</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td></tr><tr><td align="center"><img src="/files/qzUSMR9yBBzGRe4YdWnI" alt="" data-size="line"></td><td align="center"><code>ROK</code></td><td>Rocket</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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

<table><thead><tr><th width="178.4271240234375">Payment Method Name</th><th align="center">document</th><th align="center">email</th><th align="center">first_name</th><th align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</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 %}


# China

Check the list of Payment Methods available on China

## Payment Methods

<table><thead><tr><th align="center">Icon</th><th align="center">payment_method</th><th width="139">Name</th><th width="122" align="center">Flow</th><th width="175" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/nFRCxvuAUaw5ofiOHPbx" alt="" data-size="line"></td><td align="center"><code>P2P</code></td><td>Bank Transfer (P2P)</td><td align="center"><code>REDIRECT</code></td><td align="center"><code>VOUCHER</code></td></tr><tr><td align="center"><img src="/files/9IXupUTu9iLOA8CkOpNo" alt="" data-size="line"></td><td align="center"><code>AP</code></td><td>AliPay</td><td align="center"><p><code>ONE_SHOT</code></p><p><code>REDIRECT</code></p></td><td align="center"><code>WALLET</code></td></tr><tr><td align="center"><img src="/files/soKKoeYOYg3QrDa6eqSY" alt="" data-size="line"></td><td align="center"><code>DT</code></td><td>DingTalk</td><td align="center"><code>REDIRECT</code></td><td align="center"><code>WALLET</code></td></tr><tr><td align="center"><img src="/files/onzBI0JvhwfgiXXCXHa5" alt="" data-size="line"></td><td align="center"><code>ECNY</code></td><td>e-CNY</td><td align="center"><code>REDIRECT</code></td><td align="center"><code>WALLET</code></td></tr><tr><td align="center"><img src="/files/8xTOzNy7H9bD6Am11UL1" alt="" data-size="line"></td><td align="center"><code>ICSH</code></td><td>iCash One</td><td align="center"><code>REDIRECT</code></td><td align="center"><code>VOUCHER</code></td></tr></tbody></table>

{% hint style="info" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="139" align="center">country</th><th width="119" align="center">amount</th><th width="128" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>country</code></td><td align="center"><code>amount</code></td><td align="center"><code>payer[]</code></td><td align="center"><code>payment_method</code></td></tr><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="151" align="center">document</th><th align="center">email</th><th align="center">first_name</th><th align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>document</code></td><td align="center"><code>email</code></td><td align="center"><code>first_name</code></td><td align="center"><code>last_name</code></td><td align="center"><code>Phone</code></td></tr><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes (Chineese)</td><td align="center">Yes (Chineese)</td><td align="center">Yes</td></tr></tbody></table>

{% hint style="info" %}
Kindly note that the First and Last Name should be in Chinese
{% endhint %}

#### ICash One

<table><thead><tr><th></th><th width="128">payment_method</th><th>Name</th><th>Flow</th><th>Payment Type</th><th>Iframe</th></tr></thead><tbody><tr><td></td><td><code>ICSH</code></td><td>ICash One</td><td><code>ONE_SHOT</code></td><td>Voucher</td><td>✓</td></tr></tbody></table>

#### Required Fields

| Field            | Type   | Required |
| ---------------- | ------ | -------- |
| `country`        | string | Yes      |
| `amount`         | number | Yes      |
| `payment_method` | string | Yes      |
| `payer[email]`   | string | Yes      |
| `payer[phone]`   | string | Yes      |

#### Request Example

```json
{
  "country": "CN",
  "amount": 5000,
  "currency": "CNY",
  "payment_method": "ICSH",
  "merchant_invoice_id": "INV-001",
  "payer": {
    "email": "user@example.com",
    "phone": "8613800138000"
  }
}
```

#### Response Example

```json
{
  "checkout_type": "ONE_SHOT",
  "redirect_url": "https://payment.depositcheckout.com/v1/checkout/...",
  "iframe": true,
  "deposit_id": 1597517685,
  "merchant_invoice_id": "INV-001",
  "payment_info": {
    "type": "VOUCHER",
    "payment_method": "ICSH",
    "payment_method_name": "ICash",
    "amount": 5000,
    "currency": "CNY",
    "expiration_date": "2026-06-19 09:36:07",
    "created_at": "2026-06-18 09:36:06",
    "metadata": {
      "sub_type": "REDIRECT",
      "qr_code": "data:image/png;base64,...",
      "provider_link": "https://payments.citedist.com/deposit/..."
    }
  }
}
```


# Hong Kong

Check the list of Payment Methods available on Hong Kong

## Payment Methods

<table><thead><tr><th align="center">Icon</th><th align="center">payment_method</th><th width="139">Name</th><th width="122" align="center">Flow</th><th width="175" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/-MZmPuB5xvap1KeEj1jP" alt="" data-size="line"></td><td align="center">ITBA</td><td>Bank Transfer </td><td align="center"><code>REDIRECT</code></td><td align="center"><code>BANK_TRANSFER</code></td></tr></tbody></table>

{% hint style="info" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="110.46875" align="center">country</th><th width="99.171875" align="center">amount</th><th width="108.4896240234375" align="center">payer[]</th><th width="160.5885009765625" align="center">payment_method</th><th align="center">client_ip</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>country</code></td><td align="center"><code>amount</code></td><td align="center"><code>payer[]</code></td><td align="center"><code>payment_method</code></td><td align="center"><code>client_ip</code></td></tr><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table><thead><tr><th width="178.4271240234375">Payment Method Name</th><th align="center">document</th><th align="center">email</th><th align="center">first_name</th><th align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</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="info" %}
Kindly note that the First and Last Name should be in Chinese
{% endhint %}


# India

Check the list of Payment Methods available on India

## Payment Methods

<table><thead><tr><th width="107" align="center">Icon</th><th align="center">payment_method</th><th width="156">Name</th><th width="120" align="center">Flow</th><th width="176" align="center">Payment Type</th><th align="center">Iframe supported</th></tr></thead><tbody><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/UI.svg"><img src="https://resources.directa24.com/cashin/payment_method/square/UI.svg" alt="" data-size="line"></a></td><td align="center"><code>UI</code></td><td>UPI</td><td align="center"><code>REDIRECT</code></td><td align="center"><code>BANK_DEPOSIT</code></td><td align="center">No</td></tr><tr><td align="center"><img src="/files/DpbccAPQmP4BHViOSHts" alt="" data-size="line"></td><td align="center"><code>UIS</code></td><td>UPI Seamless</td><td align="center"><code>REDIRECT</code><br><code>ONE_SHOT</code></td><td align="center"><code>BANK_DEPOSIT</code></td><td align="center"><p></p><p>Yes</p></td></tr><tr><td align="center"><img src="/files/8AbLK29yZ8wnssfOvm3e" alt="" data-size="original"></td><td align="center"><code>ICSH</code></td><td>iCash One </td><td align="center"><code>ONE_SHOT</code></td><td align="center"><code>VOUCHER</code><br><code>WALLET</code></td><td align="center">Yes</td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

| Field            | Required? |
| ---------------- | --------- |
| `Country`        | Yes       |
| `Amount`         | Yes       |
| `Payer[]`        | Yes       |
| `payment_method` | Yes       |

### Payer object requirements

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="139" align="center">document</th><th width="92" align="center">email</th><th width="143" align="center">first_name</th><th width="130" align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>document</code></td><td align="center"><code>email</code></td><td align="center"><code>first_name</code></td><td align="center"><code>last_name</code></td><td align="center"><code>phone</code></td></tr><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">No</td></tr></tbody></table>

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

### UPI&#x20;

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

```javascript
{
    "invoice_id" : "{{invoiceId}}",
    "amount": "500",
    "country": "IN",
    "currency": "INR",
    "payment_method": "UI",
    "payer": {
        "document": "1233131313",
        "document_type": "ID",
        "first_name": "Rojit",
        "last_name": "Test",
        "phone": "91 2234567890",
        "email": "testing@ing.com"
    },
 
    "description": "test description",
    "client_ip": "123.123.123.123",
    "back_url": "https://www.lime-pay.com/deposit_cancelled",
    "success_url": "https://www.lime-pay.com/deposit_completed",
    "error_url": "https://www.lime-pay.com/deposit_error",
    "notification_url": "https://www.lime-pay.com/limepay/notify",
    "logo": "https://www.lime-pay.com/limepay.png",
    "test": false,
    "mobile": false,
    "language": "en"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://payment-stg.lime-pay.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI1Njk4Mjg2NSIsImlhdCI6MTcxNDAwNDExMSwiZXhwIjoxNzE1MzAwMTExLCJsYW5ndWFnZSI6InB0In0.m_veUauWLd5oFp9vcVd6q7Sa-ou6__12U5LkqF5XdDm1r0-tonU83KmUJ15FTrcf/IN/UI/4731/10881",
    "iframe": true,
    "deposit_id": 301245385,
    "user_id": "11",
    "merchant_invoice_id": "postmanTest701370365",
    "payment_info": {
        "type": "VOUCHER",
        "payment_method": "UI",
        "payment_method_name": "UPI",
        "amount": 1000.00,
        "currency": "INR",
        "expiration_date": "2024-05-01 22:55:08",
        "created_at": "2024-04-25 00:15:08",
        "metadata": {}
    }
}
```

{% endtab %}
{% endtabs %}

### UPI  Seamless

\
This method requires the field listed below to generate deposit successfully

{% hint style="info" %}
The UPI Seamless payment method is only available using the OneShot integration as all fields must be sent.
{% endhint %}

<table><thead><tr><th width="409">Field</th><th>Required?</th></tr></thead><tbody><tr><td><code>Country</code></td><td>Yes</td></tr><tr><td><code>Amount</code></td><td>Yes</td></tr><tr><td><code>Payer[]</code></td><td>Yes</td></tr><tr><td><code>payment_method</code></td><td>Yes</td></tr><tr><td><code>reported_info[].bank_account_number</code></td><td>Yes, see example below<br><code>"bank_account_number"</code>= VPA (UPI ID)</td></tr></tbody></table>

{% hint style="success" %}
VPA is the technical term used for the identifier of the UPI Accounts, for UX and user-facing views, use “UPI ID” instead
{% endhint %}

{% hint style="warning" %}
VPA Regex: ^\[a-zA-Z0-9.\_\\-]{2,50}@\[a-zA-Z]{2,50}$
{% endhint %}

Payer object requirements For UPI Seamless

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

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

```json
{
    "invoice_id" : "{{invoiceId}}",
    "amount": "500",
    "country": "IN",
    "currency": "INR",
    "payer": {
        "document": "1233131313",
        "document_type": "ID",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "91 2234567890",
        "email": "testing@ing.com"
    },
    "payment_method": "UIS",
    "reported_info": {
        "bank_account_number": "test@paymt"
    },
    "description": "test description",
    "client_ip": "123.123.123.123",
    "back_url": "https://www.lime-pay.com/deposit_cancelled",
    "success_url": "https://www.lime-pay.com/deposit_completed",
    "error_url": "https://www.lime-pay.com/deposit_error",
    "notification_url": "https://www.lime-pay.com/limepay/notify",
    "logo": "https://www.lime-pay.com/limepay.png",
    "test": true,
    "mobile": false,
    "language": "en"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://payment.lime-pay.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI4MzMyMzY5NzAiLCJpYXQiOjE3MTM5NTc1OTUsImV4cCI6MTcxNTI1MzU5NSwibGFuZ3VhZ2UiOiJwdCJ9.7URAL4pNP8ARSoBiBJJe0dknC6US2LXra6Q6ginDtH1AZLnsCfOQsPQA-133rtFP/IN/UIS/8261/4",
    "iframe": true,
    "deposit_id": 991814322,
    "merchant_invoice_id": "postmanTest934792442",
    "payment_info": {
        "type": "VOUCHER",
        "payment_method": "UIS",
        "payment_method_name": "UPI Seamless",
        "amount": 500.00,
        "currency": "INR",
        "expiration_date": "2024-04-25 11:19:51",
        "created_at": "2024-04-24 11:19:51",
        "metadata": {
            "qr_code": "data:image/png;base64,encodedimage",
            "provider_link": "upi://pay?pa=paymentdata"
        }
    }
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For Customizeable UPI Seamless checkout, Kindly ensure that both the `qr_code` and `provider_link` is displayed on the checkout. The `provider_link` is the intent button that allows end-users make payment right from  any of their mobile app. The `provider_link` is a deep link, therefore, make sure to open it outside of any containers/mobile apps.
{% endhint %}

<figure><img src="/files/JVe2X9VA6pPwNjdiIV0d" alt=""><figcaption><p>UPI Seamless checkout.</p></figcaption></figure>

### iCash One

{% hint style="info" %}
ICash supports both **wallet** (balance-based) and **voucher** (prepaid code) modes in India.
{% endhint %}

#### Required Fields

| Field            | Type   | Required |
| ---------------- | ------ | -------- |
| `country`        | string | Yes      |
| `amount`         | number | Yes      |
| `payment_method` | string | Yes      |
| `payer[email]`   | string | Yes      |
| `payer[phone]`   | string | Yes      |

#### Request Example

```json
{
  "country": "IN",
  "amount": 1000,
  "currency": "INR",
  "payment_method": "ICSH",
  "merchant_invoice_id": "INV-001",
  "payer": {
    "email": "user@example.com",
    "phone": "919876543210"
  }
}
```

#### Response Example

```json
{
  "checkout_type": "ONE_SHOT",
  "redirect_url": "https://payment.checkoutogate.com/v1/checkout/...",
  "iframe": true,
  "deposit_id": 1597517845,
  "merchant_invoice_id": "INV-001",
  "payment_info": {
    "type": "VOUCHER",
    "payment_method": "ICSH",
    "payment_method_name": "ICash",
    "amount": 1000,
    "currency": "INR",
    "expiration_date": "2026-06-18 21:36:50",
    "created_at": "2026-06-18 09:36:50",
    "metadata": {
      "qr_code": "data:image/png;base64,...",
      "provider_link": "https://payments.lime-pay.com/deposit/..."
    }
  }
}
```

{% hint style="warning" %}
Both the `qr_code` and `provider_link` should be displayed on the checkout. The `provider_link` opens the iCash app or web flow to complete the payment.
{% endhint %}

***

### Discover the Payment Flows Behind Our Top Methods! 🚀

<figure><img src="/files/B912xWX9aZUReISpMmxK" alt=""><figcaption><p>UPI Seamless Flow</p></figcaption></figure>


# Indonesia

Check the list of Payment Methods available on Indonesia

## Payment Methods

<table><thead><tr><th width="110.875" align="center">Icon</th><th width="183" align="center">payment_method</th><th width="139">Name</th><th width="125" align="center">Flow</th><th width="186" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"> <img src="/files/-MZmPuB5xvap1KeEj1jP" alt="" data-size="line"></td><td align="center"><code>TR</code></td><td>Bank Transfer</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td></tr><tr><td align="center"><img src="/files/24j0lZzZhy41nbOJ3WmI" alt="" data-size="line"></td><td align="center"><code>QRS</code></td><td>QRIS</td><td align="center"><code>REDIRECT</code></td><td align="center">VOUCHER</td></tr><tr><td align="center"><img src="/files/UEVOgY69xh1AoZlDr7r6" alt="" data-size="line"></td><td align="center"><code>DANA</code></td><td>Dana Wallet</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td></tr><tr><td align="center"><img src="/files/ZPVTeekLWGb63iW3Vszy" alt="" data-size="line"></td><td align="center"><code>OVO</code></td><td>OVO Wallet</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td></tr><tr><td align="center"><img src="/files/1wmoJLHqNvETDTeOFXD6" alt="" data-size="line"></td><td align="center"><code>SPAY</code></td><td>ShopeePay</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td></tr><tr><td align="center"><img src="/files/Qh4RkKYQ9tUD9iwt3JcL" alt="" data-size="line"></td><td align="center"><code>LINK</code></td><td>LinkAja</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td></tr><tr><td align="center"><img src="/files/X7pNI5Cophgxa4KYqFTd" alt="" data-size="line"></td><td align="center"><code>GPY</code></td><td>GoPay</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td></tr><tr><td align="center"><img src="/files/iB0LQRt9sHIBQkavEL9o" alt="" data-size="line"></td><td align="center"><code>BCA</code></td><td>BCA Digital</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="127" align="center">country</th><th width="122" align="center">amount</th><th width="114" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>country</code></td><td align="center"><code>amount</code></td><td align="center"><code>payer[]</code></td><td align="center"><code>payment_method</code></td></tr><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="123" align="center">document</th><th align="center">email</th><th align="center">first_name</th><th align="center">last_name</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>document</code></td><td align="center"><code>email</code></td><td align="center"><code>first_name</code></td><td align="center"><code>last_name</code></td></tr><tr><td>All</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 %}


# Japan

Check the list of Payment Methods available on Japan

{% hint style="warning" %}
At the moment, the payment methods listed for Japan are only available for certain industries. Please contact your Account Manager to learn more about eligibility and available options for your business.
{% endhint %}

## Payment Methods

<table data-header-hidden><thead><tr><th width="101" align="center">Icon</th><th width="117" align="center">payment_method</th><th>Name</th><th width="123" align="center">Flow</th><th width="178" align="center">Payment Type</th><th align="center">Available for test</th></tr></thead><tbody><tr><td align="center"><a href="https://resources.directa24.com/cashin/payment_method/square/TR.svg"><img src="/files/-MZmPuB5xvap1KeEj1jP" alt="" data-size="line"></a> </td><td align="center"><code>TR</code></td><td>Bank Transfer</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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` | `client_ip` |
| ------------------- | :-------: | :------: | :-------: | :--------------: | :---------: |
| All                 |    Yes    |    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 %}

***

### Discover the Payment Flows Behind Our Top Methods! 🚀

<figure><img src="/files/JhvbYmNJJyosRhbYAoNE" alt=""><figcaption><p>Bank Transfer Flow</p></figcaption></figure>


# Malaysia

Check the list of Payment Methods available on Malaysia

## Payment Methods

<table><thead><tr><th width="98" align="center">Icon</th><th width="128" align="center">payment_method</th><th width="127">Name</th><th width="119" align="center">Flow</th><th width="172" align="center">Payment Type</th><th align="center">Iframe supported</th></tr></thead><tbody><tr><td align="center"><img src="/files/HodAmCXj9PiZdJllnX3x" alt="" data-size="line"></td><td align="center"><code>FPX</code></td><td>FPX</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/GxvNBz6BOLWPupymVV3A" alt="" data-size="line"></td><td align="center"><code>SPAY</code></td><td>ShopeePay</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/jw2UpRrCyybG8aMhOwEF" alt="" data-size="line"></td><td align="center"><code>TNG</code></td><td>Touch'n Go</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/lmGSRtxryXBqT8k7M8bu" alt="" data-size="line"></td><td align="center"><code>GRB</code></td><td>Grab</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/uCHHhQGZXm9nWQnWiOFv" alt=""></td><td align="center"> <code>BST</code></td><td>Boost</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">Yes</td></tr><tr><td align="center"> <img src="/files/-MZmPuB5xvap1KeEj1jP" alt="" data-size="line"></td><td align="center"><code>TR</code></td><td>Bank Transfer</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/bTVnlafF6Qhc5fm3bidQ" alt="" data-size="line"></td><td align="center"><code>DN</code></td><td>DuitNow</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/a2vbwVbdhCixGkmJEQk9" alt="Bigpay" data-size="line"></td><td align="center"><code>BGP</code></td><td>Bigpay</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/z4YSUgQEwt71egwrbA0A" alt="MAE by Maybank" data-size="line"></td><td align="center"><code>MAE</code></td><td>MAE by Maybank</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/prbKVJml3WwRX8a6qS9c" alt="" data-size="line"></td><td align="center"><code>BY</code></td><td>CIMB</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/ImC9GlVIjfRGzu6rIjHF" alt="" data-size="original"></td><td align="center"><code>HO</code></td><td>Hong Leong Bank</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/jmuSckaW7pwfx6d4Xg6t" alt="" data-size="line"></td><td align="center"><code>MY</code></td><td>Maybank</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/ZyFiH0Q5RoGXcUHtQO0X" alt="" data-size="line"></td><td align="center"><code>PU</code></td><td>Public Bank</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/dC42i6siB0MCH7p50A3l" alt="" data-size="line"></td><td align="center"><code>RH</code></td><td>RHB</td><td align="center"><code>REDIRECT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/ZMAamwkYwWDtwJHAEzbK" alt="" data-size="original"></td><td align="center"><code>BSN</code></td><td>Bank Simpanan Nasional</td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/IzTxBK5OHTWMIMcmUAc4" alt="" data-size="original"></td><td align="center"><code>AFB</code></td><td>Affin Bank </td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/ipaIXGxEI9aCGeGlSJ4X" alt="" data-size="original"></td><td align="center"><code>ARGO</code></td><td>Agrobank</td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/rBn9q6fyWfKq4NkgWdSO" alt="" data-size="original"></td><td align="center"><code>ABMB</code></td><td>Alliance Bank</td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/RWInzbTvIkBbh07TfHQ8" alt="" data-size="original"></td><td align="center"><code>MB</code></td><td>AmBank</td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/GEZq1m96BeJkqwx7xQQt" alt="" data-size="original"></td><td align="center"><code>IM</code></td><td>Bank Islam</td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/PZnziabI901pWLCFi40O" alt="" data-size="original"></td><td align="center"><code>BKRM</code></td><td>Bank Kerjasama Rakyat</td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/lJX3mYCthLlm1QLH86qD" alt="" data-size="original"></td><td align="center"><code>BMMB</code></td><td>Bank Muamalat</td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/quFLWk7ZXddC2q2R8tM3" alt="" data-size="original"></td><td align="center"><code>HSM</code></td><td>HSBC</td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/pnNHZmxHUABzMR2DGRZK" alt="" data-size="original"></td><td align="center"><code>KFH</code></td><td>Kuwait Finance House</td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/6YfDvYQinmFDP1x3RhX7" alt="" data-size="original"></td><td align="center"><code>OCBC</code></td><td>OCBC</td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/DHCxumtPhsPg0S1s3bvq" alt="" data-size="original"></td><td align="center"><code>SCM</code></td><td>Standard Chartered </td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/cBgDHYbLBrDu51LPaHwS" alt="" data-size="original"></td><td align="center"><code>UOB</code></td><td>United Overseas Bank </td><td align="center"><code>REDIRECT</code><br><code>ONESHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="113" align="center">country</th><th width="118" align="center">amount</th><th width="145" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>country</code></td><td align="center"><code>amount</code></td><td align="center"><code>payer[]</code></td><td align="center"><code>payment_method</code></td></tr><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="124" align="center">document</th><th width="107" align="center">email</th><th align="center">first_name</th><th align="center">last_name</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>document</code></td><td align="center"><code>email</code></td><td align="center"><code>first_name</code></td><td align="center"><code>last_name</code></td></tr><tr><td>All</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 %}


# Pakistan

Check the list of Payment Methods available in Pakistan

## Payment Methods

<table><thead><tr><th width="97" align="center">Icon</th><th width="223" align="center">payment_method</th><th width="127">Name</th><th width="119" align="center">Flow</th><th width="172" align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/cHuI5wjOcDhvp2MosJqD" alt="" data-size="line"></td><td align="center"><code>EPS</code></td><td>Easypaisa</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td></tr><tr><td align="center"><img src="/files/BwA4nZIlso3TMG7hUTTo" alt="" data-size="line"></td><td align="center"><code>JZC</code></td><td>Jazzcash</td><td align="center"><code>REDIRECT</code></td><td align="center">WALLET</td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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

<table><thead><tr><th width="182.3126220703125">Payment Method Name</th><th width="106.3802490234375" align="center">document</th><th width="91.296875" align="center">email</th><th width="94.8853759765625" align="center">first_name</th><th width="122.078125" align="center">last_name</th><th align="center">phone</th></tr></thead><tbody><tr><td>All</td><td align="center">Yes</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 %}


# South Korea

## Payment Methods

<table><thead><tr><th width="138" align="center">Icon</th><th width="169" align="center">payment_method</th><th width="139">Name</th><th width="125" align="center">Flow</th><th align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/lenLsqYcGHV7mfuL0VUg" alt="" data-size="original"></td><td align="center"><code>KKP</code></td><td>Kakaopay wallet</td><td align="center"><code>REDIRECT</code></td><td align="center"><code>WALLET</code></td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="136" align="center">country</th><th width="119" align="center">amount</th><th width="133" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>country</code></td><td align="center"><code>amount</code></td><td align="center"><code>payer[]</code></td><td align="center"><code>payment_method</code></td></tr><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="159.2291259765625" align="center">document</th><th width="131.7291259765625" align="center">email</th><th width="131.3333740234375" align="center">first_name</th><th align="center">last_name</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>document</code></td><td align="center"><code>email</code></td><td align="center"><code>first_name</code></td><td align="center"><code>last_name</code></td></tr><tr><td>All</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 %}


# Thailand

Check the list of Payment Methods available on Thailand

## Payment Methods

<table><thead><tr><th width="100" align="center">Icon</th><th align="center">payment_method</th><th>Name</th><th align="center">Flow</th><th align="center">Payment Type</th><th align="center">Available for test</th></tr></thead><tbody><tr><td align="center"><img src="https://resources.directa24.com/cashin/payment_method/square/QRT.svg" alt="" data-size="line"></td><td align="center"><code>QRT</code></td><td>Thai QR</td><td align="center"><code>ONE_SHOT</code></td><td align="center">VOUCHER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/9B4qmDdAy9pKgXm62rq3" alt="" data-size="line"></td><td align="center"><code>PPAY</code></td><td>Prompt pay</td><td align="center"><code>ONE_SHOT</code></td><td align="center">WALLET</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/-MZmPuB5xvap1KeEj1jP" alt="" data-size="line"></td><td align="center"><code>TR</code></td><td>Bank Transfer</td><td align="center"><code>ONE_SHOT</code></td><td align="center">BANK_TRANSFER</td><td align="center">Yes</td></tr><tr><td align="center"><img src="/files/Miyg4lBe38FBVaRn8M4P" alt="" data-size="line"></td><td align="center"><code>TRM</code></td><td>True Money</td><td align="center"><code>ONE_SHOT</code></td><td align="center">WALLET</td><td align="center">No</td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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_nameAll` |
| ------------------- | :--------: | :-----: | :----------: | :------------: |
| All                 |     Yes    |   Yes   |      Yes     |       Yes      |

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


# Turkey

Check the list of Payment Methods available in Turkey

## Payment Methods

<table><thead><tr><th width="137" align="center">Icon</th><th width="175" align="center">payment_method</th><th width="122.572265625">Name</th><th width="139" align="center">Flow</th><th align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"><img src="/files/-MZmPuB5xvap1KeEj1jP" alt="" data-size="line"></td><td align="center"><code>IBAN</code></td><td>IBAN</td><td align="center">REDIRECT</td><td align="center"><code>BANK_TRANSFER</code></td></tr><tr><td align="center"><img src="/files/JHhU56VYhAwilAoFFUBV" alt="" data-size="line"></td><td align="center"><code>PARO</code></td><td>ParolaPara</td><td align="center">REDIRECT</td><td align="center"><code>VOUCHER</code></td></tr><tr><td align="center"><img src="/files/RPoxpnqpqJMlyXJd8Ibp" alt="" data-size="line"></td><td align="center"><code>FST</code></td><td>FAST</td><td align="center">REDIRECT</td><td align="center"><code>VOUCHER</code></td></tr><tr><td align="center"><img src="/files/SvuXYl05l1wuaiRGzefb" alt="" data-size="line"></td><td align="center"><code>PYB</code></td><td>Paybol</td><td align="center">REDIRECT</td><td align="center"><code>WALLET</code></td></tr></tbody></table>

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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

<table data-header-hidden><thead><tr><th width="167.578125">Payment Method Name</th><th width="161.625" align="center">document</th><th align="center">email</th><th align="center">first_name</th><th align="center">last_name</th><th align="center">Adress</th><th align="center">State</th><th align="center">State</th><th align="center">City</th><th align="center">Zip</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>document</code></td><td align="center"><code>email</code></td><td align="center"><code>first_name</code></td><td align="center"><code>last_name</code></td><td align="center">Adress</td><td align="center">State</td><td align="center">State</td><td align="center">City</td><td align="center">ZIP</td></tr><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td></tr></tbody></table>

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


# Vietnam

Check the list of Payment Methods available on Vietnam

## Payment Methods

<table><thead><tr><th width="138" align="center">Icon</th><th width="169" align="center">payment_method</th><th width="139">Name</th><th width="125" align="center">Flow</th><th align="center">Payment Type</th></tr></thead><tbody><tr><td align="center"> <img src="https://resources.directa24.com/cashin/payment_method/square/TR.svg" alt="https://resources.directa24.com/cashin/payment_method/square/TR.svg" data-size="line"></td><td align="center"><code>TR</code></td><td>Bank Transfer</td><td align="center"><code>ONE_SHOT</code></td><td align="center"><code>BANK_DEPOSIT</code></td></tr><tr><td align="center"><img src="/files/zjwDeb7sTTJW5uYzKCT4" alt="" data-size="line"></td><td align="center"><code>MOM</code></td><td>MOMO</td><td align="center"><code>ONE_SHOT</code></td><td align="center"><code>VOUCHER</code></td></tr><tr><td align="center"><img src="/files/HpoWcXjhZDgXz3utfPPB" alt="" data-size="line"></td><td align="center"><code>ZA</code></td><td>ZaloPay</td><td align="center"><code>ONE_SHOT</code></td><td align="center"><code>WALLET</code></td></tr><tr><td align="center"><img src="/files/E23MbUwpjmVb9W4R7Jox" alt="" data-size="line"></td><td align="center"><code>VQR</code></td><td>VietQR</td><td align="center"><code>ONE_SHOT</code></td><td align="center"><code>VOUCHER</code></td></tr><tr><td align="center"><img src="/files/N52zMV7G5OiwH1RdV21N" alt="" data-size="line"></td><td align="center"><code>VTLP</code></td><td>ViettelPay</td><td align="center"><code>ONE_SHOT</code></td><td align="center"><code>VOUCHER</code></td></tr><tr><td align="center"><img src="/files/1wmoJLHqNvETDTeOFXD6" alt="" data-size="line"></td><td align="center"><code>SPAY</code></td><td>ShopeePay</td><td align="center"><code>ONE_SHOT</code></td><td align="center"><code>WALLET</code></td></tr></tbody></table>

{% hint style="info" %}
Using `Payment_method: TR` code, clients will have the opportunity to select any bank from a comprehensive list of all banks available in Vietnam, as all bank options will be accessible.
{% endhint %}

{% hint style="success" %}
Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) 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)

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="136" align="center">country</th><th width="119" align="center">amount</th><th width="133" align="center">payer[]</th><th align="center">payment_method</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>country</code></td><td align="center"><code>amount</code></td><td align="center"><code>payer[]</code></td><td align="center"><code>payment_method</code></td></tr><tr><td>All</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td><td align="center">Yes</td></tr></tbody></table>

### Payer object requirements

<table data-header-hidden><thead><tr><th>Payment Method Name</th><th width="159.2291259765625" align="center">document</th><th width="131.7291259765625" align="center">email</th><th width="131.3333740234375" align="center">first_name</th><th align="center">last_name</th></tr></thead><tbody><tr><td>Payment Method Name</td><td align="center"><code>document</code></td><td align="center"><code>email</code></td><td align="center"><code>first_name</code></td><td align="center"><code>last_name</code></td></tr><tr><td>All</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 %}


# 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="/files/-MDBHnzNY05ffYAzGwV_" alt="" data-size="original"> | The deposit is created but the customer hasn't opened the link yet.                                                                                                                                                                                                                         |
| <img src="/files/-MDBHD__gsa_CT3H-8Z2" 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="/files/-MDBIKAz8rS9s0p0oaai" 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="/files/-M9Uq6hh3MZ301JtlBh4" alt="" data-size="original"> | The deposit is created with all the information required and it is awaiting on customer's payment.                                                                                                                                                                                          |
| <img src="/files/-M9Usf-KMOsFfbQJ_ZoQ" alt="" data-size="original"> | The deposit didn't pass our anti-fraud systems and will be retained until manual review.                                                                                                                                                                                                    |
| <img src="/files/-MDBH_7RIHxUC25-qIS1" alt="" data-size="original"> | The deposit has reached its expiration time and the user didn't pay.                                                                                                                                                                                                                        |
| <img src="/files/-M9UsJ4Co_cg-RzJZT6c" alt="" data-size="original"> | The deposit has been cancelled by the customer or it has been 7 days after the expiration.                                                                                                                                                                                                  |
| <img src="/files/-M9UsDlL5PDQXBDL5CUD" alt="" data-size="original"> | The deposit has been completed and the money was credited to your account.                                                                                                                                                                                                                  |

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

## Refunds Status Codes

|                                Status                               | Description                                                                           |
| :-----------------------------------------------------------------: | ------------------------------------------------------------------------------------- |
| <img src="/files/-M9Uq6hh3MZ301JtlBh4" alt="" data-size="original"> | The refund is created and is pending to be processed. It can still be cancelled.      |
| <img src="/files/-ME_izqMi9S4uIPsWPjR" alt="" data-size="original"> | The refund is pending for you to provide more information. It can still be cancelled. |
| <img src="/files/-MDQyQCx2cX3EhoAitEv" alt="" data-size="original"> | The refund has been sent to the bank for processing. It can't be cancelled anymore.   |
| <img src="/files/-M9UsJ4Co_cg-RzJZT6c" alt="" data-size="original"> | The refund has been manually cancelled. Final status.                                 |
| <img src="/files/-MDNZ67x7s7LgmAyG4YI" alt="" data-size="original"> | The refund has been rejected by the bank. Final status.                               |
| <img src="/files/-M9UsDlL5PDQXBDL5CUD" 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](#refund-api-error-codes)
* `9xx` - [Credit Card errors](#pci-deposit-api-error-codes)

### Deposit API Error Codes

<table><thead><tr><th align="center">API Code</th><th width="107" 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="/pages/-M7F-Uc7ZKhYsNpqrSof#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="/pages/-M7ic8P-kyDs3BecUOKC">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="/pages/-M7F-Uc7ZKhYsNpqrSof#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="/pages/-M7hYEvN5DB8MxUgRUuA">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="/pages/-M7F-Uc7ZKhYsNpqrSof#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">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">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">FINANCIAL_CAPACITY</td><td>The transaction cannot be processed as the user has reached their financial capacity, please provide proof of funds</td><td>The transaction cannot be processed as the user has reached their financial capacity, please provide proof of funds</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="/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="/pages/-M7hYU7T42-pbXYXjrnh#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="/pages/-M7hYU7T42-pbXYXjrnh#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="/pages/-M7hYU7T42-pbXYXjrnh#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="/pages/-M7hYU7T42-pbXYXjrnh#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="/pages/-M7hYU7T42-pbXYXjrnh#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="/pages/-M7hYU7T42-pbXYXjrnh#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>

### 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`&#x20;
{% endhint %}

<table><thead><tr><th width="145" 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><tr><td align="center">400</td><td align="center">115</td><td>Invalid document format</td><td>Document format rejections</td></tr><tr><td align="center">400</td><td align="center">116</td><td>Sportsman User</td><td>Sportsman User</td></tr><tr><td align="center">400</td><td align="center">117</td><td>Related to Sportsman User</td><td>Related to Sportsman User</td></tr><tr><td align="center">400</td><td align="center">118</td><td>National Sanction Lists</td><td>User has been identified on national sanction lists</td></tr><tr><td align="center">400</td><td align="center">119</td><td>International Sanction Lists</td><td>User has been identified on international sanction lists</td></tr><tr><td align="center">400</td><td align="center">120</td><td>Regulatory reasons</td><td>Rejected due to regulatory reasons</td></tr><tr><td align="center">400</td><td align="center">121</td><td>Velocity check</td><td>Rejected due to velocity check</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 Lime-Pay 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 benficiary'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.lime-pay.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@lime-pay.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. Treat it as a password.

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

## 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: 223a9dd4784726f1536k23nda7dc69155a57612c5c3c1e1b429c367a5eee67cf

​

### 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\": \"IN\",  \"amount\": 2000,  \"currency\": \"INR\",  \"email\": \"test@test.com\", \"notification_url\": \"http:\\/\\/lime-pay.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": "IN",
"amount": 2000,
"currency": "INR",
"email": "test@test.com",
"notification_url": "http://www.lime-pay.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\": \"IN\",  \"amount\": 2000,  \"currency\": \"INR\",  \"email\": \"test@test.com\", \"notification_url\": \"http:\\/\\/www.lime-pay.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.lime-pay.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 Lime-Pay CASHOUTS API login key                                                          |
| pass<mark style="color:red;">\*</mark>              | string  | Your Lime-Pay 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\_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 Cashout request successfully created." %}

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

{% endtab %}

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

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

{% endtab %}

{% tab title="412 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 %}
{% endtabs %}

## Request Fields Description

| Field                  | Format                         | Description                                                                                                                                        |                                             Validations                                             |
| ---------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------: |
| login                  | string (max length: 32)        | Your Lime-Pay **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 Lime-Pay  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](/knowledge-base/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](/knowledge-base/countries-specifications#currencies)             |
| document\_id           | string (max length: 40)        | Beneficiary’s personal identification number                                                                                                       |            [See document validations](/knowledge-base/countries-specifications#documents)           |
| document\_type         | string (maxLength: 15)         | Beneficiary’s personal identification number type                                                                                                  |         [See document types validations](/knowledge-base/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](/knowledge-base/countries-specifications#emails-validations)         |
| phone                  | string (maxLength: 20)         | Beneficiary's phone number                                                                                                                         | [See phone number validations](/knowledge-base/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](/knowledge-base/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]`                                           |

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


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

![](/files/-M9v7i6l28PPXX9ssThc)

## Example Notifications

```
    date=2023-03-12%2020%3A26%3A11
    &bank_reference_id=
    &comments=
    &external_id=cashoutV33243281
    &control=A4CFF64E78C4BD01F8BJSI4AFF04632EC4A33CC61BD6BBD156BA1289897892EB
    &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 = "cashoutID123334";
      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 = 'cashoutID123334';
$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 = "cashoutID123334";
 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:

![](/files/-MkIVGqDDe8OYIKHdJ0O)

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

![](/files/-MkIVm1exkvCAAucF04N)


# 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.lime-pay.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 Lime-Pay CASHOUTS API login key                                                                       |
| pass<mark style="color:red;">\*</mark>         | string | Your Lime-Pay 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 Lime-Pay 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              |

## 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 Lime-Pay **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 Lime-Pay **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 Lime-Pay 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` |

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

## Cashout Status Response

### Response Example

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

{
    "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                                                                                                                  |
| `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                                                                                                |

## 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](/files/-MEhM7tjzaYE5_JN6TKA)

{% 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 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.lime-pay.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 LimePay CASHOUTS API login key                                                                       |
| pass<mark style="color:red;">\*</mark>        | string | Your LimePay 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 LimePay 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: 2e5023770760ka0a02230bff1a6dab934fe3b47a5e3d43854b58676600ee3868 

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

### Request Fields Description

<table><thead><tr><th>Field</th><th width="239.33333333333331">Format</th><th>Description</th></tr></thead><tbody><tr><td><code>login</code></td><td>String. Length 32 max</td><td>Your Lime-Pay <strong>CASHOUTS</strong> API Key, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials</td></tr><tr><td><code>pass</code></td><td>String. Length 32 max</td><td>Your Lime-Pay <strong>CASHOUTS</strong> API Passphrase, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials</td></tr><tr><td><code>cashout_id</code></td><td>Number</td><td>Identifier of the cashout on Lime-Pay end. It is the one returned by the <a href="/pages/-M9v7BbfX1Lno6zliytq">Create Cashout Endpoint</a></td></tr><tr><td><code>status</code></td><td>String</td><td>Status to be assigned to the cashout. Valid values: <code>PENDING</code>, <code>ON_HOLD</code></td></tr></tbody></table>

### 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](/files/-MEhM7tjzaYE5_JN6TKA)

{% 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.lime-pay.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 LimePay CASHOUTS API login key                                                               |
| pass<mark style="color:red;">\*</mark>         | string | Your LimePay 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 LimePay 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 Lime-Pay **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 Lime-Pay **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 Lime-Pay 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.lime-pay.com/v3/banks?country={ISO_CODE}`

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

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

<details>

<summary>200 Bank list successfully retrieved</summary>

```
[
    {
        "code": 11,
        "name": "First Bank of Nigeria Plc"
    },
    {
        "code": 29,
        "name": "Lotus Bank"
    },
    {
        "code": 30,
        "name": "Heritage Bank"
    },
    {
        "code": 31,
        "name": "PremiumTrust Bank"
    },
    {
        "code": 32,
        "name": "Union Bank Nigeria Plc"
    },
    {
        "code": 33,
        "name": "United Bank for Africa Plc"
    },
    {
        "code": 35,
        "name": "WEMA Bank Plc"
    },
    {
        "code": 36,
        "name": "Optimus Bank"
    },
    {
        "code": 39,
        "name": "Stanbic IBTC Plc"
    },
    {
        "code": 44,
        "name": "Access Bank Plc"
    },
    {
        "code": 50,
        "name": "Ecobank Nigeria"
    },
    {
        "code": 57,
        "name": "Zenith Bank International"
    },
    {
        "code": 58,
        "name": "Guaranty Trust Bank Plc"
    },
    {
        "code": 70,
        "name": "Fidelity Bank Plc"
    },
    {
        "code": 82,
        "name": "Keystone Bank Ltd"
    },
    {
        "code": 214,
        "name": "First City Monument Bank"
    },
    {
        "code": 215,
        "name": "Unity Bank Plc"
    },
    {
        "code": 232,
        "name": "Sterling Bank Plc"
    },
    {
        "code": 301,
        "name": "Jaiz Bank"
    },
    {
        "code": 70022,
        "name": "Stb Mortgage Bank"
    },
    {
        "code": 70026,
        "name": "Fha Mortgage Bank Ltd"
    },
    {
        "code": 90113,
        "name": "Microvis Microfinance Bank"
    },
    {
        "code": 90136,
        "name": "Baobab Microfinance Bank"
    },
    {
        "code": 90155,
        "name": "La Fayette Microfinance Bank"
    },
    {
        "code": 90170,
        "name": "Rahama Microfinance Bank"
    },
    {
        "code": 90175,
        "name": "Rubies Microfinance Bank"
    },
    {
        "code": 90267,
        "name": "Kuda Microfinance Bank"
    },
    {
        "code": 90275,
        "name": "Meridian Microfinance Bank"
    },
    {
        "code": 90281,
        "name": "Mint-Finex MICROFINANCE BANK"
    },
    {
        "code": 90283,
        "name": "Thrive Microfinance Bank"
    },
    {
        "code": 90291,
        "name": "Halacredit Microfinance Bank"
    },
    {
        "code": 90296,
        "name": "Polyuwanna Microfinance Bank"
    },
    {
        "code": 90302,
        "name": "Sunbeam Microfinance Bank"
    },
    {
        "code": 90305,
        "name": "Sulsap Microfinance Bank"
    },
    {
        "code": 90316,
        "name": "Bayero Microfinance Bank"
    },
    {
        "code": 90319,
        "name": "Bonghe Microfinance Bank"
    },
    {
        "code": 90330,
        "name": "Fame Microfinance Bank"
    },
    {
        "code": 90337,
        "name": "Iyeru Okin Microfinance Bank Ltd"
    },
    {
        "code": 90340,
        "name": "Stockcorp Microfinance Bank"
    },
    {
        "code": 90341,
        "name": "Unilorin Microfinance Bank"
    },
    {
        "code": 90343,
        "name": "Citizen Trust Microfinance Bank Ltd"
    },
    {
        "code": 90345,
        "name": "Oau Microfinance Bank Ltd"
    },
    {
        "code": 90349,
        "name": "Nasarawa Microfinance Bank"
    },
    {
        "code": 90350,
        "name": "Illorin Microfinance Bank"
    },
    {
        "code": 90353,
        "name": "Isuofia Microfinance Bank"
    },
    {
        "code": 90370,
        "name": "Ilasan Microfinance Bank"
    },
    {
        "code": 90371,
        "name": "Agosasa Microfinance Bank"
    },
    {
        "code": 90379,
        "name": "Peniel Micorfinance Bank Ltd"
    },
    {
        "code": 90380,
        "name": "Kredi Money Microfinance Bank"
    },
    {
        "code": 90383,
        "name": "Manny Microfinance bank"
    },
    {
        "code": 90390,
        "name": "Parkway Mf Bank"
    },
    {
        "code": 90392,
        "name": "Mozfin Microfinance Bank"
    },
    {
        "code": 90397,
        "name": "Chanelle Bank"
    },
    {
        "code": 90400,
        "name": "Finca Microfinance Bank"
    },
    {
        "code": 90402,
        "name": "Peace Microfinance Bank"
    },
    {
        "code": 90403,
        "name": "Uda Microfinance Bank"
    },
    {
        "code": 90405,
        "name": "Moniepoint Microfinance Bank"
    },
    {
        "code": 90413,
        "name": "Benysta Microfinance Bank"
    },
    {
        "code": 90414,
        "name": "Crutech Microfinance Bank"
    },
    {
        "code": 90415,
        "name": "Calabar Microfinance Bank"
    },
    {
        "code": 90416,
        "name": "Chibueze Microfinance Bank"
    },
    {
        "code": 90417,
        "name": "Imowo Microfinance Bank"
    },
    {
        "code": 90418,
        "name": "Highland Microfinance Bank"
    },
    {
        "code": 90419,
        "name": "Winview Bank"
    },
    {
        "code": 90420,
        "name": "Letshego MFB"
    },
    {
        "code": 90421,
        "name": "Izon Microfinance Bank"
    },
    {
        "code": 90422,
        "name": "Landgold Microfinance Bank"
    },
    {
        "code": 90423,
        "name": "MAUTECH Microfinance Bank"
    },
    {
        "code": 90425,
        "name": "Banex Microfinance Bank"
    },
    {
        "code": 90426,
        "name": "Tangerine Bank"
    },
    {
        "code": 90427,
        "name": "Ebsu Microfinance Bank"
    },
    {
        "code": 90428,
        "name": "Ishie Microfinance Bank"
    },
    {
        "code": 90429,
        "name": "Crossriver Microfinance Bank"
    },
    {
        "code": 90430,
        "name": "Ilora Microfinance Bank"
    },
    {
        "code": 90431,
        "name": "Bluewhales Microfinance Bank"
    },
    {
        "code": 90432,
        "name": "Memphis Microfinance Bank"
    },
    {
        "code": 90433,
        "name": "Rigo Microfinance Bank"
    },
    {
        "code": 90434,
        "name": "Insight Microfinance Bank"
    },
    {
        "code": 90435,
        "name": "Links Microfinance Bank"
    },
    {
        "code": 90436,
        "name": "Spectrum Microfinance Bank"
    },
    {
        "code": 90437,
        "name": "Oakland Microfinance Bank"
    },
    {
        "code": 90438,
        "name": "Futminna Microfinance Bank"
    },
    {
        "code": 90439,
        "name": "Ibeto Microfinance Bank"
    },
    {
        "code": 90440,
        "name": "Cherish Microfinance Bank"
    },
    {
        "code": 90441,
        "name": "Giwa Microfinance Bank"
    },
    {
        "code": 90445,
        "name": "Capstone Mf Bank"
    },
    {
        "code": 90446,
        "name": "Support Mf Bank"
    },
    {
        "code": 90449,
        "name": "Sls Mf Bank"
    },
    {
        "code": 90450,
        "name": "Kwasu Mf Bank"
    },
    {
        "code": 90451,
        "name": "Atbu Microfinance Bank"
    },
    {
        "code": 90452,
        "name": "Unilag Microfinance Bank"
    },
    {
        "code": 90453,
        "name": "Uzondu Mf Bank"
    },
    {
        "code": 90454,
        "name": "Borstal Microfinance Bank"
    },
    {
        "code": 90456,
        "name": "Oke-Aro Oredegbe Microfinance Bank Ltd"
    },
    {
        "code": 90459,
        "name": "Nice Microfinance Bank"
    },
    {
        "code": 90460,
        "name": "Oluyole Microfinance Bank"
    },
    {
        "code": 90461,
        "name": "Uniibadan Microfinance Bank"
    },
    {
        "code": 90462,
        "name": "Monarch Microfinance Bank"
    },
    {
        "code": 90470,
        "name": "DOT MICROFINANCE BANK"
    },
    {
        "code": 90478,
        "name": "Avuenegbe Microfinance Bank"
    },
    {
        "code": 90480,
        "name": "Cintrust Microfinance Bank"
    },
    {
        "code": 90481,
        "name": "Prisco Microfinance Bank"
    },
    {
        "code": 90484,
        "name": "Garki Microfinance Bank"
    },
    {
        "code": 90485,
        "name": "Safegate Microfinance Bank"
    },
    {
        "code": 90486,
        "name": "Fortress Microfinance Bank"
    },
    {
        "code": 90487,
        "name": "Kingdom College Microfinance Bank"
    },
    {
        "code": 90493,
        "name": "Iperu Microfinance Bank"
    },
    {
        "code": 90496,
        "name": "Radalpha Microfinance Bank"
    },
    {
        "code": 90497,
        "name": "Palmcoast Microfinance Bank"
    },
    {
        "code": 90498,
        "name": "Catland Microfinance Bank"
    },
    {
        "code": 90500,
        "name": "Gwong Microfinance Bank"
    },
    {
        "code": 90501,
        "name": "Boromu Microfinance Bank"
    },
    {
        "code": 90505,
        "name": "Nigeria Prisonsmicrofinance Bank"
    },
    {
        "code": 90508,
        "name": "Borno Renaissance Microfinance Bank"
    },
    {
        "code": 90509,
        "name": "Capitalmetriq Swift Microfinance Bank"
    },
    {
        "code": 90510,
        "name": "Umunnachi Microfinance Bank"
    },
    {
        "code": 90511,
        "name": "Cloverleaf Microfinance Bank"
    },
    {
        "code": 90512,
        "name": "Bubayero Microfinance Bank"
    },
    {
        "code": 90514,
        "name": "Umuchinemere Procredit Microfinance Bank"
    },
    {
        "code": 90519,
        "name": "Ibom Fadama Microfinance Bank"
    },
    {
        "code": 90520,
        "name": "Ic Globalmicrofinance Bank"
    },
    {
        "code": 90521,
        "name": "Foresight Microfinance Bank"
    },
    {
        "code": 90525,
        "name": "Triple A Microfinance Bank"
    },
    {
        "code": 90532,
        "name": "Ibolo Micorfinance Bank Ltd"
    },
    {
        "code": 90534,
        "name": "Polyibadan Microfinance Bank"
    },
    {
        "code": 90535,
        "name": "Nkpolu-Ust Microfinance"
    },
    {
        "code": 90538,
        "name": "Blue Investments Microfinance Bank"
    },
    {
        "code": 90542,
        "name": "Otuo Microfinance Bank Ltd"
    },
    {
        "code": 90543,
        "name": "Iwoama Microfinance Bank"
    },
    {
        "code": 90544,
        "name": "Aspire Microfinance Bank Ltd"
    },
    {
        "code": 90545,
        "name": "Abulesoro Microfinance Bank Ltd"
    },
    {
        "code": 90546,
        "name": "Ijebu-Ife Microfinance Bank Ltd"
    },
    {
        "code": 90548,
        "name": "Ally Microfinance Bank"
    },
    {
        "code": 90549,
        "name": "Kc Microfinance Bank"
    },
    {
        "code": 90550,
        "name": "Green Energy Microfinance Bank Ltd"
    },
    {
        "code": 90551,
        "name": "Fairmoney Microfinance Bank Ltd"
    },
    {
        "code": 90552,
        "name": "Ekimogun Microfinance Bank"
    },
    {
        "code": 90553,
        "name": "Consistent Trust Microfinance Bank Ltd"
    },
    {
        "code": 90554,
        "name": "Kayvee Microfinance Bank"
    },
    {
        "code": 90555,
        "name": "Bishopgate Microfinance Bank"
    },
    {
        "code": 90556,
        "name": "Egwafin Microfinance Bank Ltd"
    },
    {
        "code": 90557,
        "name": "Lifegate Microfinance Bank Ltd"
    },
    {
        "code": 90558,
        "name": "Shongom Microfinance Bank Ltd"
    },
    {
        "code": 90559,
        "name": "Shield Microfinance Bank Ltd"
    },
    {
        "code": 90560,
        "name": "TANADI MFB (CRUST)"
    },
    {
        "code": 90562,
        "name": "Cedar Microfinance Bank Ltd"
    },
    {
        "code": 90563,
        "name": "Balera Microfinance Bank Ltd"
    },
    {
        "code": 90564,
        "name": "Supreme Microfinance Bank Ltd"
    },
    {
        "code": 90565,
        "name": "Oke-Aro Oredegbe Microfinance Bank Ltd"
    },
    {
        "code": 90566,
        "name": "Okuku Microfinance Bank Ltd"
    },
    {
        "code": 90567,
        "name": "Orokam Microfinance Bank Ltd"
    },
    {
        "code": 90568,
        "name": "Broadview Microfinance Bank Ltd"
    },
    {
        "code": 90569,
        "name": "Qube Microfinance Bank Ltd"
    },
    {
        "code": 90570,
        "name": "Iyamoye Microfinance Bank Ltd"
    },
    {
        "code": 90571,
        "name": "Ilaro Poly Microfinance Bank Ltd"
    },
    {
        "code": 90572,
        "name": "Ewt Microfinance Bank"
    },
    {
        "code": 90573,
        "name": "Snow Microfinance Bank"
    },
    {
        "code": 90575,
        "name": "Firstmidas Microfinance Bank Ltd"
    },
    {
        "code": 90576,
        "name": "Octopus Microfinance Bank Ltd"
    },
    {
        "code": 90578,
        "name": "Iwade Microfinance Bank Ltd"
    },
    {
        "code": 90579,
        "name": "Gbede Microfinance Bank"
    },
    {
        "code": 90580,
        "name": "Otech Microfinance Bank Ltd"
    },
    {
        "code": 90589,
        "name": "Mercury MFB"
    },
    {
        "code": 100026,
        "name": "Carbon"
    }
]
```

</details>

<details>

<summary>Invalid Credentials</summary>

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

</details>

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

{% content-ref url="/pages/-MB7PYXof9ddP4AqFANg" %}
[African Countries](/api-documentation/cashouts-api/countries-validations/african-countries)
{% endcontent-ref %}

{% content-ref url="/pages/-MB7PYkuT6VUcSne0hnQ" %}
[Asian Countries](/api-documentation/cashouts-api/countries-validations/asian-countries)
{% endcontent-ref %}


# African Countries

Learn about the cashouts validations of the African countries

{% content-ref url="/pages/M4RXfLfh7w3Ds101CvnI" %}
[Cameroon](/api-documentation/cashouts-api/countries-validations/african-countries/cameroon)
{% endcontent-ref %}

{% content-ref url="/pages/N2a6DgOqbq0tQN8aLEce" %}
[Egypt](/api-documentation/cashouts-api/countries-validations/african-countries/egypt)
{% endcontent-ref %}

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

{% 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/XcInNpn5yQCVv8ZRUR5R" %}
[South Africa](/api-documentation/cashouts-api/countries-validations/african-countries/south-africa)
{% endcontent-ref %}


# Cameroon

Check the requirements and validations made over the cashouts on Cameroon

## 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](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID                                                               |
| `country`              | `CM`                                                                                       | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | XAF / `USD`                                                                                | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                               | Cashout amount                                                                          |
| `bank_account`         | See [validations below](#bank-account-validations)                                         | Beneficiary's bank account                                                              |
| `bank_code`            | See [bank codes](#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](/knowledge-base/countries-specifications#documents-validations) to check document types and validations.

## Example Request

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

## Bank Codes

| Bank                                                          | Code  |
| ------------------------------------------------------------- | ----- |
| MTN Cameroon                                                  | 10000 |
| Orange Cameroon                                               | 10004 |
| AFRILAND FIRST BANK                                           | 1     |
| BANQUE ATLANTIQUE CAMEROUN                                    | 5     |
| BANQUE DES ETATS D'AFRIQUE CENTRALE                           | 13    |
| BANQUE INTERNATIONALE DU CAMEROUN POUR L'EPARGNE ET LE CREDIT | 17    |
| BC PME SA                                                     | 18    |
| BGFIBANK CAMEROUN SA                                          | 19    |
| CITIBANK N.A                                                  | 20    |
| COMMERCIAL BANK OF CAMEROON                                   | 22    |
| CREDIT COMMUNAUTAIRE D'AFRIQUE S.A.                           | 30    |
| ECOBANK CAMEROUN SA.                                          | 31    |
| NATIONAL FINANCIAL CREDIT BANK S.A.                           | 31    |
| SCB CAMEROUN S.A.                                             | 33    |
| SOCIETE GENERALE CAMEROUN                                     | 34    |
| STANDARD CHARTERED BANK CAMEROON S.A.                         | 35    |
| UNION BANK OF CAMEROON LTD.                                   | 37    |
| UNITED BANK FOR AFRICA CAMEROON PLC                           | 38    |

{% 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 %}


# Egypt

Check the requirements and validations made over the cashouts on Egypt

## 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](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID                                                               |
| `country`              | `EG`                                                                                       | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `EGP` / `USD`                                                                              | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) |
| `Phone`                | String (max length: 100)                                                                   | Beneficiary phone number                                                                |
| `amount`               | Number with up to 2 decimals                                                               | Cashout amount                                                                          |
| `bank_code`            | See [bank codes](#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                                                                 |

## Document Validations

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

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "20000000001",
    "country": "EG",
    "amount": 500,
    "currency": "EGP",
    "phone": "201001231176",
    "bank_code": "10001", 
    "document_id": "12345678901234",
    "beneficiary_name": "John",
    "beneficiary_lastname": "Doe",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

| Bank             | Code  |
| ---------------- | ----- |
| Etisalat         | 10001 |
| Vodafone         | 10002 |
| Orange Cash      | 10003 |
| CIB Smart wallet | 10004 |

{% 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](/knowledge-base/countries-specifications#documents-validations)                                      | Beneficiary's document ID                                                               |
| `country`              | `GH`                                                                                                                            | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `GHS` / `USD`                                                                                                                   | See [currency codes](/knowledge-base/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                                                                 |

## Bank Account Validations

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

## Document Validations

[Click here](/knowledge-base/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 |

```
{
    "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 Codes

| Bank                                          | Code     |
| --------------------------------------------- | -------- |
| CENTRAL SECURITIES DEPOSITORY LIMITED         | 014      |
| ECOBANK GHANA                                 | 017      |
| TAKORADI INTERNATIONAL COMPANY                | 049      |
| UNITED BANK FOR AFRICA LTD                    | 050      |
| MTN Ghana                                     | 10000    |
| ATL Ghana                                     | 10003    |
| Telecel                                       | 10007    |
| Airtel Ghana                                  | 10006    |
| AirtelTigo                                    | 10101    |
| 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 |

{% 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 %}


# Ivory Coast

Check the requirements and validations made over the cashouts on Ivory coast

## 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](/knowledge-base/countries-specifications#documents-validations)                                      | Beneficiary's document ID                                                               |
| `country`              | `CI`                                                                                                                            | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `XOF` / `USD`                                                                                                                   | See [currency codes](/knowledge-base/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](#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`                | Numeric                                                                                                                         | Beneficiary's Phone Number                                                              |

## Document Validations

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

## Example Request

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

```json
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "30000000001",
    "country": "CI",
    "amount": 100,
    "currency": "XOF",
    "bank_account": "",
    "bank_code": "10000",
    "phone": "2250544845079",
    "document_id": "89237423356",
    "beneficiary_name": "User",
    "beneficiary_lastname": "Test",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

{% endtab %}
{% endtabs %}

{% 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 %}

## Bank Codes

| Bank               | Code  |
| ------------------ | ----- |
| MTN Ivory Coast    | 10000 |
| Orange Ivory Coast | 10004 |
| Wave               | 10007 |


# 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](/knowledge-base/countries-specifications#documents-validations)                                      | Beneficiary's document ID                                                               |
| `country`              | `KE`                                                                                                                            | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `KES` / `USD`                                                                                                                   | See [currency codes](/knowledge-base/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`                | Numeric                                                                                                                         | Beneficiary's Phone Number                                                              |

## Bank Account Validations

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

## Document Validations

[Click here](/knowledge-base/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 %}

{% 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 %}

## Bank Codes

| Bank        | Code  |
| ----------- | ----- |
| MPesa Kenya | 10000 |


# 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](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID                                                               |
| `country`              | `NG`                                                                                       | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `NGN` / `USD`                                                                              | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                               | Cashout amount                                                                          |
| `bank_account`         | See [validations below](#document-validations)                                             | Beneficiary's bank account                                                              |
| `bank_code`            | See [bank codes](/api-documentation/cashouts-api/endpoints/cashout-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](/knowledge-base/countries-specifications#documents-validations) to check document types and validations.

## Example Request

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

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

{% endtab %}

{% tab title="Response" %}

```
external_id=100365001A2538925094
cashout_id=197824123
date=2025-03-18 10:10:10
bank_reference_id=999999250318115805775951234567
comments=
control=50553B0A13419744FF8CFFAD6711829863B5152E702FCDB123456789735671
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
We now return session ID for cashouts in Nigeria as the bank\_reference\_id field in the API response as well as the API callback
{% endhint %}

## Bank Codes

{% 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 %}

| Bank                      | Bank Code |
| ------------------------- | --------- |
| Polaris Bank              | 8         |
| Taj Bank                  | 26        |
| Globus Bank               | 103       |
| Titan-Paystack            | 100039    |
| Paga                      | 327       |
| One Finance               | 100026    |
| GoMoney                   | 100022    |
| Keystone Bank Ltd         | 82        |
| Kuda Bank                 | 50211     |
| Zenith Bank International | 100034    |

{% 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](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID                                                               |
| `country`              | `ZA`                                                                                       | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `ZAR` / `USD`                                                                              | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                               | Cashout amount                                                                          |
| `bank_account`         | See [validations below](#bank-account-validations)                                         | Beneficiary's bank account                                                              |
| `bank_code`            | See [bank codes](#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](/knowledge-base/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"
}
```

{% 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 %}

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


# Tanzania

## 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](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID                                                               |
| `country`              | `TZ`                                                                                       | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `TZS` / `USD`                                                                              | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                               | Cashout amount                                                                          |
| `bank_account`         | See [validations below](#bank-account-validations)                                         | Beneficiary's bank account                                                              |
| `bank_code`            | See [bank codes](#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](/knowledge-base/countries-specifications#documents-validations) to check document types and validations.

## Example Request

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

{% 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 %}

## Bank Codes

| Bank          | Code  |
| ------------- | ----- |
| MPSA Tanznaia | 10000 |
| Airtel        | 10002 |
| Mixx by Yas   | 10004 |


# Uganda

## 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](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID                                                               |
| `country`              | `UG`                                                                                       | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `UGX` / `USD`                                                                              | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) |
| `amount`               | Number with up to 2 decimals                                                               | Cashout amount                                                                          |
| `bank_account`         | See [validations below](#bank-account-validations)                                         | Beneficiary's bank account                                                              |
| `bank_code`            | See [bank codes](#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](/knowledge-base/countries-specifications#documents-validations) to check document types and validations.

## Example Request

```java
{
  "login": "xxxxxxx",
  "pass": "xxxxxxx",
  "external_id": "40000000001",
  "country": "UG",
  "amount": 500,
  "currency": "UGX",
  "bank_account": "62102458345",
  "bank_code": "10002",
  "document_id": "12345678",
  "beneficiary_name": "John",
  "beneficiary_lastname": "Doe",
  "account_type": "S",
  "phone": +255681234567,
  "notification_url": "https://webhook.site/url",
  "type": "json"
}
```

{% 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 %}

## Bank Codes

| Bank          | Code  |
| ------------- | ----- |
| MTN Uganda    | 10000 |
| AIRTEL Uganda | 10002 |
| Vodafone      | 36    |


# Asian Countries

Learn about the cashouts validations of the Asian countries

{% content-ref url="/pages/bM4KmQ4lsnJ7tQTrkCd1" %}
[Bangladesh](/api-documentation/deposits-api/payment-methods/asia/bangladesh)
{% endcontent-ref %}

{% content-ref url="/pages/NtNRxogfPe97IpvuL71U" %}
[China](/api-documentation/cashouts-api/countries-validations/asian-countries/china)
{% endcontent-ref %}

{% 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/-MD78NFXnQKELpB78535" %}
[Malaysia](/api-documentation/cashouts-api/countries-validations/asian-countries/malaysia)
{% 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 %}

{% content-ref url="/pages/OgObhoW8PolAE5qn7pxA" %}
[Pakistan](/api-documentation/deposits-api/payment-methods/asia/pakistan)
{% endcontent-ref %}


# 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="/pages/-M8muWcG4tmJbnohBWM5#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="/pages/-M8muWcG4tmJbnohBWM5#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="/pages/-M8muWcG4tmJbnohBWM5#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="/pages/-MD70wsOav-zReUGlOsm#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](/knowledge-base/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

{% 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 %}

| Bank   | Code |
| ------ | ---- |
| BKash  | 001  |
| Nagad  | 002  |
| Rocket | 004  |


# 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](/knowledge-base/countries-specifications#documents-validations)              | Beneficiary's document ID                                                                           |
| `country`              | `CN`                                                                                                    | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)              |
| `currency`             | `CNY` / `USD`                                                                                           | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies)             |
| `amount`               | Number with up to 2 decimals                                                                            | Cashout amount                                                                                      |
| `bank_account`         | Numeric                                                                                                 | 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`                | String                                                                                                  | <p>Beneficiary's phone number including country code</p><h4 id="bank-account-validations"><br></h4> |

## 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](/knowledge-base/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": "+8618581234567",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Code

{% 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 %}

<table data-header-hidden><thead><tr><th width="374">Bank</th><th>Code</th></tr></thead><tbody><tr><td>Bank of Communications</td><td>301</td></tr><tr><td>China CITIC Bank</td><td>302</td></tr><tr><td>Shanghai Pudong Development Bank</td><td>310</td></tr><tr><td>China Minsheng Bank</td><td>305</td></tr><tr><td>Pingan bank</td><td>903</td></tr><tr><td>Postal Savings Bank of China</td><td>403</td></tr><tr><td>China s Industrial Bank</td><td>309</td></tr><tr><td>China Everbright Bank</td><td>303</td></tr><tr><td>China Construction Bank</td><td>105</td></tr><tr><td>Industrial and Commercial Bank</td><td>102</td></tr></tbody></table>


# India

Check the requirements and validations made over the cashouts on India

## 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](/knowledge-base/countries-specifications#documents-validations)                                    | Beneficiary's document ID                                                               |
| `country`          | `IN`                                                                                                                          | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`         | `INR` / `USD`                                                                                                                 | See [currency codes](/knowledge-base/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/india#bank-account-validations) | Beneficiary's bank account                                                              |
| `bank_branch`      | See [validations below](/api-documentation/cashouts-api/countries-validations/asian-countries/india#bank-branch-validations)  | Beneficiary's [IFSC](https://economictimes.indiatimes.com/wealth/ifsc-bank-code)        |
| `beneficiary_name` | String (max length: 100)                                                                                                      | Beneficiary's name                                                                      |
| `email`            | String (max length: 100)                                                                                                      | <p>User's email</p><h3 id="bank-account-validations"><br></h3>                          |

## 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                  |
| ----- | ----------- | ---------------------------------- | ------------------------ |
| iCash | IFSC        | Hardcode the example value         | ICSH0000000              |
| 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;**\
\- Paytm Payment Bank
{% endhint %}

## Document Validations

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

## Example Request

{% tabs %}
{% tab title="Cashout request" %}

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

{% endtab %}

{% tab title="Response" %}

```
external_id=100365001A2538925094
cashout_id=197821234
date=2025-03-18 10:10:10
bank_reference_id=39b6e872adc04e23f437dbd75cccd123
control=50553B0A13419744FF8CFFAD6711829863B5152E702FCDB123456789735671
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The UTR is returned in the bank\_reference\_id field.
{% endhint %}

## Bank Codes

{% 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 %}

{% 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 %}

| STATE BANK OF INDIA          | 139  |
| ---------------------------- | ---- |
| KOTAK MAHINDRA BANK          | 90   |
| HDFC BANK LTD.               | 62   |
| BANK OF BARODA               | 17   |
| PUNJAB NATIONAL BANK         | 128  |
| UNION BANK OF INDIA          | 167  |
| CANARA BANK                  | 35   |
| AXIS BANK                    | 172  |
| BANK OF INDIA                | 24   |
| AIRTEL PAYMENTS BANK LIMITED | 5    |
| ICICI BANK LTD.              | 70   |
| iCash One                    | 1000 |


# 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](/knowledge-base/countries-specifications#documents-validations)                                        | Beneficiary's document ID                                                               |
| `country`              | `ID`                                                                                                                              | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `IDR` / `USD`                                                                                                                     | See [currency codes](/knowledge-base/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](/knowledge-base/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": "lastname",
    "country": "ID",
    "amount": 10,
    "currency": "IDR",
    "bank_code": "57",
    "bank_account": "16800026081",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

{% 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 %}

| Bank                   | Code  |
| ---------------------- | ----- |
| Bank BCA               | 4     |
| DANA                   | 10000 |
| Bank Seabank Indonesia | 535   |
| Bank Mandiri           | 57    |
| BRI Bank               | 856   |
| BNI Bank               | 857   |
| Bank Jago              | 542   |
| Gopay                  | 980   |
| CIMB Niaga             | 659   |
| OVO                    | 970   |


# 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](/knowledge-base/countries-specifications#documents-validations)                                       | Beneficiary's document ID                                                               |
| `country`              | `MY`                                                                                                                             | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `MYR` / `USD`                                                                                                                    | See [currency codes](/knowledge-base/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](/knowledge-base/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

{% 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 %}

| Touch Go wallet        | 32  |
| ---------------------- | --- |
| Maybank                | 268 |
| CIMB Bank              | 1   |
| Public Bank            | 634 |
| Hong Leong Bank        | 961 |
| RHB Bank               | 785 |
| Bank Simpanan National | 229 |
| AM Bank                | 312 |
| Alliance Bank          | 421 |
| Bank Islam Malaysia    | 555 |

{% 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](/knowledge-base/countries-specifications#documents-validations)                                       | Beneficiary's document ID                                                               |
| `country`              | `TH`                                                                                                                             | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `THB` / `USD`                                                                                                                    | See [currency codes](/knowledge-base/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](/knowledge-base/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": "lastname",
    "country": "TH",
    "amount": 100,
    "currency": "THB",
    "bank_code": "21",
    "bank_account": "1680026081",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

{% 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 %}

| KasiKorn Bank                   | 278 |
| ------------------------------- | --- |
| Siam Commercial Bank            | 734 |
| Bank of Ayudhya                 | 21  |
| Bangkok Bank                    | 427 |
| KTB Net Bank                    | 215 |
| Krung Thai Bank                 | 824 |
| Government Savings Bank         | 485 |
| TMB Bank Public Company Limited | 823 |
| Kiatnakin Bank                  | 168 |
| CIMB Thai                       | 93  |

{% 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 %}


# 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](/knowledge-base/countries-specifications#documents-validations)                                      | Beneficiary's document ID                                                               |
| `country`              | `VN`                                                                                                                            | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `VND` / `USD`                                                                                                                   | See [currency codes](/knowledge-base/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](/knowledge-base/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": "lastname",
    "country": "VN",
    "amount": 100,
    "currency": "VND",
    "bank_code": "400",
    "bank_account": "16800026081",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

{% 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 %}

| BANK                                           | CODE |
| ---------------------------------------------- | ---- |
| MB Bank                                        | 129  |
| Vietcom Bank                                   | 436  |
| Techcom Bank                                   | 407  |
| TPBank                                         | 130  |
| VietinBank                                     | 415  |
| ACB                                            | 2    |
| VPBank                                         | 128  |
| Bank for Investment and Development of Vietnam | 401  |
| CAKE                                           | 3496 |


# Pakistan

Check the requirements and validations made over the Cashouts in Pakistan

## 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](/knowledge-base/countries-specifications#documents-validations)                                       | Beneficiary's document ID                                                               |
| `country`              | `PK`                                                                                                                             | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies)  |
| `currency`             | `PKR` / `USD`                                                                                                                    | See [currency codes](/knowledge-base/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                                                                 |
| Email                  | String                                                                                                                           | beneficiary email                                                                       |
| phone                  | String                                                                                                                           | Beneficiary phone number                                                                |

## Bank Account Validations

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

## Document Validations

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

## Example Request

```java
{
    "login": "xxxxxxx",
    "pass": "xxxxxxx",
    "external_id": "12300000001",
    "document_id": "8738394738785",
    "document_type": "CNIC",
    "beneficiary_name": "John",
    "beneficiary_lastname": "Doe",
    "phone": "+92 312 3456026",
    "email": "johndoe@email.com",
    "country": "PK",
    "amount": 5000,
    "currency": "PKR",
    "bank_code": "001",
    "bank_account": "16800026081",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}
```

## Bank Codes

{% 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 %}

| Bank      | Code |
| --------- | ---- |
| Jazzcash  | 001  |
| Easypaisa | 002  |


# API Codes

Learn about the API Codes returned by our Cashouts APIs

## **Cashout Status Codes**

<table><thead><tr><th width="181.33333333333331" 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="/files/-M9Uq6hh3MZ301JtlBh4" alt="" data-size="original"> </td><td>The cashout was accepted by Lime-Pay but it wasn't sent to the bank yet. It can still be Canceled. See <a href="/pages/-M9v7BJbQ5JRXqkF4Ksv">Cancel Cashout</a></td></tr><tr><td align="center">1</td><td align="center"><img src="/files/-M9UsDlL5PDQXBDL5CUD" 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="/files/-M9UsJ4Co_cg-RzJZT6c" 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="/files/-MDNZ67x7s7LgmAyG4YI" 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="/files/-MDQyQCx2cX3EhoAitEv" 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="/files/MUsyplC1BSBUM2PyZDm0" 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.

| Code | Name                                    | Description                                     |
| ---- | --------------------------------------- | ----------------------------------------------- |
| 800  | `ERROR_ACCOUNT_INCORRECT`               | Invalid bank account                            |
| 801  | `ERROR_ACCOUNT_CLOSED`                  | Bank account is closed                          |
| 802  | `ERROR_AMOUNT_INCORRECT`                | Invalid amount                                  |
| 803  | `ERROR_BANK_INVALID`                    | Invalid bank code                               |
| 804  | `ERROR_BANK_BRANCH_INCORRECT`           | Invalid bank branch                             |
| 805  | `ERROR_BENEFICIARY_DOCUMENT_ID_INVALID` | Invalid beneficiary document                    |
| 806  | `ERROR_BENEFICIARY_NAME_INCORRECT`      | Beneficiary name doesn't match bank details     |
| 807  | `ERROR_REJECTED_BY_BANK`                | Rejected by bank                                |
| 808  | `ERROR_OTHER`                           | Other error                                     |
| 809  | `WITHDRAWAL_EXPIRED`                    | Withdrawal expired                              |
| 810  | `LIMIT_EXCEEDED`                        | Beneficiary limit exceeded                      |
| 811  | `RISK_POLICY`                           | Violates bank risk policy                       |
| 812  | `BLOCKED_FROZEN_ACCOUNT`                | Bank account blocked/frozen                     |
| 813  | `DOCUMENT_ACCOUNT_MISMATCH`             | Beneficiary document doesn't match bank details |
| 815  | `INVALID_IFSC_CODE`                     | Invalid IFSC code                               |
| 816  | `INVALID_ACCOUNT_OR_IFSC_CODE`          | Invalid bank account or IFSC code               |
| 817  | `INVALID_NBIN`                          | Invalid NBIN                                    |
| 818  | `ACCOUNT_UNABLE`                        | The bank account is unable to receive transfers |
| 819  | `INVALID_ACCOUNT_TYPE`                  | Invalid bank account type                       |
| 820  | `REJECTED_BY_MERCHANT_REQUEST`          | Rejected by  merchant's request                 |
| 823  | `REJECTED_BY_MERCHANT_REQUEST`          | Email field cannot be empty                     |

## **Cashout Internal Error Codes**

<table><thead><tr><th width="253">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="/pages/-M9v4jg1AwCXUr1Q_PJy">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 processed as the user has reached their financial capacity, please provide proof of winnings</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 support team</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 support team</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="/pages/-M8muWcG4tmJbnohBWM5#phone-numbers-validations"> valid phone number</a></td></tr><tr><td>557</td><td>Account name required to be in Mandarin</td></tr><tr><td>566</td><td>Bank Code disabled</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 support team</td></tr></tbody></table>

## **Cashout Status Rejection Error Codes**

The error information is the one (if) provided by the Bank.

<table><thead><tr><th width="196.33333333333331">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>

### 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><br>Sportsman user</td><td>Sportsman user</td></tr><tr><td align="center">117</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Related to Sportsman user</td><td>Related to Sportsman user</td></tr><tr><td align="center">118</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>National Sanction List</td><td>User has been identified on national sanction lists</td></tr><tr><td align="center">119</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>International Sanction Lists</td><td>User has been identified on international sanction lists</td></tr><tr><td align="center">120</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><tr><td align="center">121</td><td align="center">400</td><td align="center"><code>USER_REJECTED_KYC_CHECK</code></td><td>Velocity check</td><td>Rejected due to velocity check</td></tr></tbody></table>


# Reconciliation API

The Reconciliation API allows you to automatize your reconciliation tasks

## Introduction

The Reconciliation API allows you to retrieve the details of one or a list of transactions on demand at any time.

The responses will be in JSON format, which you can then parse to the format you would be more comfortable with (.CSV as example).

## Initial Configurations

* Create a user account on the merchant panel and assign the "Financial" pre set capability.
* curate a list of IP address from which the API will be accessed and send to <integration@lime-pay.com> for configuration

## Reconciliation API Flow

To integrate this API, you will use our STG environment. Once the integration is completed, you will move to our Production environment.&#x20;

Described below is the flow of usage of the Reconciliation API:

**1 -** **Register:** create a user on our **Staging Merchant Panel**. You won't be able to use this account to log in through the web once it was configured for using with the API.

**2 -** **Configure the account:** send an email to <integration@lime-pay.com> containing the email address you created the user's account with and the list of IPs you would like to whitelist to set up the account for the API usage. Having in mind that you are able to hit the Merchants API only from the whitelisted IPs, you will need to collect the required IPs and send them for configuration.

{% hint style="danger" %}
Have in mind that once the user is configured, the user account won't be able to login from the web(Merchant panel), but from the API instead, as r*econciliation API users cannot access the panel and are only meant for API interaction.* Once your tests are completed, please create a user account in the Production Merchant Panel.
{% endhint %}

**3 -** **Integrate:** once our Integration team has configured your account, you can start integrating the API in our STG environment.

**4 -** **Login:** login by using the email and password from **step 1** using the [**Login Endpoint**](/api-documentation/reconciliation-api/endpoints#login-endpoint).

**5 -** **Consult details:** hit our [**Transactions Endpoints**](/api-documentation/reconciliation-api/endpoints#transactions-endpoint) to retrieve the desired details.

**6 -** **Logout:** as soon as you've finished the activities, you may need to use the [**Logout Endpoint**](/api-documentation/reconciliation-api/endpoints#logout-endpoint) to terminate the session.

**7 -** **Move to Production:** as soon as you have completed the tests and you would like to start using it in our Production environment, please repeat steps **1** and **2** using our **Production Merchant Panel**.


# Technical and Security Aspects

Learn about the technical and security aspects of our Reconciliation API

## Authentication <a href="#authentication" id="authentication"></a>

The Merchant API requires you to authenticate with the email and password of a user account you will have to create on the Merchant Panel. Once you request to authenticate to the [**Login Endpoint**](about:/api-documentation/reconciliation-api/endpoints#login-endpoint), we will respond with a cookie called **BEARER\_TOKEN** containing a **token** you have to use in the next API calls to remain authenticated.

The **BEARER\_TOKEN** cookie will expire after 15 minutes of its last request. Otherwise you may use the [**Logout Endpoint**](about:/api-documentation/reconciliation-api/endpoints#logout-endpoint) to invalidate the cookie for future usages.

## Technical and Security Aspects <a href="#technical-and-security-aspects" id="technical-and-security-aspects"></a>

**Secure Connections**: All the communications between you and the Merchants API has to be performed through secure connections over HTTPS.

**User access**: Only users set up to use this API can get information from it. Others won’t be allowed in..

**IP restrictions**: Only connections from the whitelisted IPs will be accepted. This measure ensures that only designated sources can access the API.

**Login Requirements:** You'll need both your email and password to use this API. This helps to ensure only authorised users can get in.


# Endpoints

Learn how to automatize your reconciliation tasks by integrating the endpoints of our Reconciliation API

## Login Endpoint

Once your account is ready to use the Merchants API, the first step will be authenticating yourself. This authentication process necessitates the submission of a POST request to the login endpoint. mentioned below. This request should include the **accessKey (email)** and **secretKey (password)** in JSON format to validate and establish the user's credentials.

## Login to API user

<mark style="color:green;">`POST`</mark> `https://merchants-api-stg.lime-pay.com/v1/auth/login`

**Production** `POST https://merchants-api.lime-pay.com/v1/auth/login`

#### Request Body

| Name                                        | Type   | Description                       |
| ------------------------------------------- | ------ | --------------------------------- |
| accessKey<mark style="color:red;">\*</mark> | string | Configured API User email address |
| secretKey<mark style="color:red;">\*</mark> | string | Configured API User's password    |

{% tabs %}
{% tab title="403: Forbidden Failure: invalid location" %}

```json
{
    "code": 83,
    "description": "You are not permitted to log in from this location, please contact your account administrator."
}
```

{% endtab %}

{% tab title="200: OK Login success" %}
{% tabs %}
{% tab title="response" %}

```json
{
    "idUser": 123,
    "username": "your@email.com",
    "idMerchant": 456
}
```

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

{% hint style="info" %}
Make sure you add in the header of the request the following value: \
**Content-Type: application/json**
{% endhint %}

***

## Switch Context Endpoint

In some cases where a reconciliation user needs to fetch reports from more than one MIDs that the user belongs to, The Switch context endpoint allows you to switch effortlessly between MIDS irrespective of number of MIDS the user account belongs.

## Switch Between MIDs

<mark style="color:green;">`POST`</mark> `https://merchants-api-stg.lime-pay.com/v1/auth/[MID]/switchContext`

**Production** `POST https://merchants-api.lime-pay.com/v1/auth/[MID]/switchContext`

#### Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | `application/json` |
| Cookie       | String | BEARER             |

{% hint style="info" %}
Replace the \[MID] in the urls above with your merchant MID

Note: You can not switch to an account that the user does not belong as a user.
{% endhint %}

If switched from MID A to MID B, note that all responses from other endpoints will fetch reports from MID B.

***

### BEARER\_TOKEN cookie

Upon successful authentication, the response will include a header field named Set-Cookie. This particular field will carry a cookie labeled as **BEARER\_TOKEN** that has to be sent back to the server in all the following requests to stay logged in.

Example of a cookie in the header with the BEARER\_TOKEN value:

```
cookie: BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk
```

See [this page](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) to learn more about cookies.

***

## TRANSACTIONS ENDPOINT

Described below the endpoints for each kind of transactions.

To send requests, ensure you include the BEARER\_TOKEN obtained from the Login Endpoint in the Authentication header field of the requests. You can use it in the following ways:

**As part of the header:**

```
Authorization: Bearer U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk
```

**Or as a cookie:**

```
cookie: BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk
```

There are certain parameter you can send in the GET request. These parameters come in pairs of names and values known as name-value pairs. They're added to the URL following a “?” sign, and multiple parameters can be utilized, separated by an “&” sign. The name and value are always separated using an “=” sign.

The syntax is as follows (examples):

**Staging** `https://merchants-api-stg.lime-pay.com/v1/cashouts?page=0&from=1577836800&to=1580515200`

**Production** `https://merchants-api.lime-pay.com/v1/cashouts?page=0&from=1577836800&to=1580515200`

{% hint style="info" %}
The "from" and "to" values follow the [unixTimeStamp format](https://www.unixtimestamp.com/), allowing a maximum difference of up to 60 days between them. The "from" value cannot exceed the "to" value.
{% endhint %}

A basic response has the following format:

```json
{
 "data": [],
 "page": 0,
 "rows": 0,
 "maxRows": 50
 }
```

* The **data** field, is an array that will contain multiple JSON objects, one for each transaction. Each with its own details.
* The response from these endpoints can display a maximum of 50 records per page. In case there are more than 50 records, you will have to request for the next page using the **page** parameter in the GET request. Always start with **page=0**.
* The **rows** field, indicates how many transactions the request returned.
* The **maxRows** field shows the maximum transactions a request can retrieve. In case the "**rows"** is equal to "**maxRows"**, you should do another request specifying the **page** plus one. Repeat this until the **rows** value is lesser than the **maxRows** one.

***

### Deposits Endpoint

## Retrieve deposit details

<mark style="color:blue;">`GET`</mark> `https://merchants-api-stg.lime-pay.com/v1/deposits`

This endpoint allows you to retrieve the details of all your Deposits in a given time.

**Production:** `GET https://merchants-api.lime-pay.com/v1/deposits`

#### Query Parameters

| Name           | Type                   | Description                                                                                                                              |
| -------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| from           | integer                | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format.                                            |
| to             | integer                | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format - max difference with "from" value 60 days. |
| page           | integer                | The page number. Each page contains as many transactions as indicated in the maxRows value.                                              |
| country        | String (max length: 2) | Country´s code. [Click here](/knowledge-base/countries-specifications) to see the list of countries.                                     |
| paymentMethod  | String (max length: 2) | Payment Method code. See [Payment Methods](/api-documentation/deposits-api/payment-methods) for its codes.                               |
| status         | String                 | Transaction´s status. Values: PENDING APPROVED COMPLETED CANCELLED DECLINED                                                              |
| clientDocument | String                 | The customer´s document.                                                                                                                 |

#### Headers

| Name          | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| Content-Type  | String | `application/json`                               |
| Cookie        | String | `BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk` |
| Authorization | String | `BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk` |

{% tabs %}
{% tab title="200: OK Merchants API Deposits Endpoint Response" %}

```json
{
    "data": [
        {
            "idDeposit": 1190025477,
            "externalId": "postmanTest624202296",
            "creationDate": "2025-01-16T13:08:08Z",
            "countryName": "Malaysia",
            "country": "MY",
            "paymentMethodName": "Grab",
            "paymentMethodCode": "GRB",
            "requestedPaymentMethod": "GRB",
            "requestedPaymentMethodName": "Grab",
            "clientId": "1234",
            "amount": 5.0,
            "currency": "USD",
            "balanceCurrency": "USD",
            "requestedAmount": 5.0,
            "requestedCurrency": "USD",
            "localAmount": 123.45,
            "localCurrency": "MYR",
            "localCountryTaxFee": 0.0,
            "usdCountryTaxFee": 0.0,
            "fee": 0.0,
            "feeCurrency": "USD",
            "lastChangeDate": "2025-01-16T13:08:08Z",
            "status": "CREATED",
            "idUser": "9156789",
            "flags": [],
            "idMerchant": 22865,
            "merchantName": "John Doe inc.",
            "allowInstallments": false,
            "refundAttempted": false,
        },
    ],
    "page": 0,
    "rows": 1,
    "maxRows": 50
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The parameter "Status" may have either of the following status\
`PENDING`**,** `APPROVED`**,** `COMPLETED`**,** `CANCELLED`**,** `DECLINED`
{% endhint %}

***

### Cashouts Endpoint

## Retrieve Cashout details

<mark style="color:blue;">`GET`</mark>` ``https://merchants-api-stg.lime-pay.com/v1/cashouts`

This endpoint allows you to retrieve the details of all your Cashouts in a given time.

**Production:** `GET https://merchants-api.lime-pay.com/v1/cashouts`

#### Query Parameters

| Name           | Type                   | Description                                                                                                                              |
| -------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| from           | integer                | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format.                                            |
| to             | integer                | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format - max difference with "from" value 60 days. |
| page           | integer                | The page number. Each page contains as many transactions as indicated in the maxRows value.                                              |
| country        | String (max length: 2) | Country´s code. [Click here](/knowledge-base/countries-specifications) to see the list of countries.                                     |
| Status         | String                 | Transaction status. Values: ON\_HOLD PENDING DELIVERED COMPLETED REJECTED CANCELLED DECLINED                                             |
| clientDocument | String                 | The customer´s document.                                                                                                                 |

#### Headers

| Name          | Type   | Description                                                                |
| ------------- | ------ | -------------------------------------------------------------------------- |
| Content-Type  | String | `application/json`                                                         |
| Cookie        | String | <p><code>BEARER\_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk</code></p><p></p> |
| Authorization | String | `BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk`                           |

{% tabs %}
{% tab title="200: OK Merchants API Cashouts Endpoint response" %}

```json
{
    "data": [
        {
            "idCashout": 1770,
            "externalId": "test123",
            "creationDate": "2025-01-24T18:17:55Z",
            "country": "MY",
            "currency": "USD",
            "amount": 200.0,
            "creditedCurrency": "USD",
            "creditedAmount": 0.0,
            "merchantCurrency": "USD",
            "merchantAmount": 0.0,
            "feeCurrency": "USD",
            "fee": 0.0,
            "tax": 0.0,
            "lastChangeDate": "2025-01-24T18:17:55Z",
            "status": "PENDING",
            "clientDocument": "12345678901",
            "flags": [],
            "idMerchant": 1234,
            "merchantName": "Merchant Test",
            "reason": "",
            "existVoucher": false
        }
    ],
    "page": 0,
    "rows": 1,
    "maxRows": 50
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The parameter "Status" may have either of the following status\
`ON_HOLD`, `PENDING`, `DELIVERED`, `COMPLETED`, `REJECTED`, `CANCELLED`, `DECLINED`
{% endhint %}

***

### Credit and Debit Notes Endpoint

This specific endpoint allow users to access comprehensive details pertaining to all Credit and Debit Notes within a specified time frame.

## Retrieve credit/Debit note details

<mark style="color:blue;">`GET`</mark> `https://merchants-api-stg.lime-pay.com/v1/notes`

This specific endpoint empowers users to access comprehensive details pertaining to all Credit and Debit Notes within a specified time frame.\
\
**Production** `GET https://merchants-api.lime-pay.com/v1/notes`

#### Query Parameters

| Name | Type    | Description                                                                                                                                                                                                                                                                                                                                                             |
| ---- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from | integer | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format.                                                                                                                                                                                                                                                                           |
| to   | integer | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format - max difference with "from" value 60 days.                                                                                                                                                                                                                                |
| page | integer | The page number. Each page contains as many transactions as indicated in the maxRows value.                                                                                                                                                                                                                                                                             |
| type | string  | <p>Credit/debit note types;</p><p></p><p>GENERIC\_CREDIT\_NOTE,</p><p>SERVICE\_FEE\_CREDIT\_NOTE,</p><p>CHARGEBACK\_COVERED\_CREDIT\_NOTE,</p><p>GENERIC\_DEBIT\_NOTE</p><p>REFUND,</p><p>REFUND\_PROCESSING\_FEE,</p><p>CASHOUT\_TRANSACTION,</p><p>CASHOUT\_PROCESSING\_FEE,</p><p>CHARGEBACK,</p><p>CHARGEBACK\_PROCESSING\_FEE,</p><p>SERVICE\_FEE\_DEBIT\_NOTE</p> |

{% tabs %}
{% tab title="200: OK Success" %}

```json
{
    "data": [
        {
            "id": 989851,
            "externalId": "",
            "idMerchant": 1234,
            "merchantName": "Merchant Test",
            "date": "2025-01-7T14:04:53Z",
            "amount": 1000000.0,
            "currency": "USD",
            "type": "GENERIC_CREDIT_NOTE",
            "description": "test note",
            "category": "CREDIT"
        },
        {
            "id": 989852,
            "externalId": "",
            "idMerchant": 1234,
            "merchantName": "Merchant Test",
            "date": "2025-01-10T14:05:22Z",
            "amount": 500.0,
            "currency": "USD",
            "type": "CASHOUT_PROCESSING_FEE",
            "description": "cashout transaction fee debit note",
            "category": "DEBIT"
        }
    ],
    "page": 0,
    "rows": 2,
    "maxRows": 50
}
```

{% endtab %}
{% endtabs %}

***

### Refunds Endpoint

This endpoint allows you to retrieve the details of all your **Refunds** in a given time.

## Refund endpoint parameters

<mark style="color:blue;">`GET`</mark> `https://merchants-api-stg.lime-pay.com/v1/refund`

**Production:** `GET https://merchants-api.lime-pay.com/v1/refund`

#### Query Parameters

| Name          | Type                   | Description                                                                                                                              |
| ------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| from          | integer                | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format.                                            |
| to            | integer                | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format - max difference with "from" value 60 days. |
| page          | integer                | The page number. Each page contains as many transactions as indicated in the maxRows value.                                              |
| country       | String (max length: 2) | Country code. [Click here](/knowledge-base/countries-specifications) to see the list of countries.                                       |
| paymentMethod | String (max length: 2) | Payment Method code. See [Payment Methods](/api-documentation/deposits-api/payment-methods) for its codes.                               |
| status        | string                 | Transaction status                                                                                                                       |

{% tabs %}
{% tab title="412: Precondition Failed Exceeded date period" %}

```json
{
    "code": 18,
    "description": "Date period must be smaller than 60 days",
    "type": "EXCEEDED_DATE_PERIOD"
}

```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Transaction Status Values\
`PENDING`, `COMPLETED`, `CANCELLED`, `WAITING_DETAILS`
{% endhint %}

***

### Chargebacks Endpoint

This endpoint allows you to retrieve the details of all your **Chargebacks** in a given time.

## Chargeback

<mark style="color:blue;">`GET`</mark> `https://merchants-api-stg.lime-pay.com/v1/chargeback`

**Production** `GET https://merchants-api.lime-pay.com/v1/chargeback`

#### Query Parameters

| Name    | Type                   | Description                                                                                                                                                       |
| ------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from    | integer                | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format.                                                                     |
| to      | integer                | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format - max difference with "from" value 60 days.                          |
| page    | integer                | The page number. Each page contains as many transactions as indicated in the maxRows value.                                                                       |
| country | String (max length: 2) | Country code. [Click here](/knowledge-base/countries-specifications) to see the list of countries.                                                                |
| status  | string                 | <p>Transaction status</p><p>Values: <br><strong>PENDING</strong>, <br><strong>COMPLETED,</strong> <br><strong>CANCELLED,</strong><br> <strong>FAILED</strong></p> |

***

### Settlements Endpoint

This endpoint allows you to retrieve the details of all your **Settlements** in a given time.

## Settlement Endpoint

<mark style="color:blue;">`GET`</mark> `https://merchants-api-stg.lime-pay.com/v1/settlements`

**Production:** `GET https://merchants-api.lime-pay.com/v1/settlements`

#### Query Parameters

| Name   | Type    | Description                                                                                                                              |
| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| from   | integer | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format.                                            |
| to     | integer | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format - max difference with "from" value 60 days. |
| page   | integer | The page number. Each page contains as many transactions as indicated in the maxRows value.                                              |
| Status | string  | <p>Transaction status<br>Values: PENDING, COMPLETED, CANCELLED, FAILED</p>                                                               |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "data": [
        {
            "id": 3329,
            "creationDate": "2025-01-06T00:00:00Z",
            "type": "MANUAL",
            "currency": "USD",
            "requestedAmount": 50000.0,
            "fee": 250.0,
            "amountToTransfer": 49750.0,
            "status": "PENDING",
            "idMerchant": 1234,
            "merchantName": "Merchant Test"
        },
        {
            "id": 3328,
            "creationDate": "2019-12-13T00:00:00Z",
            "type": "MANUAL",
            "currency": "USD",
            "requestedAmount": 1000000.0,
            "fee": 0.0,
            "amountToTransfer": 1000000.0,
            "status": "PENDING",
            "idMerchant": 1234,
            "merchantName": "Merchant Test"
        }
    ],
    "page": 0,
    "rows": 2,
    "maxRows": 50
}
```

{% endtab %}
{% endtabs %}

***

### Balance Report Endpoint

This endpoint allows you to retrieve the details of your daily **Balance Report** in a given time.

## Balance Report Endpoint

<mark style="color:blue;">`GET`</mark> `https://merchants-api-stg.lime-pay.com/v1/balance/report`

**Production** `GET https://merchants-api.lime-pay.com/v1/balance/report`

#### Query Parameters

| Name | Type    | Description                                                                                                                              |
| ---- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| from | integer | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format.                                            |
| to   | integer | Transaction creation date interval in [UnixTimeStamp](https://www.unixtimestamp.com/) format - max difference with "from" value 60 days. |
| page | integer | The page number. Each page contains as many transactions as indicated in the maxRows value.                                              |

{% tabs %}
{% tab title="200: OK success" %}

```json
{
    "data": [
        {
            "idMerchant": 1234,
            "depositTotal": 0.0,
            "cashoutTotal": 0.0,
            "noteTotal": 0.0,
            "settlementTotal": 0.0,
            "cancelledSettlementTotal": 0.0,
            "depositFeeTotal": 0.0,
            "netAmount": 0.0,
            "totalBalance": 104642.98,
            "date": "2020-01-05T00:00:00Z",
            "currency": "USD"
        },
        {
            "idMerchant": 1234,
            "depositTotal": 12.5,
            "cashoutTotal": 0.0,
            "noteTotal": 0.0,
            "settlementTotal": 0.0,
            "cancelledSettlementTotal": 0.0,
            "depositFeeTotal": 0.1,
            "netAmount": 12.4,
            "totalBalance": 104655.38,
            "date": "2025-01-11T00:00:00Z",
            "currency": "USD"
        }
    ],
    "page": 0,
    "rows": 2,
    "maxRows": 50
}
```

{% endtab %}
{% endtabs %}

***

### Total Available Balance Endpoint

This endpoint allows you to retrieve the details of your **Total Available Balance**.

**Staging:**  `GET https://merchants-api-stg.lime-pay.com/v1/balance`

**Production:**  `GET https://merchants-api.lime-pay.com/v1/balance`

***

## Logout Endpoint

<mark style="color:red;">`DELETE`</mark> `https://merchants-api-stg.lime-pay.com/v1/auth/session/destroy`

The token expires after 15 minutes of its last usage. In case of wanting to terminate the session earlier, you will have to use the mentioned endpoint with the **DELETE** method.\
This will take the **BEARER\_TOKEN** in the header of the request and invalidate it for future usages.\ <br>

**Staging:**  `DELETE https://merchants-api-stg.lime-pay.com/v1/auth/session/destroy`

**Production:**  `DELETE https://merchants-api.lime-pay.com/v1/auth/session/destroy`

#### Headers

| Name   | Type   | Description                                      |
| ------ | ------ | ------------------------------------------------ |
| Cookie | String | `BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk` |

{% hint style="info" %}
Once the token is invalidated, you will need to [authenticate](broken://pages/-M8b_n0sSR9bjW6GaTuZ#login-endpoint) again before sending a new request.
{% endhint %}


# API Codes

Check the list of HTTP and API codes returned by the Reconciliaton API

## Merchants API codes

‌

### HTTP codes <a href="#http-codes" id="http-codes"></a>

| **Code** | **Description**       | **Action**                                                                                                                                                                                |
| -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200      | Ok                    | The request was successful                                                                                                                                                                |
| 301      | Moved Permanently     | Make sure you are sending the request over HTTPS                                                                                                                                          |
| 400      | Bad Request           | Make sure the syntax of the request is correct                                                                                                                                            |
| 401      | Unauthorized          | The token is expired or incorrect                                                                                                                                                         |
| 403      | Forbidden             | Your IP may not be whitelisted or you are not allowed to use this API                                                                                                                     |
| 405      | Method Not Allowed    | The request HTTP method you are using is incorrect                                                                                                                                        |
| 412      | Precondition Failed   | Make sure you are sending the right credentials, that your account is active, or that it was configured for Merchants API usage. It will be shown in case of incorrect parameters as well |
| 500      | Internal Server Error | Make sure the content type of the request is the correct and that the syntax of the request is also correct                                                                               |

‌

### Error codes <a href="#error-codes" id="error-codes"></a>

| **Code** | **Description**                                                                               | **Action**                                                                                                                                                              |
| -------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 11       | You have typed wrong credentials, or the user is either locked or inactive                    | Make sure you are using the right credentials. Also check with one of your admin user accounts if the account is active                                                 |
| 17       | Date `from` must be before date `to`                                                          | Make sure the FROM field in the GET request is smaller than the TO field                                                                                                |
| 19       | Provided ISO country XX is not valid                                                          | ​Provide a valid country code                                                                                                                                           |
| 26       | Access denied. The user has insufficient privileges                                           | Make sure your API user account is not configured as administrator and that you have the required capabilities configured to hit the endpoint (go to Accounts -> Users) |
| 83       | You are not permitted to log in from this location, please contact your account administrator | The IP you are using has to be whitelisted. Please see [Whitelisting IPs](broken://pages/-M8b_g5pavgZs81C7ZE-)                                                          |
| 96       | The user type is incorrect                                                                    | The user account is not configured for usage with the Merchants API. Please see Configuration and reach out to [integration@lime-pay.com](mailto:integration@d24.com)   |


# Support Tickets API

The Support Ticket API allows you to create and manage support tickets directly from the Merchant Panel. You can flag deposits for review, attach supporting documents, and track your requests — all through simple API calls.

### How it works

Ticket creation follows a **three-step flow**:

1. **Create a draft ticket** — call the create endpoint with the ticket type and description. You will receive a ticket ID.
2. **Attach documents (if needed)** — upload any required files such as vouchers, bank statements, or ID documents. Some documents may be auto-attached for you.
3. **Confirm the ticket** — once everything is ready, confirm the ticket. It gets submitted to our support team and cannot be modified after that.

{% hint style="info" %}
For deposit reviews, you can skip step 1 — use the dedicated deposit endpoints and they will create the draft ticket for you automatically.
{% endhint %}

### Environments

| Environment | Base URL                                 |
| ----------- | ---------------------------------------- |
| Staging     | `https://merchants-api-stg.lime-pay.com` |
| Production  | `https://merchants-api.lime-pay.com`     |

{% hint style="success" %}
We recommend testing your integration in the **Staging** environment before going live in Production.
{% endhint %}


# Technical and Security Aspects

### Authentication

The Support Ticket API requires you to authenticate with the email and password of a user account created on the Merchant Panel. Once you request to authenticate to the Login Endpoint, we will respond with a cookie called **BEARER\_TOKEN** containing a token you have to use in the next API calls to remain authenticated.

{% hint style="info" %}
The **BEARER\_TOKEN** cookie will expire after **15 minutes** of its last request. Otherwise you may use the Logout Endpoint to invalidate the cookie for future usages.
{% endhint %}

#### BEARER\_TOKEN cookie

Upon successful authentication, the response will include a header field named `Set-Cookie`. This particular field will carry a cookie labeled as **BEARER\_TOKEN** that has to be sent back to the server in all the following requests to stay logged in.

Example of a cookie in the header with the BEARER\_TOKEN value:

```
cookie: BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk
```

To send requests, ensure you include the BEARER\_TOKEN obtained from the Login Endpoint in the Authentication header field of the requests. You can use it in the following ways:

**As part of the header:**

```
Authorization: Bearer U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk
```

**Or as a cookie:**

```
cookie: BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk
```

See [this page](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) to learn more about cookies.

{% hint style="info" %}
Make sure you add in the header of the request the following value:\
**Content-Type: application/json**
{% endhint %}

### Secure Connections

All the communications between you and the Merchants API has to be performed through secure connections over **HTTPS**.

### Switching Between MIDs

In cases where a user needs to manage tickets from more than one MID, the Switch Context endpoint allows you to switch effortlessly between MIDs irrespective of the number of MIDs the user account belongs to.

If switched from MID A to MID B, note that all responses from other endpoints will operate under MID B.

{% hint style="warning" %}
You cannot switch to an account that the user does not belong to.
{% endhint %}

### Document Types

When attaching documents to a ticket, you must specify the document type. The following types are accepted:

| Type             | Description                            |
| ---------------- | -------------------------------------- |
| `VOUCHER`        | Payment receipt or proof of transfer   |
| `ID_DOCUMENT`    | Government-issued identification       |
| `BANK_STATEMENT` | Bank statement showing the transaction |

{% hint style="info" %}
For deposit review tickets, if a voucher already exists in the system it gets attached automatically. Check the `uploadedDocuments` field in the response before uploading a duplicate.
{% endhint %}


# Endpoints

### Login Endpoint

Once your account is ready to use the Support Ticket API, the first step will be authenticating yourself. This authentication process necessitates the submission of a POST request to the login endpoint mentioned below. This request should include the **accessKey (email)** and **secretKey (password)** in JSON format to validate and establish the user's credentials.

### Login to API user

<mark style="color:green;">`POST`</mark> `https://merchants-api-stg.lime-pay.com/v1/auth/login`

**Production** `POST https://merchants-api.lime-pay.com/v1/auth/login`

**Request Body**

| Name                                        | Type   | Description                       |
| ------------------------------------------- | ------ | --------------------------------- |
| accessKey<mark style="color:red;">\*</mark> | string | Configured API User email address |
| secretKey<mark style="color:red;">\*</mark> | string | Configured API User's password    |

{% tabs %}
{% tab title="200: OK Login success" %}

```json
{
    "idUser": 123,
    "username": "your@email.com",
    "idMerchant": 456
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid credentials" %}

```json
{
    "code": "UNAUTHORIZED",
    "message": "Session expired or invalid token"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Make sure you add in the header of the request the following value:\
**Content-Type: application/json**
{% endhint %}

***

### Switch Context Endpoint

In some cases where a user needs to manage tickets from more than one MID, the Switch Context endpoint allows you to switch effortlessly between MIDs irrespective of the number of MIDs the user account belongs to.

### Switch Between MIDs

<mark style="color:green;">`POST`</mark> `https://merchants-api-stg.lime-pay.com/v1/auth/{mid}/switchContext`

**Production** `POST https://merchants-api.lime-pay.com/v1/auth/{mid}/switchContext`

**Headers**

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | `application/json` |
| Cookie       | String | BEARER\_TOKEN      |

{% hint style="info" %}
Replace the `{mid}` in the URLs above with your merchant MID.

Note: You cannot switch to an account that the user does not belong to.
{% endhint %}

If switched from MID A to MID B, note that all responses from other endpoints will operate under MID B.

{% tabs %}
{% tab title="200: OK Context switched" %}
Context switched successfully. Your session now operates under the new merchant.
{% endtab %}

{% tab title="401: Unauthorized Session expired" %}

```json
{
    "code": "UNAUTHORIZED",
    "message": "Session expired or invalid token"
}
```

{% endtab %}
{% endtabs %}

***

### Logout Endpoint

Invalidates the current session token. Use this when you are done to keep your account secure.

### Delete Session

<mark style="color:red;">`DELETE`</mark> `https://merchants-api-stg.lime-pay.com/v1/auth/session/destroy`

**Production** `DELETE https://merchants-api.lime-pay.com/v1/auth/session/destroy`

**Headers**

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | String | `application/json` |
| Cookie       | String | BEARER\_TOKEN      |

{% tabs %}
{% tab title="200: OK Session destroyed" %}
Session destroyed successfully.
{% endtab %}

{% tab title="401: Unauthorized Session expired" %}

```json
{
    "code": "UNAUTHORIZED",
    "message": "Session expired or invalid token"
}
```

{% endtab %}
{% endtabs %}

***

### TICKET ENDPOINTS

Described below are the endpoints for creating and confirming support tickets.

To send requests, ensure you include the BEARER\_TOKEN obtained from the Login Endpoint in the Authentication header field of the requests. You can use it in the following ways:

**As part of the header:**

```
Authorization: Bearer U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk
```

**Or as a cookie:**

```
cookie: BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk
```

***

#### Create Draft Ticket

### Create a support ticket in draft state

<mark style="color:green;">`POST`</mark> `https://merchants-api-stg.lime-pay.com/v1/tickets/createTicket`

**Production** `POST https://merchants-api.lime-pay.com/v1/tickets/createTicket`

Creates a new support ticket in **draft** state. The ticket is not submitted until confirmed. After creation, you can add attachments before calling the confirm endpoint.

**Request Body**

| Name                                          | Type    | Description                                       |
| --------------------------------------------- | ------- | ------------------------------------------------- |
| type<mark style="color:red;">\*</mark>        | string  | Ticket type (e.g. `DEPOSIT`)                      |
| category                                      | string  | Ticket category (e.g. `FLAG_FOR_REVIEW_DEPOSIT`)  |
| description<mark style="color:red;">\*</mark> | string  | Description of the issue                          |
| referenceId                                   | integer | ID of the related entity (deposit, cashout, etc.) |

**Headers**

| Name          | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| Content-Type  | String | `application/json`                               |
| Cookie        | String | `BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk` |
| Authorization | String | `Bearer U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk`       |

{% tabs %}
{% tab title="200: OK Draft ticket created" %}

```json
{
    "idTicket": 12345,
    "description": "Deposit not credited after 48h",
    "requiredDocuments": [
        "VOUCHER"
    ],
    "uploadedDocuments": []
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
    "code": "UNAUTHORIZED",
    "message": "Session expired or invalid token"
}
```

{% endtab %}

{% tab title="403: Forbidden" %}

```json
{
    "code": "FORBIDDEN",
    "message": "Missing required capability: TICKETS_CREATE"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Check the `requiredDocuments` field in the response. If there are items listed that are not in `uploadedDocuments`, you need to attach them before confirming the ticket.
{% endhint %}

***

#### Add Attachment

### Upload a document to a draft ticket

<mark style="color:green;">`POST`</mark> `https://merchants-api-stg.lime-pay.com/v1/tickets/{idTicket}/addAttachment`

**Production** `POST https://merchants-api.lime-pay.com/v1/tickets/{idTicket}/addAttachment`

Uploads a file to a draft ticket. The ticket must still be in draft state (not yet confirmed).

{% hint style="info" %}
Replace `{idTicket}` with the ticket ID returned by the create ticket endpoint.

This request must be sent as **multipart/form-data**, not JSON.
{% endhint %}

**Request Body (multipart/form-data)**

| Name                                           | Type   | Description                                                  |
| ---------------------------------------------- | ------ | ------------------------------------------------------------ |
| file<mark style="color:red;">\*</mark>         | binary | The file to upload (PDF, image, etc.)                        |
| documentType<mark style="color:red;">\*</mark> | string | Type of document: `VOUCHER`, `ID_DOCUMENT`, `BANK_STATEMENT` |

**Headers**

| Name          | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| Content-Type  | String | `multipart/form-data`                            |
| Cookie        | String | `BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk` |
| Authorization | String | `Bearer U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk`       |

{% tabs %}
{% tab title="200: OK Attachment uploaded" %}

```json
{
    "idTicket": 12345,
    "description": "Deposit not credited after 48h",
    "requiredDocuments": [
        "VOUCHER"
    ],
    "uploadedDocuments": [
        "VOUCHER"
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid file or type" %}

```json
{
    "code": "INVALID_DOCUMENT",
    "message": "Invalid file or document type"
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
    "code": "NOT_FOUND",
    "message": "Ticket not found or already confirmed"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For deposit review tickets, if a voucher already exists in the system it gets attached automatically. Check `uploadedDocuments` before uploading a duplicate.
{% endhint %}

***

### Confirm and submit a draft ticket

<mark style="color:green;">`POST`</mark> `https://merchants-api-stg.lime-pay.com/v1/tickets/{idTicket}/confirmTicket`

**Production** `POST https://merchants-api.lime-pay.com/v1/tickets/{idTicket}/confirmTicket`

Confirms a draft ticket and submits it to the support team. Once confirmed, the ticket **cannot be modified**.

{% hint style="info" %}
Replace `{idTicket}` with the ticket ID returned by the create ticket endpoint.
{% endhint %}

**Headers**

| Name          | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| Content-Type  | String | `application/json`                               |
| Cookie        | String | `BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk` |
| Authorization | String | `Bearer U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk`       |

{% tabs %}
{% tab title="200: OK Ticket confirmed" %}

```json
{
    "idTicket": 12345,
    "description": "Deposit not credited after 48h",
    "requiredDocuments": [
        "VOUCHER"
    ],
    "uploadedDocuments": [
        "VOUCHER"
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
    "code": "UNAUTHORIZED",
    "message": "Session expired or invalid token"
}
```

{% endtab %}

{% tab title="403: Forbidden" %}

```json
{
    "code": "FORBIDDEN",
    "message": "Missing required capability: TICKETS_CONFIRM"
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
    "code": "NOT_FOUND",
    "message": "Ticket not found"
}
```

{% endtab %}
{% endtabs %}

***

### DEPOSIT REVIEW ENDPOINTS

These endpoints allow you to flag a deposit or a deposit reversal for manual review. They automatically create a draft ticket — you only need to attach any missing documents and confirm.

***

#### Flag Deposit for Review

### Flag a deposit for manual review

<mark style="color:green;">`POST`</mark> `https://merchants-api-stg.lime-pay.com/v1/deposits/{idDeposit}/flagForReview`

**Production** `POST https://merchants-api.lime-pay.com/v1/deposits/{idDeposit}/flagForReview`

Flags a deposit for manual review. Internally creates a ticket of type `FLAG_FOR_REVIEW_DEPOSIT`.

{% hint style="info" %}
Replace `{idDeposit}` with the deposit ID you want to flag for review.
{% endhint %}

**Validations performed before ticket creation:**

* Deposit must exist
* Deposit must belong to the authenticated merchant
* A minimum time interval must have passed since the deposit was created

If the deposit has a voucher, it is **automatically attached** to the ticket.

**Headers**

| Name          | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| Content-Type  | String | `application/json`                               |
| Cookie        | String | `BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk` |
| Authorization | String | `Bearer U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk`       |

{% tabs %}
{% tab title="200: OK Review ticket created" %}

```json
{
    "idTicket": 67890,
    "description": "Flag for review - Deposit #98765",
    "requiredDocuments": [
        "VOUCHER"
    ],
    "uploadedDocuments": [
        "VOUCHER"
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request Deposit not reviewable" %}

```json
{
    "code": "DEPOSIT_NOT_REVIEWABLE",
    "message": "The deposit does not meet the minimum requirements to be flagged for review"
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
    "code": "UNAUTHORIZED",
    "message": "Session expired or invalid token"
}
```

{% endtab %}

{% tab title="403: Forbidden" %}

```json
{
    "code": "FORBIDDEN",
    "message": "Missing required capability: DEPOSITS_FLAG_REVIEW"
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
After flagging, check `requiredDocuments` vs `uploadedDocuments`. If the voucher was auto-attached, you may be able to confirm the ticket right away without uploading anything extra.
{% endhint %}

After receiving the response, you may add more attachments and confirm the ticket via `POST /v1/tickets/{idTicket}/confirmTicket`.

***

#### Flag Deposit Reversal for Review

### Flag a deposit reversal for manual review

<mark style="color:green;">`POST`</mark> `https://merchants-api-stg.lime-pay.com/v1/deposits/{idDeposit}/flagForReviewReversal`

**Production** `POST https://merchants-api.lime-pay.com/v1/deposits/{idDeposit}/flagForReviewReversal`

Flags a deposit **reversal** for manual review. Internally creates a ticket of type `FLAG_FOR_REVIEW_DEPOSIT_REVERSAL`. Applies the same validations and auto-attachment logic as `flagForReview`.

{% hint style="info" %}
Replace `{idDeposit}` with the deposit ID whose reversal should be flagged for review.
{% endhint %}

**Headers**

| Name          | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| Content-Type  | String | `application/json`                               |
| Cookie        | String | `BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk` |
| Authorization | String | `Bearer U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk`       |

{% tabs %}
{% tab title="200: OK Reversal review ticket created" %}

```json
{
    "idTicket": 67891,
    "description": "Flag for review reversal - Deposit #98765",
    "requiredDocuments": [
        "VOUCHER"
    ],
    "uploadedDocuments": [
        "VOUCHER"
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request Deposit not reviewable" %}

```json
{
    "code": "DEPOSIT_NOT_REVIEWABLE",
    "message": "The deposit does not meet the minimum requirements to be flagged for review"
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
    "code": "UNAUTHORIZED",
    "message": "Session expired or invalid token"
}
```

{% endtab %}

{% tab title="403: Forbidden" %}

```json
{
    "code": "FORBIDDEN",
    "message": "Missing required capability: DEPOSITS_FLAG_REVIEW"
}
```

{% endtab %}
{% endtabs %}


# API Codes

When something goes wrong, the API returns a JSON object with a `code` and a `message` explaining what happened.

### Error Response Format

```json
{
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
}
```

### Error Codes

| Code                     | HTTP Status | Description                                                                                                                           |
| ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `UNAUTHORIZED`           | 401         | Session expired or invalid token. Log in again.                                                                                       |
| `FORBIDDEN`              | 403         | Your account does not have the required permission. Contact your account administrator.                                               |
| `NOT_FOUND`              | 404         | The ticket or resource does not exist. Double-check the ID.                                                                           |
| `DEPOSIT_NOT_REVIEWABLE` | 400         | The deposit cannot be flagged for review. It may not exist, belong to another merchant, or not enough time has passed since creation. |
| `INVALID_DOCUMENT`       | 400         | Invalid file or document type when uploading an attachment.                                                                           |

{% hint style="info" %}
If you receive a `401 UNAUTHORIZED` error, your session has expired. Simply call the Login Endpoint again to get a new BEARER\_TOKEN.
{% endhint %}

### Required Capabilities

Some endpoints require specific capabilities assigned to your user account. If you receive a `403 FORBIDDEN` error, contact your account administrator to verify your permissions.

| Capability             | Required for                      |
| ---------------------- | --------------------------------- |
| `TICKETS_CREATE`       | Creating draft tickets            |
| `TICKETS_CONFIRM`      | Confirming and submitting tickets |
| `DEPOSITS_FLAG_REVIEW` | Flagging deposits for review      |

{% hint style="warning" %}
If you are missing a capability, reach out to your account manager or contact our support team at `integration@lime-pay.com`.
{% endhint %}


# 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) |
| ------------- | :----------------------------------------: | :---------------------------: |
| Australia     |                     AU                     |            USD/AUS            |
| Bangladesh    |                     BD                     |            USD/BDT            |
| China         |                     CN                     |            USD/CNY            |
| Côte d'Ivoire |                     CI                     |           USD / XOF           |
| Egypt         |                     EG                     |            USD/EGP            |
| Ghana         |                     GH                     |           USD / GHS           |
| India         |                     IN                     |           USD / INR           |
| Indonesia     |                     ID                     |           USD / IDR           |
| Japan         |                     JP                     |           USD / JPY           |
| Kenya         |                     KE                     |           USD / KES           |
| Malaysia      |                     MY                     |           USD / MYR           |
| Nigeria       |                     NG                     |           USD / NGN           |
| Philippines   |                     PH                     |           USD / PHP           |
| Singapore     |                     SG                     |           USD / SGD           |
| South Africa  |                     ZA                     |           USD / ZAR           |
| South korea   |                     KR                     |            USD/KRW            |
| Thailand      |                     TH                     |           USD / THB           |
| Turkey        |                     TR                     |            USD/TRY            |
| Uganda        |                     UG                     |           USD / UGX           |
| Vietnam       |                     VN                     |           USD / VND           |

## Documents validations

The `document` sent must follow the validations for its respective `document_type`  described below.

<table><thead><tr><th width="240">Country</th><th width="212.33333333333331">Document type</th><th>Validation</th></tr></thead><tbody><tr><td>Bangladesh</td><td>ID</td><td>Numeric. Length: 10 digits</td></tr><tr><td>Bangladesh</td><td>PASS</td><td>Length 9 digits,<br>Starting with 2 alphanumerical character (i.e: AB1234567)</td></tr><tr><td>Bangladesh</td><td>DL (Driving license)</td><td>Length: 15,<br>Starting with 2 alphanumerical characters, followed by 7 numerical digits, 1 alphanumerical character and finally 5 numerical (i.e: AB1234567C12345)</td></tr><tr><td>Cameroon</td><td>PASS</td><td>Numeric. Length between 9 and 11 inclusive</td></tr><tr><td>Cameroon</td><td>CI</td><td>Numeric. Length between 8 and 12 inclusive</td></tr><tr><td>Cameroon</td><td>DL (Driving License)</td><td>Numeric. Length between 8 and 10 inclusive</td></tr><tr><td>China</td><td>ID</td><td>Numeric. Length: 18 digits</td></tr><tr><td>Côte d'Ivoire</td><td>ID</td><td>Length between 8 and 12 inclusive</td></tr><tr><td>Egypt</td><td>ID</td><td>Numeric. Length between 12 and 14</td></tr><tr><td>Ghana</td><td>ID</td><td>Length between 8 and 12 inclusive</td></tr><tr><td>India</td><td>ID (PAN)</td><td>Length 10. </td></tr><tr><td>India</td><td>DL (Driver's License)</td><td>Length between 15 and 16 inclusive</td></tr><tr><td>India</td><td>UID (Aadhar Card)</td><td>Numeric. Length 12</td></tr><tr><td>Indonesia</td><td>NIK / KTP</td><td>Numeric. Length between 14 and 18 inclusive</td></tr><tr><td>Japan</td><td>DL / ID / PASS / RD (Resident Registration Card)</td><td>Length between 9 and 12 inclusive</td></tr><tr><td>Kenya</td><td>ID</td><td>Length between 7 and 12 inclusive</td></tr><tr><td>Malaysia</td><td>ID</td><td>Numeric. Length between 10 and 14 inclusive</td></tr><tr><td>Nigeria</td><td>ID</td><td>Length between 9 and 12 inclusive</td></tr><tr><td>Nigeria</td><td>ID (NIN)</td><td>Numeric. Length 11</td></tr><tr><td>Nigeria</td><td>PASS (Passport)</td><td>Alphanumeric length between 8 and 10</td></tr><tr><td>Philippines</td><td>PSN</td><td>Numeric. Length between 9 and 13 inclusive</td></tr><tr><td>Singapore</td><td>NRIC</td><td>Length 9</td></tr><tr><td>Singapore</td><td>PASS</td><td>Length 9</td></tr><tr><td>South Africa</td><td>ID</td><td>Numeric. Length between 9 and 14 inclusive</td></tr><tr><td>South Korea</td><td>PASS</td><td>Length 9</td></tr><tr><td>South Korea</td><td>RRN <br>(Resident registration number)</td><td>Numeric. Length 13</td></tr><tr><td>Tanzania</td><td>ID</td><td>Length between 8 and 20 inclusive</td></tr><tr><td>Thailand</td><td>ID</td><td>Numeric. Length between 10 and 14 inclusive</td></tr><tr><td>Turkey</td><td>DL</td><td>Numeric Length between 5-8 digits</td></tr><tr><td>Turkey</td><td>TCKK <br>(Turkish National Identity Card (Kimlik Kartı)</td><td>Numeric length Between 5 to 20 digits</td></tr><tr><td>Uganda</td><td>RIC / NID</td><td>Numeric. Length between 11 and 15 inclusive</td></tr><tr><td>Vietnam</td><td>ID</td><td>Numeric. Length between 9 and 13 inclusive</td></tr></tbody></table>

## 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 |
| ------------- | ---------------------- | :-----: |
| Cameroon      | N/A                    |   N/A   |
| China         | `^\d{6}$`              |  123456 |
| Côte d'Ivoire | N/A                    |   N/A   |
| Ghana         | `^[A-Za-z]{2}\d{3,5}$` |  AB1234 |
| 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  |
| Nigeria       | `^\d{6}$`              |  123456 |
| 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   |
| 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])
```