How to initiate a withdrawal

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

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.

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

api_key

Body

application/json

• 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.

CreateWithdrawalInput (any of)

CreateCryptoWithdrawalInput (object)CreateFiatFreeFormWithdrawalInput (object)CreateFiatCardWithdrawalInput (object)CreateFiatPhoneNumberWithdrawalInput (object)CreateFiatBankAccountWithdrawalInput (object)CreateFiatPeerToPeer2WithdrawalInput (object)

Response

201400401402404422500

Created

Body

application/json

success*boolean

data*string

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v1/withdrawal', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "customerId": "text",
      "currency": "BTC",
      "amount": "text",
      "address": "text"
    }),
});
const data = await response.json();

Response

201400401402404422500

{
  "success": true,
  "data": "text"
}

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

api_key

Body

application/json

• 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.

CreateWithdrawalInput (any of)

CreateCryptoWithdrawalInput (object)CreateFiatFreeFormWithdrawalInput (object)CreateFiatCardWithdrawalInput (object)CreateFiatPhoneNumberWithdrawalInput (object)CreateFiatBankAccountWithdrawalInput (object)CreateFiatPeerToPeer2WithdrawalInput (object)

Response

201400401402404422500

Created

Body

application/json

success*boolean

data*string

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v2/withdrawal', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "customerId": "text",
      "currency": "BNB",
      "amount": "text",
      "address": "text"
    }),
});
const data = await response.json();

Response

201400401402404422500

{
  "success": true,
  "data": "text"
}

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	The currency to withdraw in
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	The currency to withdraw in
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, [phone]"
}

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	The currency to withdraw in
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	The currency to withdraw in
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	The currency to withdraw in
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	The currency to withdraw in
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": "[phone]"
}

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	The currency to withdraw in
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	The currency to withdraw in
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.