# Endpoints

## Login Endpoint

> Example: Merchants API Authentication request body

```javascript
{
    "accessKey": "your@email.com",
    "secretKey": "password"
}
```

> Example: Merchants API Authentication response success

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

> Example: Merchants API Authentication response failure

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

**Staging** `POST` [`https://merchants-api-stg.directa24.com/v1/auth/login`](https://merchants-api-stg.directa24.com/v1/auth/login)

**Production** `POST` [`https://merchants-api.directa24.com/v1/auth/login`](https://merchants-api.directa24.com/v1/auth/login)

Once your account is ready to use the Merchants API, the first step will be authenticating yourself. This has to be done through a POST request to the login endpoint mentioned above specifying the accessKey (email) and the secretKey (password) in JSON format.

Please see the examples.

Make sure you add in the header of the request the following value: **Content-Type: application/json**

### BEARER\_TOKEN cookie

Once successfully authenticated, along with the response there will come a field in the header called Set-Cookie. This field will contain a cookie called **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 Endpoints

Described below the endpoints for each kind of transactions.

All the requests sent have to have the BEARER\_TOKEN obtained from the Login Endpoint in the Authentication's header field of the requests like follows:

`Authorization: Bearer U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk`

Or as a cookie:

`cookie: BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk`

There are certain parameter you can send in the GET request. These parameters are pairs of names and their corresponding values, so-called name-value pairs. These are added to the URL with a “?” sign. The name and value are always separated using an “=” sign. Multiple parameters can be used. Here, the various parameters are separated using an “&” sign.

The syntax is as follows (examples):

**Staging** [`https://merchants-api-stg.directa24.com/v1/cashouts?page=0&from=1577836800&to=1580515200`](https://merchants-api-stg.directa24.com/v1/cashouts?page=0\&from=1577836800\&to=1580515200)

**Production** [`https://merchants-api.directa24.com/v1/cashouts?page=0&from=1577836800&to=1580515200`](https://merchants-api.directa24.com/v1/cashouts?page=0\&from=1577836800\&to=1580515200)

The **from** and **to** values are in [unixTimeStamp format](https://www.unixtimestamp.com/) and the maximum difference between them is up to 60 days. The **from** value can´t be bigger than the **to** one.

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 this API uses pagination starting from **page=0**. Each page can display a maximum of rows defined by "**maxRows**". To work effectively with this pagination, begin with **page=0** and increment the page number by 1 whenever the **rows** value is equal to **maxRows**. Continue generating requests for subsequent pages until the number of records retrieved is less than the maximum, indicating the end of the dataset. **page** parameter will be sent in a GET request.
* 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

> Example: Merchants API Deposits Endpoint output

```javascript
{
    "data": [
        {
            "idDeposit": 94582793,
            "externalId": "newIUnit9499432",
            "creationDate": "2020-02-13T19:14:43Z",
            "countryName": "Brazil",
            "country": "BR",
            "paymentMethodName": "Banco do Brasil",
            "paymentMethodCode": "BB",
            "clientDocument": "12345678901",
            "clientId": "userId123",
            "amount": 10.0,
            "currency": "USD",
            "requestedAmount": 10.0,
            "requestedCurrency": "USD",
            "localAmount": 48.09,
            "localCurrency": "BRL",
            "fee": 0.0,
            "feeCurrency": "USD",
            "lastChangeDate": "2020-02-13T19:57:10Z",
            "status": "CANCELLED",
            "idUser": "300823",
            "flags": []
        },
        {
            "idDeposit": 94582792,
            "externalId": "newIUnit91055341",
            "creationDate": "2020-02-13T19:00:26Z",
            "countryName": "Mexico",
            "country": "MX",
            "paymentMethodName": "Visa",
            "paymentMethodCode": "VI",
            "clientDocument": "1234567890",
            "clientId": "userId124",
            "amount": 10.0,
            "currency": "USD",
            "requestedAmount": 10.0,
            "requestedCurrency": "USD",
            "localAmount": 197.43,
            "localCurrency": "MXN",
            "fee": 0.0,
            "feeCurrency": "USD",
            "lastChangeDate": "2020-02-13T19:20:36Z",
            "status": "COMPLETED",
            "idUser": "300824",
            "flags": []
        }
    ],
    "page": 0,
    "rows": 2,
    "maxRows": 50
}
```

**Staging** `GET` [`https://merchants-api-stg.directa24.com/v1/deposits`](https://merchants-api-stg.directa24.com/v1/deposits)

**Production** `GET` [`https://merchants-api.directa24.com/v1/deposits`](https://merchants-api.directa24.com/v1/deposits)

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

#### Deposits Endpoint Parameters

| Parameter      | Mandatory | Format                 | Default | Description                                                                                                                                  |
| -------------- | --------- | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| from           |           | Integer                | null    | Transaction creation date interval in UnixTimeStamp format.                                                                                  |
| to             |           | Integer                | null    | Transaction creation date interval in UnixTimeStamp format - max difference with "from" value 60 days.                                       |
| page           |           | Integer                | 0       | The page number. Each page contains as many transactions as indicated in the maxRows value.                                                  |
| country        |           | String (max length: 2) | all     | Country´s code. [Click here](https://docs.pandablue.com/api-documentation/reconciliation-api/broken-reference) to see the list of countries. |
| paymentMethod  |           | String (max length: 2) | all     | Payment Method code. See [Payment Methods](https://docs.pandablue.com/api-documentation/reconciliation-api/broken-reference) for its codes.  |
| status         |           | String                 | all     | <p>Transaction´s status. Values:</p><ul><li>PENDING</li><li>APPROVED</li><li>COMPLETED</li><li>CANCELLED</li><li>DECLINED</li></ul>          |
| clientDocument |           | String                 | all     | The customer´s document.                                                                                                                     |

### Cashouts Endpoint

> Example: Merchants API Cashouts Endpoint output

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

**Staging** `GET` [`https://merchants-api-stg.directa24.com/v1/cashouts`](https://merchants-api-stg.directa24.com/v1/cashouts)

**Production** `GET` [`https://merchants-api.directa24.com/v1/cashouts`](https://merchants-api.directa24.com/v1/cashouts)

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

#### Cashouts Endpoint Parameters

| Parameter      | Mandatory | Format                 | Default | Description                                                                                                                                                            |
| -------------- | --------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from           |           | Integer                | null    | Transaction creation date interval in UnixTimeStamp format.                                                                                                            |
| to             |           | Integer                | null    | Transaction creation date interval in UnixTimeStamp format - max difference with "from" value 60 days.                                                                 |
| page           |           | Integer                | 0       | The page number. Each page contains as many transactions as indicated in the maxRows value.                                                                            |
| country        |           | String (max length: 2) | all     | Country´s code. [Click here](https://docs.pandablue.com/api-documentation/reconciliation-api/broken-reference) to see the list of countries.                           |
| status         |           | String                 | all     | <p>Transaction´s status. Values:</p><ul><li>ON\_HOLD</li><li>PENDING</li><li>DELIVERED</li><li>COMPLETED</li><li>REJECTED</li><li>CANCELLED</li><li>DECLINED</li></ul> |
| clientDocument |           | String                 | all     | The customer´s document.                                                                                                                                               |

### Credit and Debit Notes Endpoint

> Example: Merchants API Credit and Debit Notes Endpoint output

```javascript
{
    "data": [
        {
            "id": 989851,
            "externalId": "",
            "idMerchant": 4,
            "merchantName": "Merchant Test",
            "date": "2020-02-13T14:04:53Z",
            "amount": 1000000.0,
            "currency": "USD",
            "type": "GENERIC_CREDIT_NOTE",
            "description": "test note",
            "category": "CREDIT"
        },
        {
            "id": 989852,
            "externalId": "",
            "idMerchant": 4,
            "merchantName": "Merchant Test",
            "date": "2020-02-13T14: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
}
```

**Staging** `GET` [`https://merchants-api-stg.directa24.com/v1/notes`](https://merchants-api-stg.directa24.com/v1/notes)

**Production** `GET` [`https://merchants-api.directa24.com/v1/notes`](https://merchants-api.directa24.com/v1/notes)

This endpoint allows you to retrieve the details of all your **Credit and Debit Notes** in a given time.

#### Credit and Debit Notes Endpoint Parameters

| Parameter | Mandatory | Format  | Default | Description                                                                                                                                                                                                                                                                                                                                                                        |
| --------- | --------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from      |           | Integer | null    | Transaction creation date interval in UnixTimeStamp format.                                                                                                                                                                                                                                                                                                                        |
| to        |           | Integer | null    | Transaction creation date interval in UnixTimeStamp format - max difference with "from" value 60 days.                                                                                                                                                                                                                                                                             |
| page      |           | Integer | 0       | The page number. Each page contains as many transactions as indicated in the maxRows value.                                                                                                                                                                                                                                                                                        |
| type      |           | String  | all     | <p>Cred/deb note types:</p><ul><li>GENERIC\_CREDIT\_NOTE</li><li>SERVICE\_FEE\_CREDIT\_NOTE</li><li>CHARGEBACK\_COVERED\_CREDIT\_NOTE</li><li>GENERIC\_DEBIT\_NOTE</li><li>REFUND</li><li>REFUND\_PROCESSING\_FEE</li><li>CASHOUT\_TRANSACTION</li><li>CASHOUT\_PROCESSING\_FEE</li><li>CHARGEBACK</li><li>CHARGEBACK\_PROCESSING\_FEE</li><li>SERVICE\_FEE\_DEBIT\_NOTE</li></ul> |

### Refunds Endpoint

**Staging** `GET` [`https://merchants-api-stg.directa24.com/v1/refund`](https://merchants-api-stg.directa24.com/v1/refund)

**Production** `GET` [`https://merchants-api.directa24.com/v1/refund`](https://merchants-api.directa24.com/v1/refund)

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

#### Refunds Endpoint Parameters

| Parameter     | Mandatory | Format                 | Default | Description                                                                                                                                  |
| ------------- | --------- | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| from          |           | Integer                | null    | Transaction creation date interval in UnixTimeStamp format.                                                                                  |
| to            |           | Integer                | null    | Transaction creation date interval in UnixTimeStamp format - max difference with "from" value 60 days.                                       |
| page          |           | Integer                | 0       | The page number. Each page contains as many transactions as indicated in the maxRows value.                                                  |
| country       |           | String (max length: 2) | all     | Country´s code. [Click here](https://docs.pandablue.com/api-documentation/reconciliation-api/broken-reference) to see the list of countries. |
| paymentMethod |           | String (max length: 2) | all     | Payment Method code. See [Payment Methods](https://docs.pandablue.com/api-documentation/reconciliation-api/broken-reference) for its codes.  |
| status        |           | String                 | all     | <p>Transaction´s status. Values:</p><ul><li>PENDING</li><li>COMPLETED</li><li>CANCELLED</li><li>WAITING\_DETAILS</li></ul>                   |

### Chargebacks Endpoint

**Staging** `GET` [`https://merchants-api-stg.directa24.com/v1/chargeback`](https://merchants-api-stg.directa24.com/v1/chargeback)

**Production** `GET` [`https://merchants-api.directa24.com/v1/chargeback`](https://merchants-api.directa24.com/v1/chargeback)

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

#### Chargebacks Endpoint Parameters

| Parameter | Mandatory | Format                 | Default | Description                                                                                                                                  |
| --------- | --------- | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| from      |           | Integer                | null    | Transaction creation date interval in UnixTimeStamp format.                                                                                  |
| to        |           | Integer                | null    | Transaction creation date interval in UnixTimeStamp format - max difference with "from" value 60 days.                                       |
| page      |           | Integer                | 0       | The page number. Each page contains as many transactions as indicated in the maxRows value.                                                  |
| country   |           | String (max length: 2) | all     | Country´s code. [Click here](https://docs.pandablue.com/api-documentation/reconciliation-api/broken-reference) to see the list of countries. |
| status    |           | String                 | all     | <p>Transaction´s status. Values:</p><ul><li>PENDING</li><li>COMPLETED</li><li>CANCELLED</li><li>FAILED</li></ul>                             |

### Settlements Endpoint

> Example: Merchants API Settlements Endpoint output

```javascript
{
    "data": [
        {
            "id": 3329,
            "creationDate": "2020-01-06T00:00:00Z",
            "type": "MANUAL",
            "currency": "USD",
            "requestedAmount": 50000.0,
            "fee": 250.0,
            "amountToTransfer": 49750.0,
            "status": "PENDING",
            "idMerchant": 4,
            "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": 4,
            "merchantName": "Merchant Test"
        }
    ],
    "page": 0,
    "rows": 2,
    "maxRows": 50
}
```

**Staging** `GET` [`https://merchants-api-stg.directa24.com/v1/settlements`](https://merchants-api-stg.directa24.com/v1/settlements)

**Production** `GET` [`https://merchants-api.directa24.com/v1/settlements`](https://merchants-api.directa24.com/v1/settlements)

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

#### Settlements Endpoint Parameters

| Parameter | Mandatory | Format  | Default | Description                                                                                                      |
| --------- | --------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| from      |           | Integer | null    | Transaction creation date interval in UnixTimeStamp format.                                                      |
| to        |           | Integer | null    | Transaction creation date interval in UnixTimeStamp format - max difference with "from" value 60 days.           |
| page      |           | Integer | 0       | The page number. Each page contains as many transactions as indicated in the maxRows value.                      |
| status    |           | String  | all     | <p>Transaction´s status. Values:</p><ul><li>PENDING</li><li>COMPLETED</li><li>CANCELLED</li><li>FAILED</li></ul> |

### Balance Report Endpoint

> Example: Merchants API Balance Report Endpoint output

```javascript
{
    "data": [
        {
            "idMerchant": 4,
            "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-30T00:00:00Z",
            "currency": "USD"
        },
        {
            "idMerchant": 4,
            "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": "2020-01-31T00:00:00Z",
            "currency": "USD"
        }
    ],
    "page": 0,
    "rows": 2,
    "maxRows": 50
}
```

**Staging** `GET` [`https://merchants-api-stg.directa24.com/v1/balance/report`](https://merchants-api-stg.directa24.com/v1/balance/report)

**Production** `GET` [`https://merchants-api.directa24.com/v1/balance/report`](https://merchants-api.directa24.com/v1/balance/report)

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

#### Balance Report Endpoint Parameters

| Parameter | Mandatory | Format  | Default | Description                                                                                            |
| --------- | --------- | ------- | ------- | ------------------------------------------------------------------------------------------------------ |
| from      |           | Integer | null    | Transaction creation date interval in UnixTimeStamp format.                                            |
| to        |           | Integer | null    | Transaction creation date interval in UnixTimeStamp format - max difference with "from" value 60 days. |
| page      |           | Integer | 0       | The page number. Each page contains as many transactions as indicated in the maxRows value.            |

### Total Available Balance Endpoint

**Staging** `GET` [`https://merchants-api-stg.directa24.com/v1/balance`](https://merchants-api-stg.directa24.com/v1/balance/report)

**Production** `GET` [`https://merchants-api.directa24.com/v1/balance`](https://merchants-api.directa24.com/v1/balance/report)

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

## Logout Endpoint

**Staging**  `DELETE` [`https://merchants-api-stg.directa24.com/v1/auth/session/destroy`](https://merchants-api-stg.directa24.com/v1/auth/session/destroy)

**Production**  `DELETE` [`https://merchants-api.directa24.com/v1/auth/session/destroy`](https://merchants-api.directa24.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 above mentioned endpoint with the **DELETE** method.

This will take the **BEARER\_TOKEN** in the header of the request and invalidate it for future usages.

Once the token was deleted, you will need to [authenticate](#login-endpoint) again before sending a new request.