Consultar retiro

Este endpoint permite recuperar con detalle una solicitud de retiro creada previamente. Aunque se usa comúnmente para verificar el "estado del retiro", devuelve el objeto completo con toda la información vital de la transacción.

Endpoint

Método: GET

URL del endpoint
https://api.xgateglobal.com/withdraw/ID_TRANSACTION/details

Importante

El valor ID_TRANSACTION en la URL hace referencia al _id del retiro generado por XGate en el momento en que se creó la solicitud.

Solicitud

Encabezados obligatorios

Encabezado	Valor	Descripción
`Authorization`	`Bearer <tu_token>`	Token JWT de autenticación obtenido al iniciar sesión.

Respuestas

Éxito (200 OK)

La transacción fue encontrada. La estructura de los datos devueltos varía según el tipo de operación (Fiat o Cripto).

1. Retiro FIAT (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. Retiro en Cripto a 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. Retiro en Cripto a Cripto:

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

Descripción de los campos

Nota: La estructura de la respuesta es dinámica. Los retiros puramente Fiat usan el objeto currency. Los retiros puramente Cripto usan cryptocurrency. Los retiros de conversión (Cripto ➔ Pix) devuelven ambos.

Campo	Tipo	Descripción
`_id`	`string`	ID único de la transacción generado por XGate.
`customerId`	`string`	ID del cliente asociado a la transacción en XGate.
`externalId`	`string`	(Opcional) El ID del pedido en su sistema, si se envió cuando se creó el retiro.
`status`	`string`	Estado general de aprobación/procesamiento del retiro en la plataforma de XGate (por ejemplo, `APPROVED`).
`generatedReceiptAt`	`string`	Fecha y hora exactas en que se generó el comprobante de la transacción (formato ISO 8601).
`currency`	`object`	(Condicional) Datos financieros de la operación Fiat (Pix o conversiones). Devuelve propiedades como el estado de pago (`status`), el monto pagado/convertido (`amount`), la moneda (`name`) y el método de destino (`type`).
`cryptocurrency`	`object`	(Condicional) Datos de la operación Cripto (Cripto o conversiones). Devuelve el estado de la transferencia en la red (`status`), el monto descontado (`amount`), los datos del token (`name`, `symbol`, `coinGecko`) y los detalles de la red (`blockchainNetwork`).

Errores comunes

Estado	Mensaje	Causa probable
401	`Unauthorized`	• Token inválido o caducado. • Encabezado inválido o no proporcionado. • IP no permitida.
404	`Not Found`	• El ID de transacción proporcionado no es válido. • El retiro no existe en el sistema.
500	`Internal Server Error`	Error interno del servidor. Contacte con soporte.

Cómo usar

Aunque la forma más eficiente de hacer seguimiento de los retiros es mediante los webhooks, esta ruta de consulta es un endpoint esencial de lectura para mantener su sistema.

Casos de uso comunes

Usará este endpoint principalmente en las siguientes situaciones:

Conciliación y auditoría: Confirmar si el monto (amount), los datos de la red (blockchainNetwork) o el destinatario (document/wallet) de un retiro procesado por XGate coinciden exactamente con su base de datos interna.
Recuperación ante fallos (fallback): Si su servidor se cae y pierde la recepción de un webhook, puede crear una rutina (CRON) que consulte los retiros "Pending" usando este endpoint para actualizar los estados perdidos.
Atención al cliente (CS): Consultar los datos de un retiro específico en tiempo real para ayudar a un cliente final que está cuestionando el progreso de un retiro o el monto de la comisión de red (gasFeeAmount).

Ejemplo práctico

El propósito principal es verificar el progreso de la transacción. Al consultar el endpoint, se centrará en el campo status correspondiente a la operación para determinar qué mostrar a su cliente final.

Comprobando la liquidación:

En el código a continuación, el sistema valida si la respuesta tiene el objeto currency (Fiat) o cryptocurrency (Cripto) para extraer el estado correcto de la transacción:

Integración

A continuación se muestra un ejemplo sencillo de cómo implementar esta consulta con Node.js.

Node.js

El ejemplo de integración utiliza la librería Axios para realizar la solicitud HTTP.

Instalando Axios:

npm install axios

Ejemplo en JavaScript:

const axios = require("axios");

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

try {
    const url_api = "https://api.xgateglobal.com";
    
    // 1. Obtener el token de autenticación
    const login = await axios.post(`${url_api}/auth/token`, { email, password });
    
    // 2. Consultar los detalles del retiro
    const { data } = await axios.get(`${url_api}/withdraw/${transactionId}/details`, {
        headers: {
            "Authorization": `Bearer ${login.data.token}`
        }
    });
    
    console.log("Detalles del retiro:", data);
    
    // Lógica dinámica para identificar el tipo de retiro según la respuesta
    let status = "Unknown";
    let mensaje = "";
    let destino = ""; // Se inicia vacío para evitar información falsa o indefinida

    if (data.currency && data.cryptocurrency) {
        // Escenario 2: Conversión (Cripto -> Pix)
        // Leemos el estado desde 'currency' ya que es el endpoint Fiat final entregado al cliente
        status = data.currency.status; 
        mensaje = `Conversión: Salieron ${data.cryptocurrency.amount} ${data.cryptocurrency.name} y pagaron ${data.currency.amount} ${data.currency.name}`;
        if (data.document) destino = `Pix (Doc: ${data.document})`;
        
    } else if (data.cryptocurrency) {
        // Escenario 3: 100% Cripto
        status = data.cryptocurrency.status;
        const rede = data.cryptocurrency.blockchainNetwork?.name || "Desconocida";
        mensaje = `Cripto: ${data.cryptocurrency.amount} ${data.cryptocurrency.name} vía red ${rede}`;
        if (data.cryptocurrency.wallet) destino = `Billetera: ${data.cryptocurrency.wallet}`;
        
    } else if (data.currency) {
        // Escenario 1: 100% Fiat (Pix)
        status = data.currency.status;
        mensaje = `Fiat: ${data.currency.amount} ${data.currency.name} vía ${data.currency.type}`;
        if (data.document) destino = `Pix (Doc: ${data.document})`;
    }
    
    // Formatear la cadena de destino solo si hay datos mapeados
    const sufijoDestino = destino ? ` | Destino: ${destino}` : "";

    // Validar la liquidación de la transacción
    if (status === "PAID") {
        console.log(`[PAGADO] ${mensaje}${sufijoDestino}`);
    } else {
        console.log(`[${status}] ${mensaje}${sufijoDestino}`);
    }

} catch (error) {
    if (error.response) {
        if (error.response.status === 404) {
            console.error("Error 404: El retiro no fue encontrado en el sistema de XGate.");
        } else {
            console.error(`Error en la API (${error.response.status}):`, error.response.data);
        }
    } else {
        console.error("Error de conexión:", error.message);
    }
}
})();

Endpoint​

Solicitud​

Encabezados obligatorios​

Respuestas​

Éxito (200 OK)​

Descripción de los campos​

Errores comunes​

Cómo usar​

Casos de uso comunes​

Ejemplo práctico​

Integración​