Consultar depósito

Este endpoint permite recuperar con detalle una solicitud de depósito creada previamente. Aunque se usa comúnmente para verificar el "estado del depósito", 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/deposit/TRANSACTION_ID/details

Importante

El valor TRANSACTION_ID en la URL hace referencia al _id del depósito 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. Depósito Pix (Fiat BRL):

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

2. Depósito Pix convirtiendo a Cripto:

{
    "_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. Depósito en Cripto:

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

Descripción de los campos

Nota: La estructura de la respuesta es dinámica. Los depósitos puramente Fiat usan el objeto currency. Los depósitos puramente Cripto usan cryptocurrency. Los depósitos de conversión (Pix ➔ Cripto) 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.
`generatedReceiptAt`	`string`	Fecha y hora exactas en que se generó el comprobante de la transacción (formato ISO 8601).
`idempotencyKey`	`string`	(Condicional) Clave de idempotencia (presente en depósitos en cripto). Esta cadena siempre lleva el ID interno de la cryptocurrency y el hash de la transacción en la blockchain (txHash).
`currency`	`object`	(Condicional) Datos financieros de la operación Fiat (Pix o conversiones). Devuelve propiedades como el estado de liquidación (`status`), el monto final (`amount`), la moneda (`name`) y el método (`type`).
`cryptocurrency`	`object`	(Condicional) Datos de la operación Cripto (Cripto o conversiones). Devuelve el estado en la blockchain (`status`), el monto procesado (`amount`), los datos de la moneda (`name`, `symbol`, `coinGecko`) y los detalles de la red utilizada (`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 depósito 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 depósitos 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 pagador (document) de un depósito recibido 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 depósitos "Pending" usando este endpoint para actualizar los estados perdidos y liberar el saldo al usuario.
Atención al cliente (CS): Consultar los datos de un depósito específico en tiempo real para ayudar a un cliente final que envió los fondos pero dice que el saldo no se registró en la plataforma.

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 el pago:

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

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 depósito
    const { data } = await axios.get(`${url_api}/deposit/${transactionId}/details`, {
        headers: {
            "Authorization": `Bearer ${login.data.token}`
        }
    });
    
    console.log("Detalles del depósito:", data);
    
    // Lógica dinámica para identificar el tipo de depósito según la respuesta
    let status = "Unknown";
    let mensaje = "";
    let origen = ""; // Se inicia vacío para evitar mostrar información incorrecta

    if (data.currency && data.cryptocurrency) {
        // Escenario 2: Conversión (Pix -> Cripto)
        status = data.cryptocurrency.status;
        mensaje = `Conversión: Entraron ${data.currency.amount} ${data.currency.name} y se convirtieron en ${data.cryptocurrency.amount} ${data.cryptocurrency.name}`;
        if (data.document) origen = `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}`;
        origen = `Red blockchain`;
        
    } 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) origen = `Pix (Doc: ${data.document})`;
    }
    
    // Formatear la cadena de origen solo si hay datos mapeados
    const sufijoOrigem = origen ? ` | Origen: ${origen}` : "";

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

} catch (error) {
    if (error.response) {
        if (error.response.status === 404) {
            console.error("Error 404: El depósito no fue encontrado en el sistema de XGate.");
        } else {
            console.error(`Error de 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​