Endpoints

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

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.

POST https://merchants-api-stg.tupayonline.com/v1/auth/login

Staging https://merchants-api-stg.tupayonline.com/v1/auth/login

Producción tps://merchants-api.tupayonline.com/v1/auth/login

Request Body

Name	Type	Description
accessKey*	string	Configured API user email address
secretKey*	string	Password of the configured API user

Name

Type

Description

accessKey*

string

Configured API user email address

secretKey*

string

Password of the configured API user

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

Make sure to add the following value to the request header: Content-Type: application/json

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

The "from" and "to" values follow the unixTimeStamp format, allowing a maximum difference of up to 60 days between them. The "from" value cannot exceed the "to" value.

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.

DEPOSITS CONSULTATION

Retrieve deposit details

GET https://merchants-api-stg.tupayonline.com/v1/deposits

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

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

Query Parameters

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

Name

Type

Description

from

integer

Transaction creation date range in format

UnixTimeStamp

paymentMethod

string

(max legth: 2)

Payment method code. (XA/XAQR)

country

string

(PE)

Country code

page

integer

The page number. Each page contains as many transactions as indicated by the maxRows value.

integer

Transaction creation date range in format

UnixTimeStamp maximum difference with value "from" 60 days.

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

Name

Type

Description

Content-Type

String

application/json

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

Authorization

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

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

The "Status" parameter can have any of the following states PENDING, APPROVED, COMPLETED, CANCELLED, DECLINED

WITHDRAWAL CONSULTATION

GET https://merchants-api-stg.tupayonline.com/v1/cashouts

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

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

Query Parameters

Name	Type	Description
from	integer	Transaction creation date range in format UnixTimeStamp
paymentMethod	string	(max legth: 2) Payment method code.(XA/XAQR)
country	string	(PE) Country code
page	integer	The page number. Each page contains as many transactions as indicated by the maxRows value.
to	integer	Transaction creation date range in format UnixTimeStamp maximum difference with value "from" 60 days.
clienteDocument	String	The client document.
status		Transaction status values: ON_HOLD PENDING DELIVERED COMPLETED REJECTED CANCELLED DECLINED

Name

Type

Description

from

integer

Transaction creation date range in format

UnixTimeStamp

paymentMethod

string

(max legth: 2)

Payment method code.(XA/XAQR)

country

string

(PE)

Country code

page

integer

The page number. Each page contains as many transactions as indicated by the maxRows value.

integer

Transaction creation date range in format

UnixTimeStamp maximum difference with value "from" 60 days.

clienteDocument

String

The client document.

status

Transaction status values:

ON_HOLD PENDING DELIVERED COMPLETED REJECTED CANCELLED DECLINED

Headers

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

Name

Type

Description

Content-Type

String

application/json

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

Authorization

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

The "Status" parameter can have any of the following states ON_HOLD, PENDING, DELIVERED, COMPLETED, REJECTED, CANCELLED, DECLINED

REFUND CONSULTATION

This endpoint allows you to retrieve the details of all your Refunds at any given time.

GET https://merchants-api-stg.tupayonline.com/v1/refund

Staging https://merchants-api-stg.tupayonline.com/v1/refund

Producción https://merchants-api-stg.tupayonline.com/v1/refund

Query Parameters

Name	Type	Description
from	integer	Transaction creation date range in format UnixTimeStamp
paymentMethod	string	(max legth: 2) Payment method code.(XA/XAQR)
country	string	(PE) Country code
page	integer	The page number. Each page contains as many transactions as indicated by the maxRows value.
to	integer	Transaction creation date range in format UnixTimeStamp maximum difference with value "from" 60 days.
status		Transactions status

Name

Type

Description

from

integer

Transaction creation date range in format

UnixTimeStamp

paymentMethod

string

(max legth: 2)

Payment method code.(XA/XAQR)

country

string

(PE)

Country code

page

integer

The page number. Each page contains as many transactions as indicated by the maxRows value.

integer

Transaction creation date range in format

UnixTimeStamp maximum difference with value "from" 60 days.

status

Transactions status

Headers

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

Name

Type

Description

Content-Type

String

application/json

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

Authorization

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

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

Status of transactions PENDING, COMPLETED, CANCELLED, WAITING_DETAILS

LOGOUT

Endpoint Logout

DELETE https://merchants-api-stg.tupayonline.com/v1/auth/session/destroy

Staging https://merchants-api-stg.tupayonline.com/v1/auth/login

Producción tps://merchants-api.tupayonline.com/v1/auth/login

Headers

Name Type Description

Name	Type	Description
Cookie*	string	`BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk`

Cookie*

string

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

Once the token is invalidated, you will need to authenticate again before sending a new request.

AnteriorTechnical and Security Aspects

Última actualización hace 19 días

LOGIN ENPOINT

Endpoint Login

Request Body

BEARER_TOKEN cookie

DEPOSITS CONSULTATION

Retrieve deposit details

Query Parameters

Headers

WITHDRAWAL CONSULTATION

Query Parameters

Headers

REFUND CONSULTATION

Query Parameters

Headers

LOGOUT

Endpoint Logout

Headers