Query Deposit

This endpoint allows detailed retrieval of a previously created deposit request. Although it is commonly used to verify the "deposit status", it returns the full object with all vital transaction information.

Endpoint

Method: GET

Endpoint URL
https://api.xgateglobal.com/deposit/TRANSACTION_ID/details

Important

The value TRANSACTION_ID in the URL refers to the _id of the deposit generated by XGate at the time the request was created.

Request

Required Headers

Header	Value	Description
`Authorization`	`Bearer <your_token>`	JWT authentication token obtained from login.

Responses

Success (200 OK)

The transaction was found. The structure of the returned data varies according to the operation type (Fiat or Crypto).

1. Pix Deposit (Fiat BRL):

{
    "_id": "6a3d60ffc37******************",
    "currency": {
        "name": "BRL",
        "type": "PIX",
        "amount": 0.2,
        "status": "PAID"
    },
    "generatedReceiptAt": "2026-06-25T17:10:45.584Z",
    "customerId": "6a1a379e1fe****************"
}

2. Pix Deposit converting to Crypto:

{
    "_id": "6a3da62669a8*************",
    "currency": {
        "name": "BRL",
        "type": "PIX",
        "amount": 0.2,
        "status": "PAID"
    },
    "cryptocurrency": {
        "name": "USDT",
        "symbol": "USDT",
        "amount": 0.038234,
        "status": "PAID",
        "coinGecko": "tether"
    },
    "generatedReceiptAt": "2026-06-25T22:05:50.439Z",
    "customerId": "6a1a379e1fe*************"
}

3. Crypto Deposit:

{
    "_id": "6a3da45e1**************",
    "idempotencyKey": "cryptocurrency:6a3da45bb503**************************************",
    "cryptocurrency": {
        "name": "USDT",
        "symbol": "USDT",
        "coinGecko": "tether",
        "status": "PAID",
        "blockchainNetwork": {
            "name": "Solana"
        },
        "amount": 4.7
    },
    "generatedReceiptAt": "2026-06-25T21:57:50.512Z",
    "customerId": "6a1a379e**************"
}

Field Description

Note: The response structure is dynamic. Pure Fiat deposits use the currency object. Pure Crypto deposits use cryptocurrency. Conversion deposits (Pix ➔ Crypto) return both.

Field	Type	Description
`_id`	`string`	Unique transaction ID generated by XGate.
`customerId`	`string`	ID of the customer linked to the transaction in XGate.
`generatedReceiptAt`	`string`	Exact date and time when the transaction receipt was generated (ISO 8601 format).
`idempotencyKey`	`string`	(Conditional) Idempotency key (present in crypto deposits). This string always carries the internal ID of the cryptocurrency and the transaction hash on the blockchain (txHash).
`currency`	`object`	(Conditional) Financial data for the Fiat operation (Pix or Conversions). Returns properties such as the settlement status (`status`), final amount (`amount`), currency (`name`), and method (`type`).
`cryptocurrency`	`object`	(Conditional) Data for the Crypto operation (Crypto or Conversions). Returns the blockchain status (`status`), processed amount (`amount`), currency data (`name`, `symbol`, `coinGecko`), and details of the network used (`blockchainNetwork`).

Common Errors

Status	Message	Likely Cause
401	`Unauthorized`	• Invalid or expired token. • Invalid or missing header. • IP not allowed.
404	`Not Found`	• The provided transaction ID is not valid. • The deposit does not exist in the system.
500	`Internal Server Error`	Internal server error. Contact support.

How to Use

Although the most efficient way to track deposits is through receiving Webhooks, this query route is an essential read endpoint for maintaining your system.

Common Use Cases

You will use this endpoint mainly in the following situations:

Reconciliation and Auditing: Confirm whether the amount (amount), network data (blockchainNetwork), or payer (document) of a deposit received by XGate match exactly with your internal database.
Failure Recovery (Fallback): If your server goes offline and you miss receiving a Webhook, you can create a routine (CRON) that queries "Pending" deposits using this endpoint to update lost statuses and release the balance to the user.
Customer Support (CS): Fetch the data of a specific deposit in real time to assist an end customer who sent the funds but says the balance did not post on the platform.

Practical Example

The primary purpose is to verify transaction progress. When querying the endpoint, you will focus on the status field corresponding to the operation to determine what to show your end customer.

Checking the payment:

In the code below, the system validates whether the response has the currency (Fiat) or cryptocurrency (Crypto) object to extract the correct transaction status:

Integration

Below is a simple example of how to implement this query using Node.js.

Node.js

The integration example uses the Axios library to make the HTTP request.

Installing Axios:

npm install axios

JavaScript Example:

const axios = require("axios");

(async () => {
const email = "email@domain.com";
const password = "••••••";
const transactionId = "6a3da45e116************";

try {
    const url_api = "https://api.xgateglobal.com";
    
    // 1. Get authentication token
    const login = await axios.post(`${url_api}/auth/token`, { email, password });
    
    // 2. Query deposit details
    const { data } = await axios.get(`${url_api}/deposit/${transactionId}/details`, {
        headers: {
            "Authorization": `Bearer ${login.data.token}`
        }
    });
    
    console.log("Deposit Details:", data);
    
    // Dynamic logic to identify the deposit type based on the response
    let status = "Unknown";
    let mensagem = "";
    let origem = ""; // Starts empty to avoid displaying incorrect information

    if (data.currency && data.cryptocurrency) {
        // Scenario 2: Conversion (Pix -> Crypto)
        status = data.cryptocurrency.status;
        mensagem = `Conversão: Entrou ${data.currency.amount} ${data.currency.name} e converteu para ${data.cryptocurrency.amount} ${data.cryptocurrency.name}`;
        if (data.document) origem = `Pix (Doc: ${data.document})`;
        
    } else if (data.cryptocurrency) {
        // Scenario 3: 100% Crypto
        status = data.cryptocurrency.status;
        const rede = data.cryptocurrency.blockchainNetwork?.name || "Desconhecida";
        mensagem = `Crypto: ${data.cryptocurrency.amount} ${data.cryptocurrency.name} via rede ${rede}`;
        origem = `Rede Blockchain`;
        
    } else if (data.currency) {
        // Scenario 1: 100% Fiat (Pix)
        status = data.currency.status;
        mensagem = `Fiat: ${data.currency.amount} ${data.currency.name} via ${data.currency.type}`;
        if (data.document) origem = `Pix (Doc: ${data.document})`;
    }
    
    // Format the origin string only if there is mapped data
    const sufixoOrigem = origem ? ` | Origem: ${origem}` : "";

    // Validate the transaction settlement
    if (status === "PAID") {
        console.log(`[PAGO] ${mensagem}${sufixoOrigem}`);
    } else {
        console.log(`[${status}] ${mensagem}${sufixoOrigem}`);
    }

} catch (error) {
    if (error.response) {
        if (error.response.status === 404) {
            console.error("Error 404: The deposit was not found in the XGate system.");
        } else {
            console.error(`API error (${error.response.status}):`, error.response.data);
        }
    } else {
        console.error("Connection error:", error.message);
    }
}
})();

Endpoint​

Request​

Required Headers​

Responses​

Success (200 OK)​

Field Description​

Common Errors​

How to Use​

Common Use Cases​

Practical Example​

Integration​