Depósito com Conversão Crypto

Este endpoint gera uma ordem de depósito com conversão automática. O cliente realiza o pagamento em moeda fiduciária (Pix/BRL) e o valor é creditado em criptomoeda (ex: USDT) na carteira dele.

Todo pedido é obrigatoriamente associado a um usuário. Isso garante que o saldo convertido seja entregue corretamente, além de facilitar a conciliação e manter um histórico organizado de todas as operações de câmbio.

Endpoint

Método: POST

URL do Endpoint
https://api.xgateglobal.com/deposit

Testar Integração

Utilize o formulário abaixo para simular a criação de um pedido e gerar o QR Code.

💲 Testar: Criar Depósito (Pix para Crypto)

Requisição

É necessário enviar o Header de autenticação e o Body com os dados do pedido.

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	`Bearer <seu_token>`	O token JWT obtido no login.

Body (Corpo da Requisição)

Campo	Tipo	Obrigatório	Descrição
`amount`	`number`	Sim	O valor do depósito (ex: `100.50`).
`customerId`	`string`	Não	O ID único (`_id`) do cliente que fará o depósito.
`customer`	`object`	Não	Dados para a criação do cliente junto da criação do pedido de depósito.
`currency`	`object`	Sim	A moeda da transação (ex: `BRL`).
`cryptocurrency`	`object`	Sim	Criptomoeda de destino para a conversão (ex: USDT ou USDC).
`externalId`	`string`	Não	Idempotência
`identifiedDocumentPix`	`boolean`	Não	Quando `true`, força a verificação de titularidade do documento no Pix.

Sobre a validação de titularidade

O envio do parâmetro identifiedDocumentPix com o valor false (ou a ausência dele) não desativa a checagem de titularidade caso ela esteja configurada como obrigatória no painel administrativo da XGate para a sua conta.

Este parâmetro serve estritamente para forçar a validação (enviando true) em contas onde a regra padrão do painel está desativada. Para desativar a verificação de titularidade de forma definitiva, é necessário alinhar comercialmente via contrato.

Importante: Identificação do Cliente

Para criar um depósito, é obrigatório identificar o utilizador. Você deve enviar o customerId (caso o cliente já exista) OU o objeto customer (para criar um novo cliente no momento do pedido).

Nunca envie ambos os campos na mesma requisição, pois isso resultará em falha na transação.

Boas Práticas: Prevenção de Duplicidade

Recomendamos fortemente o envio do campo externalId. Ele atua como uma chave de idempotência, garantindo que o mesmo pedido de depósito não seja criado em duplicidade em caso de falha de rede, cliques duplos ou retentativas acidentais pelo seu sistema.

Respostas (Responses)

Sucesso (201 Created)

Retorna o objeto do pedido criado, contendo o code (Pix Copia e Cola) para o usuário pagar.

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

Erros Comuns

Status	Mensagem	Motivo Provável
401	`Unauthorized`	• Token inválido ou expirado. • Header inválido ou não informado. • IP não permitido.
404	`Not Found`	Cliente informado no campo `customerId` não existe.
409	`Conflict`	• Nome do cliente informado já está cadastrado. • Documento informado já está cadastrado.
500	`Internal Server Error`	Erro interno de servidor. Entrar em contato com suporte.

Como usar

A finalidade deste endpoint é iniciar o fluxo de entrada de dinheiro (Cash-in).

O retorno mais importante aqui é o campo code. Ele contém a string do "Pix Copia e Cola". Você deve exibir esse código para o seu usuário final ou gerar um QR Code visual a partir dele.

O Fluxo de Integração

Crie/Identifique o Cliente: Certifique-se de que o usuário existe na XGate (POST /customer) e tenha o _id dele.
Crie o Pedido: Chame este endpoint passando o valor e o ID do cliente.
Exiba o Pix: Pegue o code da resposta e mostre ao usuário.
Aguarde o Pagamento: O status inicial será PENDING. Assim que o usuário pagar, o status mudará (via Webhook ou consulta).

Exemplo Prático

Para criar pedidos de depósito Pix, você deve seguir esses 3 passos:

1. Passo: Aqui você tem as opções de criar o pedido de depósito sem um cliente ainda criado pela rota (POST /customer) ou com um já criado.

Recomendação

A equipe XGate recomenda que o cliente seja criado pela rota de criação de clientes (POST /customer).

Você pode estar clicando aqui para ir para a página de documentação de criação de cliente.

Com Cliente
Sem Cliente

1. Passe o _id do cliente como customerId, igual no campo destacado:

{
    "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. Você deve passar o objeto customer que irá criar o cliente ao mesmo tempo em que cria o pedido de depósito:

{
    "amount": 2,
    "customer": {
        "name": "Name",
        "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

Os dados name e document são obrigatórios.

2. Passo: Você deve obter a moeda fiduciária para qual está realizando o depósito.

Você pode obter a lista delas clicando aqui.

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

3. Passo: Você deve obter a criptomoeda para realizar a conversão.

Você pode obter a lista delas clicando aqui.

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

Detalhes do Objeto

Veja os detalhes de cada informação no objeto currency para montar sua requisição.

Campo	Tipo	Obrigatório	Descrição
`_id`	`string`	Sim	Identificador único da moeda.
`name`	`string`	Sim	Nome da moeda.
`type`	`string`	Sim	Tipo do método de pagamento ou transação associado à moeda.
`createdDate`	`string`	Não	Data em que a moeda foi criada no sistema.
`updatedDate`	`string`	Não	Data da última atualização das informações da moeda.
`__v`	`number`	Não	Versão do registro da moeda no banco de dados.
`symbol`	`string`	Sim	Símbolo da moeda.

Veja os detalhes de cada informação no objeto cryptocurrency para montar sua requisição.

Campo	Tipo	Obrigatório	Descrição
`_id`	`string`	Sim	Identificador único da criptomoeda.
`name`	`string`	Sim	Nome da criptomoeda.
`symbol`	`string`	Sim	Símbolo da criptomoeda.
`coinGecko`	`string`	Não	Identificador da criptomoeda no CoinGecko.
`updatedDate`	`string`	Não	Data da última atualização das informações da criptomoeda.
`createdDate`	`string`	Não	Data em que a criptomoeda foi criada no sistema.
`__v`	`number`	Não	Versão do registro da criptomoeda no banco de dados.

Integração

Node.js

O exemplo de integração utiliza a biblioteca Axios em Node.js.

Instalando Axios:

npm install axios

Exemplo 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],
            identifiedDocumentPix: true
        }, {
            headers: {
                "Authorization": `Bearer ${login.data.token}`
            }
        });
        console.log(data); // Response
    } catch (error) {
        console.log(error.response.data.message) // Error
    }
})()

Endpoint​

Testar Integração​

💲 Testar: Criar Depósito (Pix para Crypto)

Requisição​

Headers Obrigatórios​

Body (Corpo da Requisição)​

Respostas (Responses)​

Sucesso (201 Created)​

Erros Comuns​

Como usar​

O Fluxo de Integração​

Exemplo Prático​

Detalhes do Objeto​

Integração​