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

NameTypeDescription

accessKey*

string

Configured API User email address

secretKey*

string

Configured API User's password

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

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

NameTypeDescription

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.


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

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

NameTypeDescription

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

NameTypeDescription

Content-Type

String

application/json

Cookie

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

Authorization

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

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

NameTypeDescription

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

NameTypeDescription

Content-Type

String

application/json

Cookie

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

Authorization

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

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

NameTypeDescription

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

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

NameTypeDescription

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

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

NameTypeDescription

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

NameTypeDescription

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

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

NameTypeDescription

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.

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

NameTypeDescription

Cookie

String

BEARER_TOKEN=U3dcUx8IRJ5nLjb0WYM4cHa3qHFqnrqAk

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

Last updated