Depósito crypto con conversión

Este endpoint genera una orden de depósito con conversión automática. El cliente realiza el pago en moneda fiduciaria (Pix/BRL) y el importe se acredita en criptomonedas (por ejemplo, USDT) en su cartera.

Cada orden está asociada necesariamente a un usuario. Esto garantiza que el saldo convertido se entregue correctamente, además de facilitar la conciliación y mantener un historial organizado de todas las operaciones de cambio.

Endpoint

Método: POST

URL del endpoint
https://api.xgateglobal.com/deposit

Prueba de integración

Utilice el formulario a continuación para simular la creación de una orden y generar el código QR.

💲 Probar: Crear Depósito (Pix a Crypto)

Solicitud

Debe enviar el encabezado de autenticación y el cuerpo con los datos de la orden.

Encabezados obligatorios

Encabezado	Valor	Descripción
`Authorization`	`Bearer <tu_token>`	El token JWT obtenido al iniciar sesión.

Cuerpo (Request Body)

Campo	Tipo	Obligatorio	Descripción
`amount`	`number`	Sí	El importe del depósito (por ejemplo, `100.50`).
`customerId`	`string`	No	El ID único (`_id`) del cliente que realizará el depósito.
`customer`	`object`	No	Datos para crear el cliente junto con la orden de depósito.
`currency`	`object`	Sí	La moneda de la transacción (por ejemplo, `BRL`).
`cryptocurrency`	`object`	Sí	Criptomoneda de destino para la conversión (por ejemplo, USDT o USDC).
`externalId`	`string`	No	Idempotencia
`identifiedDocumentPix`	`boolean`	No	Cuando es `true`, fuerza la verificación de titularidad del documento en Pix.

Sobre la validación de titularidad

El envío del parámetro identifiedDocumentPix con el valor false (o su ausencia) no desactiva la verificación de titularidad si está configurada como obligatoria en el panel administrativo de XGate para tu cuenta.

Este parámetro sirve estrictamente para forzar la validación (enviando true) en cuentas donde la regla predeterminada del panel está desactivada. Para desactivar la verificación de titularidad de manera definitiva, es necesario un acuerdo comercial vía contrato.

Importante: Identificación del Cliente

Para crear un depósito, es obligatorio identificar al usuario. Debes enviar el customerId (si el cliente ya existe) O el objeto customer (para crear un nuevo cliente en el momento del pedido).

Nunca envíes ambos campos en la misma solicitud, ya que esto resultará en una falla de la transacción.

Buenas Prácticas: Prevención de Duplicidad

Recomendamos encarecidamente enviar el campo externalId. Actúa como una clave de idempotencia, garantizando que el mismo pedido de depósito no se cree por duplicado en caso de fallas en la red, doble clic o reintentos accidentales por parte de tu sistema.

Respuestas

Éxito (201 Created)

Devuelve el objeto de la orden creada, que contiene el code (Pix Copia y pega) para que el usuario lo pague.

{
  "message": "Pix Gerado com Sucesso",
  "data": {
    "status": "WAITING_PAYMENT",
    "code": "00020126850014br.gov.bcb.pix2563pi************************************************************************************",
    "id": "696e28a43e09**************",
    "customerId": "68e7b8f0db**************"
  }
}

Errores comunes

Estado	Mensaje	Posible causa
401	`Unauthorized`	• Token inválido o vencido. • Encabezado faltante o inválido. • IP no permitida.
404	`Not Found`	El cliente indicado en el campo `customerId` no existe.
409	`Conflict`	• El nombre de cliente proporcionado ya está registrado. • El documento proporcionado ya está registrado.
500	`Internal Server Error`	Error interno del servidor. Contacte con soporte.

Cómo usar

El propósito de este endpoint es iniciar el flujo de entrada de dinero (Cash-in).

El retorno más importante aquí es el campo code. Contiene la cadena de "Pix Copia y pega". Debe mostrar este código a su usuario final o generar un código QR visual a partir de él.

Flujo de integración

Crear/identificar al cliente: Asegúrese de que el usuario exista en XGate (POST /customer) y tenga su _id.
Crear la orden: Llame a este endpoint pasando el importe y el ID del cliente.
Mostrar el Pix: Tome el code de la respuesta y muéstrelo al usuario.
Esperar el pago: El estado inicial será PENDING. Tan pronto como el usuario pague, el estado cambiará (a través de webhook o consulta).

Ejemplo práctico

Para crear órdenes de depósito Pix, debe seguir estos 3 pasos:

Paso 1: Aquí tiene las opciones para crear la orden de depósito sin un cliente ya creado por la ruta (POST /customer) o con uno ya creado.

Recomendación

El equipo de XGate recomienda que el cliente se cree mediante la ruta de creación de clientes (POST /customer).

Puede hacer clic aquí para ir a la página de documentación de creación de clientes.

Con cliente
Sin cliente

1. Pase el _id del cliente como customerId, igual que en el campo resaltado:

{
    "amount": 2,
    "customerId": "672f40**************",
    "currency": {
        "_id": "6722ba**************",
        "name": "BRL",
        "type": "PIX",
        "createdDate": "202*********************",
        "updatedDate": "202*********************",
        "__v": 0,
        "symbol": "R$"
    },
    "cryptocurrency": {
        "_id": "67ce09d**************",
        "name": "USDT",
        "symbol": "USDT",
        "coinGecko": "usdt",
        "updatedDate": "202*********************",
        "createdDate": "202*********************",
        "__v": 0
    },
    "externalId": "67ce09d**************",
    "identifiedDocumentPix": true
}

1. Debe pasar el objeto customer, que creará el cliente al mismo tiempo que crea la orden de depósito:

{
    "amount": 2,
    "customer": {
        "name": "Nombre",
        "phone": "92*********",
        "email": "email@example.com",
        "document": "123*********"
    }, 
    "currency": {
        "_id": "6722c8f***************",
        "name": "BRL",
        "type": "PIX",
        "createdDate": "202*********************",
        "updatedDate": "202*********************",
        "__v": 0,
        "symbol": "R$"
    },
    "cryptocurrency": {
        "_id": "67ca33*********************",
        "name": "USDT",
        "symbol": "USDT",
        "coinGecko": "usdt",
        "updatedDate": "202*********************",
        "createdDate": "202*********************",
        "__v": 0
    },
    "externalId": "67ce09d**************",
    "identifiedDocumentPix": true
}

Importante

Los datos name y document son obligatorios.

Paso 2: Debe obtener la moneda fiduciaria para la que está haciendo el depósito.

Puede obtener la lista de ellas haciendo clic aquí.

{
    "amount": 2,
    "customerId": "672f40**************",
    "currency": {
        "_id": "6722ba**************",
        "name": "BRL",
        "type": "PIX",
        "createdDate": "202*********************",
        "updatedDate": "202*********************",
        "__v": 0,
        "symbol": "R$"
    },
    "cryptocurrency": {
        "_id": "67ce09d**************",
        "name": "USDT",
        "symbol": "USDT",
        "coinGecko": "usdt",
        "updatedDate": "202*********************",
        "createdDate": "202*********************",
        "__v": 0
    },
    "externalId": "67ce09d**************",
    "identifiedDocumentPix": true
}

Paso 3: Debe obtener la criptomoneda para realizar la conversión.

Puede obtener la lista de ellas haciendo clic aquí.

{
    "amount": 2,
    "customerId": "672f40**************",
    "currency": {
        "_id": "6722ba**************",
        "name": "BRL",
        "type": "PIX",
        "createdDate": "202*********************",
        "updatedDate": "202*********************",
        "__v": 0,
        "symbol": "R$"
    },
    "cryptocurrency": {
        "_id": "67ce09d**************",
        "name": "USDT",
        "symbol": "USDT",
        "coinGecko": "usdt",
        "updatedDate": "202*********************",
        "createdDate": "202*********************",
        "__v": 0
    },
    "externalId": "67ce09d**************",
    "identifiedDocumentPix": true
}

Detalles del objeto

Consulte los detalles de cada información en el objeto currency para construir su solicitud.

Campo	Tipo	Obligatorio	Descripción
`_id`	`string`	Sí	Identificador único de la moneda.
`name`	`string`	Sí	Nombre de la moneda.
`type`	`string`	Sí	Tipo de método de pago o transacción asociado a la moneda.
`createdDate`	`string`	No	Fecha en que la moneda se creó en el sistema.
`updatedDate`	`string`	No	Fecha de la última actualización de la información de la moneda.
`__v`	`number`	No	Versión del registro de la moneda en la base de datos.
`symbol`	`string`	Sí	Símbolo de la moneda.

Consulte los detalles de cada información en el objeto cryptocurrency para construir su solicitud.

Campo	Tipo	Obligatorio	Descripción
`_id`	`string`	Sí	Identificador único de la criptomoneda.
`name`	`string`	Sí	Nombre de la criptomoneda.
`symbol`	`string`	Sí	Símbolo de la criptomoneda.
`coinGecko`	`string`	No	Identificador de la criptomoneda en CoinGecko.
`updatedDate`	`string`	No	Fecha de la última actualización de la información de la criptomoneda.
`createdDate`	`string`	No	Fecha en que la criptomoneda se creó en el sistema.
`__v`	`number`	No	Versión del registro de la criptomoneda en la base de datos.

Integración

Node.js

Este ejemplo de integración utiliza la librería Axios en Node.js.

Instalando Axios:

npm install axios

Ejemplo en JavaScript:

const axios = require("axios");

(async () => {
    const email = "your_email@domain.com";
    const password = "**********";
    const customerId = "*************";
    const amount = 10.90;

    try {
        const url_api = "https://api.xgateglobal.com"
        const login = await axios.post(`${url_api}/auth/token`, { email, password });
        const currencies = await axios.get(`${url_api}/deposit/company/currencies`, {
            headers: {
                "Authorization": `Bearer ${login.data.token}`
            }
        });
        const cryptocurrencies = await axios.get(`${url_api}/deposit/company/cryptocurrencies`, {
            headers: {
                "Authorization": `Bearer ${login.data.token}`
            }
        });
        const { data } = await axios.post(`${url_api}/deposit`, {
            amount,
            customerId,
            currency: currencies.data[0],
            cryptocurrency: cryptocurrencies.data[0]
        }, {
            headers: {
                "Authorization": `Bearer ${login.data.token}`
            }
        });
        console.log(data); // Respuesta
    } catch (error) {
        console.log(error.response.data.message) // Error
    }
})()

Endpoint​

Prueba de integración​

💲 Probar: Crear Depósito (Pix a Crypto)

Solicitud​

Encabezados obligatorios​

Cuerpo (Request Body)​

Respuestas​

Éxito (201 Created)​

Errores comunes​

Cómo usar​

Flujo de integración​

Ejemplo práctico​

Detalles del objeto​

Integración​