Query Withdrawal

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

---

Endpoint

• Method: GET

Endpoint URL

https://api.xgateglobal.com/withdraw/ID_TRANSACTION/details

Important

The value ID_TRANSACTION in the URL refers to the _id of the withdrawal 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. FIAT Withdrawal (BRL):

{
    "_id": "6a3da740e5****************",
    "externalId": "external-id-webhook-0101",
    "currency": {
        "type": "PIX",
        "name": "BRL",
        "status": "PAID",
        "amount": 0.2
    },
    "status": "APPROVED",
    "generatedReceiptAt": "2026-06-25T22:10:18.579Z",
    "customerId": "6a1a379e1fe**************"
}

2. Crypto Withdrawal to Fiat:

{
    "_id": "6a3da803e51**************",
    "externalId": "external-id-webhook-0102",
    "cryptocurrency": {
        "name": "USDT",
        "symbol": "USDT",
        "coinGecko": "tether",
        "amount": 0.2,
        "status": "PAID"
    },
    "currency": {
        "type": "PIX",
        "name": "BRL",
        "status": "PAID",
        "amount": 1.05
    },
    "status": "APPROVED",
    "generatedReceiptAt": "2026-06-25T22:13:33.487Z",
    "customerId": "6a1a379e1fe**************"
}

3. Crypto Withdrawal to Crypto:

{
    "_id": "6a3d9ed4********************",
    "cryptocurrency": {
        "name": "USDT",
        "symbol": "USDT",
        "amount": 1,
        "status": "PAID",
        "coinGecko": "tether",
        "blockchainNetwork": {
            "name": "Solana",
            "chain": "Solana",
            "symbol": "SOL"
        }
    },
    "status": "APPROVED",
    "generatedReceiptAt": "2026-06-25T21:36:03.045Z",
    "customerId": "6a1a379e1fe9********************"
}

Field Description

Note: The response structure is dynamic. Pure Fiat withdrawals use the currency object. Pure Crypto withdrawals use cryptocurrency. Conversion withdrawals (Crypto ➔ Pix) 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.
externalId	string	(Optional) The order ID in your system, if it was sent when the withdrawal was created.
status	string	General approval/processing status of the withdrawal on the XGate platform (ex: APPROVED).
generatedReceiptAt	string	Exact date and time when the transaction receipt was generated (ISO 8601 format).
currency	object	(Conditional) Financial data for the Fiat operation (Pix or Conversions). Returns properties such as payment status (status), paid/converted amount (amount), currency (name), and destination method (type).
cryptocurrency	object	(Conditional) Data for the Crypto operation (Crypto or Conversions). Returns network transfer status (status), deducted amount (amount), token data (name, symbol, coinGecko), and network details (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 withdrawal 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 withdrawals 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:

1. Reconciliation and Auditing: Confirm whether the amount (amount), network data (blockchainNetwork), or recipient (document/wallet) of a withdrawal processed by XGate matches exactly with your internal database.
2. Failure Recovery (Fallback): If your server goes offline and you miss receiving a Webhook, you can create a routine (CRON) that queries "Pending" withdrawals using this endpoint to update lost statuses.
3. Customer Support (CS): Fetch the data of a specific withdrawal in real time to help an end customer who is questioning the progress of a withdrawal or the network fee amount (gasFeeAmount).

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

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 = "6a3da740e5***************";

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 withdrawal details
    const { data } = await axios.get(`${url_api}/withdraw/${transactionId}/details`, {
        headers: {
            "Authorization": `Bearer ${login.data.token}`
        }
    });
    
    console.log("Detalhes do Saque:", data);
    
    // Dynamic logic to identify the withdrawal type based on the response
    let status = "Unknown";
    let mensagem = "";
    let destino = ""; // Starts empty to avoid false or undefined information

    if (data.currency && data.cryptocurrency) {
        // Scenario 2: Conversion (Crypto -> Pix)
        // We read the status from 'currency' since it is the final Fiat endpoint delivered to the customer
        status = data.currency.status; 
        mensagem = `Conversão: Saiu ${data.cryptocurrency.amount} ${data.cryptocurrency.name} e pagou ${data.currency.amount} ${data.currency.name}`;
        if (data.document) destino = `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}`;
        if (data.cryptocurrency.wallet) destino = `Carteira: ${data.cryptocurrency.wallet}`;
        
    } 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) destino = `Pix (Doc: ${data.document})`;
    }
    
    // Format the destination string only if there is mapped data
    const sufixoDestino = destino ? ` | Destino: ${destino}` : "";

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

} catch (error) {
    if (error.response) {
        if (error.response.status === 404) {
            console.error("Erro 404: O saque não foi encontrado no sistema da XGate.");
        } else {
            console.error(`Erro na API (${error.response.status}):`, error.response.data);
        }
    } else {
        console.error("Erro de Conexão:", error.message);
    }
}
})();