# Endpoints

Learn how to automate your reconciliation tasks by integrating our Reconciliation API endpoint.

## <mark style="color:green;">LOGIN ENPOINT</mark>

Once your account is ready to use the Merchant API, the first step will be to authenticate. This authentication process requires sending a POST request to the login endpoint. Mentioned below. This request must include the access key (email) and secret key (password) in JSON format to validate and establish the user's credentials.

## Endpoint Login

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

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

**Producción** [`tps://merchants-api.tupayonline.com/v1/auth/login`](https://merchants-api.tupayonline.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 | Password of the configured API user |

{% tabs %}
{% tab title="200 Successful login." %}
{% tabs %}
{% tab title="Body" %}

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

{% endtab %}

{% tab title="Response" %}

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

{% endtab %}
{% endtabs %}

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

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

***

### <mark style="color:green;">BEARER\_TOKEN cookie</mark>

The response will include a header field called Set-Cookie. This particular field will carry a cookie labeled BEARER\_TOKEN which must be sent back to the server in all subsequent requests to stay logged in.

Example of cookie in header with value BEARER\_TOKEN:

```
cookie: BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk
```

Please see this [page ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies)for more information about cookies.

The endpoints for each type of transaction are described below.

To send requests, be sure to 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 parameters that you can send in the GET request. These parameters come in name-value pairs known as name-value. They are added to the URL after a “?” sign, and multiple parameters can be used, separated by an “&” sign. The name and value are always separated by an “=” sign.

The syntax is as follows (examples):

**Staging**

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

Production

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

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

A basic answer has the following format:

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

* The data field is an array that will contain multiple JSON objects, one for each transaction. Each one 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 need to request 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.

***

## <mark style="color:green;">DEPOSITS ENDPOINT</mark>

### Retrieve deposit details

**Staging**  `https://merchants-api-stg.tupayonline.com/v1/deposits`

**Production** `https://merchants-api.tupayonline.com/v1/deposits`

#### Query Parameters

| Name            | Type    | Description                                                                                                                                                     |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from            | integer | <p>Transaction creation date range in format</p><p><a href="https://www.unixtimestamp.com/">UnixTimeStamp</a></p>                                               |
| paymentMethod   | string  | <p>(max legth: 2)</p><p>Payment method code. (XA/XAQR)</p>                                                                                                      |
| country         | string  | <p>(PE)</p><p>Country code</p>                                                                                                                                  |
| page            | integer | The page number. Each page contains as many transactions as indicated by the maxRows value.                                                                     |
| to              | integer | <p>Transaction creation date range in format</p><p><a href="https://www.unixtimestamp.com/">UnixTimeStamp</a> maximum difference with value "from" 60 days.</p> |
| clienteDocument | String  | The client document.                                                                                                                                            |
| status          |         | Transaction status values: **PENDING APPROVED COMPLETED CANCELLED DECLINED**                                                                                    |

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Content-Type  | String | application/json                                |
| Cookie        | String | BEARER\_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk |
| Authorization | String | BEARER\_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk |

{% tabs %}
{% tab title="200 Respuesta del endpoint de depósitos de API de comerciantes" %}

```java
{
    "data": [
    {
            "idDeposit": 301393325,
            "externalId": "1-44862-ACP",
            "creationDate": "2024-06-01T13:37:17Z",
            "countryName": "Peru",
            "country": "PE",
            "paymentMethodName": "QR by Tupay",
            "paymentMethodCode": "XAQR",
            "requestedPaymentMethod": "XAQR",
            "requestedPaymentMethodName": "QR by Tupay",
            "clientDocument": "12345678",
            "amount": 7.92,
            "currency": "USD",
            "balanceCurrency": "USD",
            "requestedAmount": 30.0,
            "requestedCurrency": "PEN",
            "localAmount": 30.0,
            "localCurrency": "PEN",
            "localCountryTaxFee": 0.0,
            "usdCountryTaxFee": 0.0,
            "fee": 0.39,
            "feeCurrency": "USD",
            "lastChangeDate": "2024-06-02T13:38:26Z",
            "status": "CANCELLED",
            "idUser": "105",
            "flags": [],
            "idMerchant": 19759,
            "merchantName": "TUPAY TEST",
            "refundAttempted": false,
            "installments": 0,
            "allowPixApiRefund": false
        }
    ],
    "page": 0,
    "rows": 1,
    "maxRows": 50
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The "Status" parameter can have any of the following states PENDING, APPROVED, COMPLETED, CANCELLED, DECLINED
{% endhint %}

***

## <mark style="color:green;">CASHOUT ENDPOINT</mark>

### Retrieve Cashout details <a href="#cashouts-endpoint" id="cashouts-endpoint"></a>

**Staging**  `https://merchants-api-stg.tupayonline.com/v1/cashout`

**Producción** `https://merchants-api.tupayonline.com/v1/cashout`

#### Query Parameters

<table><thead><tr><th width="176">Name</th><th width="101">Type</th><th>Description</th></tr></thead><tbody><tr><td>from</td><td>integer</td><td><p>Transaction creation date range in format</p><p><a href="https://www.unixtimestamp.com/">UnixTimeStamp</a></p></td></tr><tr><td>paymentMethod</td><td>string</td><td><p>(max legth: 2)</p><p>Payment method code.(XA/XAQR)</p></td></tr><tr><td>country</td><td>string</td><td><p>(PE)</p><p>Country code</p></td></tr><tr><td>page</td><td>integer</td><td>The page number. Each page contains as many transactions as indicated by the maxRows value.</td></tr><tr><td>to</td><td>integer</td><td><p>Transaction creation date range in format</p><p><a href="https://www.unixtimestamp.com/">UnixTimeStamp</a> maximum difference with value "from" 60 days.</p></td></tr><tr><td>clienteDocument</td><td>string</td><td>The client document.</td></tr><tr><td>status</td><td>string</td><td><p>Transaction status values:</p><p>ON_HOLD <br>PENDING <br>DELIVERED COMPLETED <br>REJECTED <br>CANCELLED <br>DECLINED</p></td></tr></tbody></table>

#### Headers

<table><thead><tr><th width="152">Name</th><th width="93">Type</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type</td><td>String</td><td>application/json</td></tr><tr><td>Cookie</td><td>String</td><td>BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk</td></tr><tr><td>Authorization</td><td>String</td><td>BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk</td></tr></tbody></table>

{% tabs %}
{% tab title="200 Merchant API Cashout Endpoint" %}

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

{% endtab %}
{% endtabs %}

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

***

## <mark style="color:green;">BALANCE REPORT</mark>

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

### Balance Report Endpoint

**Staging** `GET https://merchants-api-stg.tupayonline.com/v1/balance/report`

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

**Query Parameters**

<table><thead><tr><th width="152">Name</th><th width="93">Type</th><th>Description</th></tr></thead><tbody><tr><td>from</td><td>string</td><td>Transaction creation date interval in <a href="https://www.unixtimestamp.com/">UnixTimeStamp</a> format.</td></tr><tr><td>to</td><td>string</td><td>Transaction creation date interval in <a href="https://www.unixtimestamp.com/">UnixTimeStamp</a> format - max difference with "from" value 60 days.</td></tr><tr><td>page</td><td>string</td><td>The page number. Each page contains as many transactions as indicated in the maxRows value.</td></tr></tbody></table>

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

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

{% 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.tupayonline.com/v1/balance`

**Production:** `GET https://merchants-api-stg.tupayonline.com/v1/balance`

## <mark style="color:green;">LOGOUT</mark>

## Endpoint Logout

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

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

**Producción** [`tps://merchants-api.tupayonline.com/v1/auth/login`](https://merchants-api.tupayonline.com/v1/auth/login)

#### Headers

<table><thead><tr><th width="255">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Cookie<mark style="color:red;">*</mark></td><td>string</td><td><code>BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk</code></td></tr></tbody></table>

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