Withdrawal API(V1)

The guide how to initiate a withdrawal.

Note, the V1 API is deprecated. Use V2 instead.

Our service supports multiple withdrawal methods, each tailored to different payment systems. While the API endpoint remains unified, the required fields vary depending on the withdrawal method chosen. Merchants should select the most suitable option for their specific needs, keeping in mind that certain methods come with limitations based on factors such as currency, provider, or region. If you're unsure which withdrawal type is relevant for your use case, our technical support team is available to assist and guide you to the appropriate option. The sections below outline the necessary parameters for several base types, along with examples and limitations.

Withdrawals are initiated via an HTTP API request to the endpoint. See the endpoint specification below:

Creates a withdrawal request (V1).

post

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.

Authorizations

Body

any ofoptional

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

Responses

application/json

application/json

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.xgateway.tech/api/v1/withdrawal' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentSystem": null,
    "orderId": "text",
    "customerId": "text",
    "currency": "BNB",
    "applicationId": "text",
    "amount": "text",
    "address": "text"
  }'

201

400

401

402

404

422

500

201

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

Created

INR Peer to Peer Withdrawals

To initiate a withdrawal in INR currency, please provide the following parameters in the withdrawal request

Parameter	Mandatory	Description
amount	true	String representation of requested amount
applicationId	false	Application ID in case the application is used
customerId	true	Customer id in the merchant system
orderId	false	Invoice id in the merchant system
currency	true	String representation of the requested currency. Should be INR in this case.
beneficiaryAccountNumber	false	Customer's bank account number.
beneficiaryIfsc	false	String representation of the Indian Financial System Code
beneficiaryMobileNumber	true	Customer’s phone number in string format
beneficiaryName	true	Customer’s first name and last name in string format
beneficiaryVpa	false	String representation of the Virtual Payment Address
purpose	true	One of the following: Cashbacks, LoyaltyPointsRedemption, Refunds, MarketingCampaign, VendorPayouts
transferMode	true	One of the following: IMPS, UPI, RTGS. Please provide "IMPS" at the moment.

Payoload example

{
  "amount": "1000",
  "currency": "INR",
  "customerId": "test_customer_id",
  "orderId": "test_order_id",
  "beneficiaryMobileNumber": "[phone]",
  "beneficiaryName": "John Doe",
  "beneficiaryAccountNumber": "123456789",
  “beneficiaryIfsc”: “ASDF0000161”,
  "purpose": "VendorPayouts",
  "transferMode": "IMPS"
}

Minimum amount for INR deposits and withdrawals is 300 INR

Crypto withdrawals

To initiate a withdrawal in any Crypto currency, please provide the following parameters in the withdrawal request

Parameter	Mandatory	Description
amount	true	String representation of requested amount.
applicationId	false	Application ID in case the application is used
customerId	true	Customer id in the merchant system
orderId	false	Invoice id in the merchant system
currency	true	String representation of the requested currency.
address	true	Customer's crypto address to withdraw

Payload example

{
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
    "currency": "ETH",
    "amount": "0.1",
    "customerId": "test_customer_id"
}

Ensure that no additional parameters, except those specified above, are passed into the withdrawal request.