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

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

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

Production POST https://merchants-api.directa24.com/v1/auth/login

Request Body

Name	Type	Description
accessKey*	string	Configured API User email address
secretKey*	string	Configured API User's password

403: Forbidden Failure: invalid location

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

200: OK Login success

Body

{
    "idUser": 123,
    "username": "[email protected]",
    "idMerchant": 456
}

response

{
    "idUser": 123,
    "username": "[email protected]",
    "idMerchant": 456
}

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

---

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

POST https://merchants-api-stg.directa24.com/v1/auth/[MID]/switchContext

Staging POST https://merchants-api-stg.directa24.com/v1/auth/[MID]/switchContext

Production POST https://merchants-api.directa24.com/v1/auth/[MID]/switchContext

Headers

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

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.

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 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.directa24.com/v1/cashouts?page=0&from=1577836800&to=1580515200

Production https://merchants-api.directa24.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 response 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 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

Retrieve deposit details

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

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

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

Production: GET https://merchants-api.directa24.com/v1/deposits

Query Parameters

Name	Type	Description
from	integer	Transaction creation date interval in UnixTimeStamp format.
to	integer	Transaction creation date interval in UnixTimeStamp 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 to see the list of countries.
paymentMethod	String (max length: 2)	Payment Method code. See 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

200: OK Merchants API Deposits Endpoint Response

{
    "data": [
        {
            "idDeposit": 301164223,
            "externalId": "MP_689da0bb343f4bd9ac1da111db351e9b",
            "creationDate": "2024-01-10T13:41:57Z",
            "countryName": "Brazil",
            "country": "BR",
            "paymentMethodName": "Pix",
            "paymentMethodCode": "IX",
            "requestedPaymentMethod": "IX",
            "requestedPaymentMethodName": "Pix",
            "clientDocument": "123456789",
            "amount": 10.0,
            "currency": "USD",
            "requestedAmount": 10.0,
            "requestedCurrency": "USD",
            "localAmount": 51.45,
            "localCurrency": "BRL",
            "fee": 0.0,
            "feeCurrency": "USD",
            "lastChangeDate": "2024-01-10T13:41:58Z",
            "status": "PENDING",
            "idUser": "50097755",
            "flags": [],
            "idMerchant": 12345,
            "merchantName": "Merchant Name",
            "refundAttempted": false,
        },
        {
            "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
}

The parameter "Status" may have either of the following status PENDING, APPROVED, COMPLETED, CANCELLED, DECLINED

---

Cashouts Endpoint

Retrieve Cashout details

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

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

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

Production: GET https://merchants-api.directa24.com/v1/cashouts

Query Parameters

Name	Type	Description
from	integer	Transaction creation date interval in UnixTimeStamp format.
to	integer	Transaction creation date interval in UnixTimeStamp 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 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	BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk
Authorization	String	BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

200: OK Merchants API Cashouts Endpoint response

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

The parameter "Status" may have either of the following status ON_HOLD, PENDING, DELIVERED, COMPLETED, REJECTED, CANCELLED, DECLINED

---

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

GET https://merchants-api-stg.directa24.com/v1/notes

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

Query Parameters

Name	Type	Description
from	integer	Transaction creation date interval in UnixTimeStamp format.
to	integer	Transaction creation date interval in UnixTimeStamp 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	Credit/debit note types; GENERIC_CREDIT_NOTE, SERVICE_FEE_CREDIT_NOTE, CHARGEBACK_COVERED_CREDIT_NOTE, GENERIC_DEBIT_NOTE REFUND, REFUND_PROCESSING_FEE, CASHOUT_TRANSACTION, CASHOUT_PROCESSING_FEE, CHARGEBACK, CHARGEBACK_PROCESSING_FEE, SERVICE_FEE_DEBIT_NOTE

200: OK Success

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

---

Refunds Endpoint

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

Refund endpoint parameters

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

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

Production: GET https://merchants-api.directa24.com/v1/refund

Query Parameters

Name	Type	Description
from	integer	Transaction creation date interval in UnixTimeStamp format.
to	integer	Transaction creation date interval in UnixTimeStamp 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 to see the list of countries.
paymentMethod	String (max length: 2)	Payment Method code. See Payment Methods for its codes.
status	string	Transaction status

412: Precondition Failed Exceeded date period

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

Transaction Status Values PENDING, COMPLETED, CANCELLED, WAITING_DETAILS

---

Chargebacks Endpoint

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

Chargeback

GET https://merchants-api-stg.directa24.com/v1/chargeback

Staging GET https://merchants-api-stg.directa24.com/v1/chargeback

Production GET https://merchants-api.directa24.com/v1/chargeback

Query Parameters

Name	Type	Description
from	integer	Transaction creation date interval in UnixTimeStamp format.
to	integer	Transaction creation date interval in UnixTimeStamp 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 to see the list of countries.
status	string	Transaction status Values: PENDING, COMPLETED, CANCELLED, FAILED

---

Settlements Endpoint

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

Settlement Endpoint

GET https://merchants-api-stg.directa24.com/v1/settlements

Staging: GET https://merchants-api-stg.directa24.com/v1/settlements

Production: GET https://merchants-api.directa24.com/v1/settlements

Query Parameters

Name	Type	Description
from	integer	Transaction creation date interval in UnixTimeStamp format.
to	integer	Transaction creation date interval in UnixTimeStamp 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	Transaction status Values: PENDING, COMPLETED, CANCELLED, FAILED

200: OK

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

---

Balance Report Endpoint

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

Balance Report Endpoint

GET https://merchants-api-stg.directa24.com/v1/balance/report

Staging GET https://merchants-api-stg.directa24.com/v1/balance/report

Production GET https://merchants-api.directa24.com/v1/balance/report

Query Parameters

Name	Type	Description
from	integer	Transaction creation date interval in UnixTimeStamp format.
to	integer	Transaction creation date interval in UnixTimeStamp 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.

200: OK success

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

---

Total Available Balance Endpoint

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

Staging: GET https://merchants-api-stg.directa24.com/v1/balance

Production: GET https://merchants-api.directa24.com/v1/balance

---

Logout Endpoint

DELETE https://merchants-api-stg.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 mentioned endpoint with the DELETE method. This will take the BEARER_TOKEN in the header of the request and invalidate it for future usages.

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

Production: DELETE https://merchants-api.directa24.com/v1/auth/session/destroy

Headers

Name	Type	Description
Cookie	String	BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

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