Create Deposit Order

This endpoint creates a deposit order (payment intent) for a specific customer. When the order is created, the system returns the data required for the end user to complete the payment via Pix.

Every order must be associated with a customer. This ensures the funds are credited to the correct customer on your platform, enables automatic reconciliation, and keeps a clean history of all transactions.

Endpoint

Method: POST

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

Test Integration

Use the form below to simulate creating an order and generate the QR Code.

💲 Test: Create Deposit Order

Request

You must provide the authentication Header and the request Body with the order data.

Required Headers

Header	Value	Description
`Authorization`	`Bearer <your_token>`	The JWT token obtained at login.

Body (Request Body)

Field	Type	Required	Description
`amount`	`number`	Yes	The deposit amount (ex: `100.50`).
`customerId`	`string`	No	The customer's unique `_id` who will make the deposit.
`customer`	`object`	No	Customer data to create the customer together with the deposit order.
`currency`	`string`	Yes	The transaction currency (ex: `BRL`).
`externalId`	`string`	No	Idempotency identifier.
`identifiedDocumentPix`	`boolean`	No	When `true`, forces Pix document ownership verification.

About ownership validation

Sending the identifiedDocumentPix parameter with the value false (or omitting it) does not disable the ownership check if it is configured as mandatory in the XGate administrative panel for your account.

This parameter strictly serves to force the validation (by sending true) on accounts where the panel's default rule is disabled. To permanently disable document ownership verification, a commercial alignment via contract is required.

Important: Customer Identification

To create a deposit, it is mandatory to identify the user. You must send the customerId (if the client already exists) OR the customer object (to create a new client at the time of the request).

Never send both fields in the same request, as this will result in a transaction failure.

Best Practices: Duplication Prevention

We strongly recommend sending the externalId field. It acts as an idempotency key, ensuring that the same deposit request is not created in duplicate in case of network failure, double clicks, or accidental retries by your system.

Responses

Success (201 Created)

Returns the created order object, including the code (Pix Copia e Cola) for the user to pay.

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

Common Errors

Status	Message	Likely Cause
401	`Unauthorized`	• Invalid or expired token. • Invalid or missing header. • IP not allowed.
404	`Not Found`	The `customerId` provided does not exist.
409	`Conflict`	• The provided customer name is already registered. • The provided document is already registered.
500	`Internal Server Error`	Internal server error. Contact support.

How to use

This endpoint starts the cash-in flow.

The most important return value is the code field. It contains the "Pix Copia e Cola" string. Display this code to your end user or generate a visual QR Code from it.

Integration Flow

Create/Identify the Customer: Ensure the user exists in XGate (POST /customer) and obtain their _id.
Create the Order: Call this endpoint with the amount and the customer ID (or customer object).
Show the Pix: Take the code from the response and present it to the user.
Wait for Payment: The initial status will be PENDING. Once the user pays, the status will update (via Webhook or polling).

Practical Example

To create Pix deposit orders follow these two steps:

Step 1: You can create the deposit order with an existing customer (POST /customer) or create the customer at the same time.

Recomendação

The XGate team recommends creating the customer using the customers creation endpoint (POST /customer).

You can click here to open the customer creation documentation.

With Customer
Without Customer

1.1. Pass the customer's _id as customerId, as shown in the highlighted field:

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

1.1. You must pass the customer object to create the customer together with the deposit order:

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

The name and document fields are required.

Step 2: Obtain the fiat currency for the deposit.

You can get the list by clicking here.

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

Object Details

See details for each field in the currency object to build your request.

Field	Type	Required	Description
`_id`	`string`	Yes	Unique identifier of the currency.
`name`	`string`	Yes	Currency name.
`type`	`string`	Yes	Payment method or transaction type associated with the currency.
`createdDate`	`string`	No	Date when the currency was created in the system.
`updatedDate`	`string`	No	Date of the last update to the currency information.
`__v`	`number`	No	Database record version for the currency.
`symbol`	`string`	Yes	Currency symbol.

Integration

Node.js

The integration example uses the Axios library in Node.js.

Installing Axios:

npm install axios

JavaScript Example:

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​

Test Integration​

💲 Test: Create Deposit Order

Request​

Required Headers​

Body (Request Body)​

Responses​

Success (201 Created)​

Common Errors​

How to use​

Integration Flow​

Practical Example​

Object Details​

Integration​