Criar Pedido de Depósito

Este endpoint permite gerar uma ordem de depósito (intenção de pagamento) para um cliente específico. Ao criar a ordem, o sistema retorna os dados necessários para que o usuário final realize o pagamento via Pix.

Todo pedido é obrigatoriamente associado a um usuário. Isso garante que o valor seja creditado para o cliente correto em sua plataforma, além de facilitar a conciliação automática e manter um histórico organizado de todas as transações.

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 Pedido de Depósito

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`	`string`	Sim	A moeda da transação (ex: `BRL`).
`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 2 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.1. Passe o _id do cliente como customerId, igual no campo destacado:

{
    "amount": 0.2,
    "customerId": "696d1f3331117************",
    "currency": {
        "_id": "6722ba**************",
        "name": "BRL",
        "type": "PIX",
        "createdDate": "202*********************",
        "updatedDate": "202*********************",
        "__v": 0,
        "symbol": "R$"
    },
    "identifiedDocumentPix": true
}

1.1. Você deve passar o objeto customer que irá criar o cliente ao mesmo tempo em que cria o pedido de depósito:

{
"amount": 0.2,
"customer": {
    "name": "Client Name",
    "document": "12345678900",
    "phone": "+55123456789",
    "email": "client@domain.com"
},
"currency": {
    "_id": "6722ba**************",
    "name": "BRL",
    "type": "PIX",
    "createdDate": "202*********************",
    "updatedDate": "202*********************",
    "__v": 0,
    "symbol": "R$"
},
"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": 0.2,
    "customerId": "696d1f3331117************",
    "currency": {
      "_id": "6722ba**************",
        "name": "BRL",
        "type": "PIX",
        "createdDate": "202*********************",
        "updatedDate": "202*********************",
        "__v": 0,
        "symbol": "R$"
    },
    "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.

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 { data } = await axios.post(`${url_api}/deposit`, {
        amount,
        customerId,
        currency: currencies.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 Pedido de Depósito

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​