# Endpoints

## 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](https://docs.lime-pay.com/knowledge-base/countries-specifications) to see the list of countries.            |
| paymentMethod  | String (max length: 2) | Payment Method code. See [Payment Methods](https://docs.lime-pay.com/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](https://docs.lime-pay.com/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](https://docs.lime-pay.com/knowledge-base/countries-specifications) to see the list of countries.              |
| paymentMethod | String (max length: 2) | Payment Method code. See [Payment Methods](https://docs.lime-pay.com/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](https://docs.lime-pay.com/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](https://docs.lime-pay.com/api-documentation/reconciliation-api/broken-reference) again before sending a new request.
{% endhint %}