Crypto Withdrawal with FIAT Conversion

This endpoint allows the client to redeem their digital assets with automatic conversion to fiat currency. In practice, the system processes the sale of cryptocurrency (e.g., USDT, USDC) and makes the equivalent payment in BRL directly via Pix to the registered key.

Endpoint

Method: POST

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

Test Integration

Use the form below to simulate the creation of a Crypto to FIAT conversion order.

🔄

Test: Crypto to Fiat Withdraw

Request

You need to send the authentication Header and the 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 withdrawal amount in USDT (e.g., `0.1` min).
`customerId`	`string`	Yes	The unique ID (`_id`) of the client making withdrawal.
`currency`	`object`	Yes	The transaction currency (e.g., `BRL`).
`cryptocurrency`	`object`	Yes	The transaction cryptocurrency (e.g., `USDT`, `USDC`).
`pixKey`	`object`	Yes	The client's Pix key for withdrawal.
`externalId`	`string`	No	Idempotency.
`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, containing status information and the transaction _id.

{
  "message": "Solicitação de Saque realizada com sucesso",
  "status": "PENDING",
  "_id": "69849e8c50****************"
}

Common Errors

Status	Message	Likely Reason
401	`Unauthorized`	• Invalid or expired token. • Invalid or missing header. • IP not allowed.
404	`Not Found`	The client informed in the `customerId` field does not exist.
500	`Internal Server Error`	Internal server error. Contact support.

How to Use

The purpose of this endpoint is to initiate the cash-out flow with Crypto to BRL conversion (Cash-out).

The Integration Flow

Identify the Customer: Make sure the user exists in XGate (POST /customer) and have their _id.
Register a Pix Key: After creating the customer, you need to register a Pix key for them at Add Pix Key.
Currency Data: You'll need to fetch the currency and cryptocurrency data to add to the request. You can get them at FIAT Currencies and Cryptocurrencies.
Create the Order: Call this endpoint sending the amount, customerId, currency, cryptocurrency, and pixKey data.
Wait for Payment: The initial status will be PENDING.

Practical Example

To create withdrawal orders converting Crypto to BRL, you should follow these 5 steps:

Recommendation

You need to create a customer before proceeding to create a withdrawal.

You can click here to go to the customer creation documentation page.

Step 1: Pass the value in USDT in the amount field and the customer's _id as customerId, as highlighted in the fields:

{
    "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
    },
    "pixKey": {
        "key": "123**************",
        "type": "CPF",
        "_id": "152535**************"
    },
    "externalId": "67ce09d**************",
    "identifiedDocumentPix": true
}

Step 2: You must obtain the fiat currency with the withdrawal data.

You can get the list by clicking here.

{
    "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
    },
    "pixKey": {
        "key": "123**************",
        "type": "CPF",
        "_id": "152535**************"
    },
    "externalId": "67ce09d**************",
    "identifiedDocumentPix": true
}

Object Details

See the details of each information in the currency object to build your request.

Field	Type	Required	Description
`_id`	`string`	Yes	Unique identifier of the currency.
`name`	`string`	Yes	Name of the currency.
`type`	`string`	Yes	Type of payment method or transaction associated with the currency.
`createdDate`	`string`	No	Date the currency was created in the system.
`updatedDate`	`string`	No	Date of last update of currency information.
`__v`	`number`	No	Version of the currency record in the database.
`symbol`	`string`	Yes	Symbol of the currency.

Step 3: You must obtain the cryptocurrency to perform the withdrawal conversion.

You can get the list by clicking here.

{
    "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
    },
    "pixKey": {
        "key": "123**************",
        "type": "CPF",
        "_id": "152535**************"
    },
    "externalId": "67ce09d**************",
    "identifiedDocumentPix": true
}

Object Details

See the details of each information in the cryptocurrency object to build your request.

Field	Type	Required	Description
`_id`	`string`	Yes	Unique identifier of the cryptocurrency.
`name`	`string`	Yes	Name of the cryptocurrency.
`symbol`	`string`	Yes	Symbol of the cryptocurrency.
`coinGecko`	`string`	No	Cryptocurrency identifier on CoinGecko.
`updatedDate`	`string`	No	Date of last update of cryptocurrency information.
`createdDate`	`string`	No	Date the cryptocurrency was created in the system.
`__v`	`number`	No	Version of the cryptocurrency record in the database.

Step 4: You must get the Pix key data and inform it in the payload for the withdrawal to be processed.

You can get the list of registered Pix keys by clicking here or add a new Pix key.

{
    "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
    },
    "pixKey": {
        "key": "123**************",
        "type": "CPF",
        "_id": "152535**************"
    },
    "externalId": "67ce09d**************",
    "identifiedDocumentPix": true
}

Step 5 (Optional): Add the externalId at the end of the code. It will prevent the customer from submitting the withdrawal request more than once, avoiding duplicates.

{
    "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
    },
    "pixKey": {
        "key": "123**************",
        "type": "CPF",
        "_id": "152535**************"
    },
    "externalId": "67ce09d**************",
    "identifiedDocumentPix": true
}

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 cryptocurrencies = await axios.get(`${url_api}/withdraw/company/cryptocurrencies`, {
            headers: {
                "Authorization": `Bearer ${login.data.token}`
            }
        });
        const currencies = await axios.get(`${url_api}/withdraw/company/currencies`, {
            headers: {
                "Authorization": `Bearer ${login.data.token}`
            }
        });
        const pixKey = await axios.get(`${url_api}/pix/customer/${customerId}/key`, {
            headers: {
                "Authorization": `Bearer ${login.data.token}`
            }
        });
        const { data } = await axios.post(`${url_api}/withdraw/conversion/brl/pix`, {
            amount,
            customerId,
            currency: currencies.data[0],
            cryptocurrency: cryptocurrencies.data[0],
            pixKey: pixKey.data[0]
        }, {
            headers: {
                "Authorization": `Bearer ${login.data.token}`
            }
        });
        console.log(data); // Response
    } catch (error) {
        console.log(error.response.data.message) // Error
    }
})()

Endpoint​

Test Integration​

Test: Crypto to Fiat Withdraw

Request​

Required Headers​

Body (Request Body)​

Responses​

Success (201 Created)​

Common Errors​

How to Use​

The Integration Flow​

Practical Example​

Object Details​

Object Details​

Integration​

Endpoint

Test Integration

Request

Required Headers

Body (Request Body)

Responses

Success (201 Created)

Common Errors

How to Use

The Integration Flow

Practical Example

Object Details

Object Details

Integration