🛠️
Integration Guide
  • 🔎Overview
    • 👋Welcome to XGateway
  • 🏎️QUICK START
    • Integrate with XGateway
    • Supported currencies
    • Keys and authentication
    • KYC
  • ⚙️INTEGRATION GUIDES
    • Integration using Checkout Page
      • Floating Rate invoices (deprecated)
    • Integration using API
      • Exchange rate service
    • Callbacks
      • Transaction callback
        • Transaction object
      • Bank Account callback
      • KYC callback
    • How to initiate a withdrawal
    • Environments
  • 💱Payment flows
    • Transaction flowchart
    • KYC checks diagram
    • Confirmation subprocess
    • User flow for crypto onramp
    • User flow for banking onramp
    • Fees structure
      • Adjustable BTC Minimum Deposit Fee Framework
  • 🏤Back office
Powered by GitBook
On this page
  1. INTEGRATION GUIDES

How to initiate a withdrawal

Learn how to initiate a withdrawal of funds to your customer.

PreviousKYC callbackNextEnvironments

Last updated 11 days ago

Crypto

To withdraw crypto funds on behalf of a certain customer, you can make a POST request with the following data to one of the API endpoints.

If applicationId and orderId are passed when creating an invoice, the callback will contain them after the transaction is processed.

Fiat

To withdraw fiat funds on behalf of a certain customer, you can make a POST request with the following data to one of the API endpoints.

Contact our support team to confirm the available payment systems.

Using a free-form

Initiates withdrawal of fiat funds using a free-form (v1)

POST https://api.xgateway.tech/api/v1/withdrawal

Headers

Name
Type
Description

x-api-key*

String

Your API key

Request Body

Name
Type
Description

customerId*

String

The unique customer ID who initiated the withdrawal

amount*

String

The amount to withdraw

currency*

String

orderId

String

The unique order ID in your system

applicationId

String

The application ID if you have multiple

comment

String

The comment (max 255 symbols)

paymentSystem

String

The payment system to process withdrawal with

recipient*

String

The recipient information

Initiates withdrawal of fiat funds using a free-form (v2)

POST https://api.xgateway.tech/api/v2/withdrawal

Headers

Name
Type
Description

x-api-key*

String

Your API key

Request Body

Name
Type
Description

customerId*

String

The unique customer ID who initiated the withdrawal

amount*

String

The amount to withdraw

currency*

String

orderId

String

The unique order ID in your system

applicationId

String

The application ID if you have multiple

comment

String

The comment (max 255 symbols)

paymentSystem

String

The payment system to process withdrawal with

recipient*

String

The recipient information

Example of the request body
{
    "amount": "1000",
    "applicationId": "test_application_id",
    "comment": "fiat withdrawal using a free-form",
    "currency": "INR",
    "customerId": "21c5e78e-95b9-11ed-a1eb-0242ac120002",
    "orderId": "ef3e9b1e-712a-4122-848f-4838a167861b",
    "paymentSystem": "UPI",
    "recipient": "John Doe, +11111111111"
}

Using a card

Initiates withdrawal of fiat funds using a card (v1)

POST https://api.xgateway.tech/api/v1/withdrawal

Headers

Name
Type
Description

x-api-key*

String

Your API key

Request Body

Name
Type
Description

customerId*

String

The unique customer ID who initiated the withdrawal

amount*

String

The amount to withdraw

currency*

String

orderId

String

The unique order ID in your system

applicationId

String

The application ID if you have multiple

comment

String

The comment (max 255 symbols)

paymentSystem

String

The payment system to process withdrawal with

cardHolderName

String

The name on the card to withdraw to

cardNumber*

String

The card number to withdraw to

Initiates withdrawal of fiat funds using a card (v2)

POST https://api.xgateway.tech/api/v2/withdrawal

Headers

Name
Type
Description

x-api-key*

String

Your API key

Request Body

Name
Type
Description

customerId*

String

The unique customer ID who initiated the withdrawal

amount*

String

The amount to withdraw

currency*

String

orderId

String

The unique order ID in your system

applicationId

String

The application ID if you have multiple

comment

String

The comment (max 255 symbols)

paymentSystem

String

The payment system to process withdrawal with

cardHolderName

String

The name on the card to withdraw to

cardNumber*

String

The card number to withdraw to

Example of the request body
{
    "amount": "1000",
    "applicationId": "test_application_id",
    "cardHolderName": "John Doe",
    "cardNumber": "4242424242424242",
    "comment": "fiat withdrawal using a card",
    "currency": "INR",
    "customerId": "21c5e78e-95b9-11ed-a1eb-0242ac120002",
    "orderId": "ef3e9b1e-712a-4122-848f-4838a167861b",
    "paymentSystem": "UPI"
}

Using a phone number

Initiates withdrawal of fiat funds using a phone number (v1)

POST https://api.xgateway.tech/api/v1/withdrawal

Headers

Name
Type
Description

x-api-key*

String

Your API key

Request Body

Name
Type
Description

customerId*

String

The unique customer ID who initiated the withdrawal

amount*

String

The amount to withdraw

currency*

String

orderId

String

The unique order ID in your system

applicationId

String

The application ID if you have multiple

comment

String

The comment (max 255 symbols)

paymentSystem

String

The payment system to process withdrawal with

phoneNumber*

String

The recipient phone number

bankName

String

The bank name, where there's an account with the provided phone number

Initiates withdrawal of fiat funds using a phone number (v2)

POST https://api.xgateway.tech/api/v2/withdrawal

Headers

Name
Type
Description

x-api-key*

String

Your API key

Request Body

Name
Type
Description

customerId*

String

The unique customer ID who initiated the withdrawal

amount*

String

The amount to withdraw

currency*

String

orderId

String

The unique order ID in your system

applicationId

String

The application ID if you have multiple

comment

String

The comment (max 255 symbols)

paymentSystem

String

The payment system to process withdrawal with

phoneNumber*

String

The recipient phone number

bankName

String

The bank name, where there's an account with the provided phone number

Example of the request body
{
    "amount": "1000",
    "applicationId": "test_application_id",
    "bankName": "Bank Inc.",
    "comment": "fiat withdrawal using a phone number",
    "currency": "INR",
    "customerId": "21c5e78e-95b9-11ed-a1eb-0242ac120002",
    "orderId": "ef3e9b1e-712a-4122-848f-4838a167861b",
    "paymentSystem": "UPI",
    "phoneNumber": "+11111111111"
}

Using a bank account

Initiates withdrawal of fiat funds using a bank account (v1)

POST https://api.xgateway.tech/api/v1/withdrawal

Headers

Name
Type
Description

x-api-key*

String

Your API key

Request Body

Name
Type
Description

customerId*

String

The unique customer ID who initiated the withdrawal

amount*

String

The amount to withdraw

currency*

String

orderId

String

The unique order ID in your system

applicationId

String

The application ID if you have multiple

comment

String

The comment (max 255 symbols)

paymentSystem

String

The payment system to process withdrawal with

bankName

String

The bank name

bankAccountName*

String

The bank account name

bankAccountNumber*

String

The bank account number

Initiates withdrawal of fiat funds using a bank account (v2)

POST https://api.xgateway.tech/api/v2/withdrawal

Headers

Name
Type
Description

x-api-key*

String

Your API key

Request Body

Name
Type
Description

customerId*

String

The unique customer ID who initiated the withdrawal

amount*

String

The amount to withdraw

currency*

String

orderId

String

The unique order ID in your system

applicationId

String

The application ID if you have multiple

comment

String

The comment (max 255 symbols)

paymentSystem

String

The payment system to process withdrawal with

bankName

String

The bank name

bankAccountName*

String

The bank account name

bankAccountNumber*

String

The bank account number

Example of the request body
{
    "amount": "1000",
    "applicationId": "test_application_id",
    "bankAccountName": "John Doe",
    "bankAccountNumber": "AA0000000000000000000000000",
    "bankName": "Bank Inc.",
    "comment": "fiat withdrawal using a phone number",
    "currency": "INR",
    "customerId": "21c5e78e-95b9-11ed-a1eb-0242ac120002",
    "orderId": "ef3e9b1e-712a-4122-848f-4838a167861b",
    "paymentSystem": "UPI"
}

If applicationId and orderId are passed when creating an invoice, the callback will contain them after the transaction is processed.

Results

When the transactions have been initiated you'll receive the response.

{
    "data": "The transaction has been initiated. You will be notified once its status has changed.",
    "success": true
}

Keep in mind that the transaction is initially pending. You will receive a callback once it has been confirmed.

We assume that the customer has already been authorized on your side to withdraw the given amount of funds. The funds are withdrawn from your main wallet. This means that the customer can withdraw more than they have deposited.

You can always top up your main wallet to ensure it holds enough funds for customer withdrawals.

The to withdraw in

The to withdraw in

The to withdraw in

The to withdraw in

The to withdraw in

The to withdraw in

The to withdraw in

The to withdraw in

⚙️
currency
currency
currency
currency
currency
currency
currency
currency

Creates a withdrawal request (V2).

Creates a withdrawal request to an external resource.

Access to this endpoint requires a valid API key. The API key is sent in the x-api-key header on requests.

POSThttps://api.xgateway.tech/api/v2/withdrawal
Authorization
Body
  • The input that contains the request data.

Crypto:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal.
  • address - The recipient address.
  • amount - The amount to be withdrawn.

Peer-to-peer:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal.
  • recipient - The recipient, if the free form is selected.
  • amount - The amount to be withdrawn.
  • bankAccountName - The bank account name, if the bank account transfer is selected.
  • bankAccountNumber - The bank account number, if the bank account transfer is selected.
  • bankName - The bank name, if the bank account or phone number transfer is selected.
  • cardHolderName - The cardholder's name, if the card transfer is selected.
  • cardNumber - The card number, if the card transfer is selected.
  • phoneNumber - The phone number, if the phone number transfer is selected.
  • comment - The additional comment.

Bank transfer:

  • Unsupported.

Peer-to-peer2:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal (INR).
  • amount - The amount to be withdrawn.
  • beneficiaryAccountNumber - The bank account number of the beneficiary.
  • beneficiaryIfsc - The IFSC code of the beneficiary's bank branch.
  • beneficiaryMobileNumber - The mobile number of the beneficiary, required for mobile-based transactions.
  • beneficiaryName - The full name of the beneficiary as registered in their bank.
  • beneficiaryVpa - Optional Virtual Payment Address (VPA) for UPI transactions.
  • purpose - Description of the purpose of the transaction.
  • transferMode - Specifies the mode of transfer such as IMPS, RTGS, or UPI.
  • comment - Only applicable for RTGS transactions. Special characters are not allowed.
any of
  • The input that contains the request data.

Crypto:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal.
  • address - The recipient address.
  • amount - The amount to be withdrawn.

Peer-to-peer:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal.
  • recipient - The recipient, if the free form is selected.
  • amount - The amount to be withdrawn.
  • bankAccountName - The bank account name, if the bank account transfer is selected.
  • bankAccountNumber - The bank account number, if the bank account transfer is selected.
  • bankName - The bank name, if the bank account or phone number transfer is selected.
  • cardHolderName - The cardholder's name, if the card transfer is selected.
  • cardNumber - The card number, if the card transfer is selected.
  • phoneNumber - The phone number, if the phone number transfer is selected.
  • comment - The additional comment.

Bank transfer:

  • Unsupported.

Peer-to-peer2:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal (INR).
  • amount - The amount to be withdrawn.
  • beneficiaryAccountNumber - The bank account number of the beneficiary.
  • beneficiaryIfsc - The IFSC code of the beneficiary's bank branch.
  • beneficiaryMobileNumber - The mobile number of the beneficiary, required for mobile-based transactions.
  • beneficiaryName - The full name of the beneficiary as registered in their bank.
  • beneficiaryVpa - Optional Virtual Payment Address (VPA) for UPI transactions.
  • purpose - Description of the purpose of the transaction.
  • transferMode - Specifies the mode of transfer such as IMPS, RTGS, or UPI.
  • comment - Only applicable for RTGS transactions. Special characters are not allowed.
Response

Created

Body
success*boolean
data*string
Request
const response = await fetch('https://api.xgateway.tech/api/v2/withdrawal', {
    method: 'POST',
    headers: {
      "x-api-key": "api_key <apiKey>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "customerId": "text",
      "currency": "BNB",
      "amount": "text",
      "address": "text"
    }),
});
const data = await response.json();
Response
{
  "data": "The transaction has been initiated. You will be notified once its status has changed.",
  "success": true
}

Creates a withdrawal request (V1).

Creates a withdrawal request to an external resource.

Access to this endpoint requires a valid API key. The API key is sent in the x-api-key header on requests.

POSThttps://api.xgateway.tech/api/v1/withdrawal
Authorization
Body
  • The input that contains the request data.

Crypto:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal.
  • address - The recipient address.
  • amount - The amount to be withdrawn.

Peer-to-peer:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal.
  • recipient - The recipient, if the free form is selected.
  • amount - The amount to be withdrawn.
  • bankAccountName - The bank account name, if the bank account transfer is selected.
  • bankAccountNumber - The bank account number, if the bank account transfer is selected.
  • bankName - The bank name, if the bank account or phone number transfer is selected.
  • cardHolderName - The card holder name, if the card transfer is selected.
  • cardNumber - The card number, if the card transfer is selected.
  • phoneNumber - The phone number, if the phone number transfer is selected.
  • comment - The additional comment.

Bank transfer:

  • Unsupported.

Peer-to-peer2:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal (INR).
  • amount - The amount to be withdrawn.
  • beneficiaryAccountNumber - The bank account number of the beneficiary.
  • beneficiaryIfsc - The IFSC code of the beneficiary's bank branch.
  • beneficiaryMobileNumber - The mobile number of the beneficiary, required for mobile-based transactions.
  • beneficiaryName - The full name of the beneficiary as registered in their bank.
  • beneficiaryVpa - Optional Virtual Payment Address (VPA) for UPI transactions.
  • purpose - Description of the purpose of the transaction.
  • transferMode - Specifies the mode of transfer such as IMPS, RTGS, or UPI.
  • comment - Only applicable for RTGS transactions. Special characters are not allowed.
any of
  • The input that contains the request data.

Crypto:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal.
  • address - The recipient address.
  • amount - The amount to be withdrawn.

Peer-to-peer:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal.
  • recipient - The recipient, if the free form is selected.
  • amount - The amount to be withdrawn.
  • bankAccountName - The bank account name, if the bank account transfer is selected.
  • bankAccountNumber - The bank account number, if the bank account transfer is selected.
  • bankName - The bank name, if the bank account or phone number transfer is selected.
  • cardHolderName - The card holder name, if the card transfer is selected.
  • cardNumber - The card number, if the card transfer is selected.
  • phoneNumber - The phone number, if the phone number transfer is selected.
  • comment - The additional comment.

Bank transfer:

  • Unsupported.

Peer-to-peer2:

  • applicationId - The associated application ID in the external system.
  • orderId - The associated order ID in the external system.
  • customerId - The customer ID in the external system.
  • currency - The currency of a withdrawal (INR).
  • amount - The amount to be withdrawn.
  • beneficiaryAccountNumber - The bank account number of the beneficiary.
  • beneficiaryIfsc - The IFSC code of the beneficiary's bank branch.
  • beneficiaryMobileNumber - The mobile number of the beneficiary, required for mobile-based transactions.
  • beneficiaryName - The full name of the beneficiary as registered in their bank.
  • beneficiaryVpa - Optional Virtual Payment Address (VPA) for UPI transactions.
  • purpose - Description of the purpose of the transaction.
  • transferMode - Specifies the mode of transfer such as IMPS, RTGS, or UPI.
  • comment - Only applicable for RTGS transactions. Special characters are not allowed.
Response

Created

Body
success*boolean
data*string
Request
const response = await fetch('https://api.xgateway.tech/api/v1/withdrawal', {
    method: 'POST',
    headers: {
      "x-api-key": "api_key <apiKey>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "customerId": "text",
      "currency": "BTC",
      "amount": "text",
      "address": "text"
    }),
});
const data = await response.json();
Response
{
  "data": "The transaction has been initiated. You will be notified once its status has changed.",
  "success": true
}
  • Crypto
  • POSTCreates a withdrawal request (V1).
  • POSTCreates a withdrawal request (V2).
  • Fiat
  • Initiates withdrawal of fiat funds using a free-form (v1)
  • Initiates withdrawal of fiat funds using a free-form (v2)
  • Initiates withdrawal of fiat funds using a card (v1)
  • Initiates withdrawal of fiat funds using a card (v2)
  • Initiates withdrawal of fiat funds using a phone number (v1)
  • Initiates withdrawal of fiat funds using a phone number (v2)
  • Initiates withdrawal of fiat funds using a bank account (v1)
  • Initiates withdrawal of fiat funds using a bank account (v2)
  • Results