Withdrawal initiation with API
The guide how to initiate a withdrawal
Our service supports multiple withdrawal methods 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 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 the examples and limitations.
Withdrawals are initiated via an API request to the endpoint. Examples of requests are described below. See the general endpoint specification at the bottom of this page.
INR Peer to Peer Withdrawals
To initiate a withdrawal in INR currency, please provide the following parameters in the withdrawal request:
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.
{
"amount": "1000",
"currency": "INR",
"customerId": "test_customer_id",
"orderId": "test_order_id",
"beneficiaryMobileNumber": "+11111111111",
"beneficiaryName": "John Doe",
"beneficiaryAccountNumber": "123456789",
"beneficiaryIfsc": "ASDF0000161",
"purpose": "VendorPayouts",
"transferMode": "IMPS"
}
TRY Papara withdrawals
To initiate a withdrawal in TRY currency from your Papara account, please provide the following parameters in the withdrawal request
amount
true
String representation of requested amount. Should be multiple of 50.
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 TRY in this case.
beneficiaryAccountNumber
true
Customer's Papara account number.
beneficiaryName
true
Customer’s first name and last name in string format
beneficiaryEmail
false
Customer's email address.
paymentMethod
true
Payment method name. Should be "papara" in this case.
{
"beneficiaryAccountNumber": "2004169722",
"beneficiaryEmail": "[email protected]",
"beneficiaryName":"John Doe",
"currency": "TRY",
"amount": "50",
"customerId": "test_customer_id",
"paymentMethod": "papara"
}
TRY deposit and withdrawal amounts should be multiples of 50.
TRY Bankpay/Havale withdrawals
To initiate a withdrawal in TRY currency from your Bankpay account, please provide the following parameters in the withdrawal request
amount
true
String representation of requested amount. Should be multiple of 50.
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 TRY in this case.
beneficiaryAccountNumber
true
Customer's IBAN.
beneficiaryName
true
Customer’s first name and last name in string format
beneficiaryEmail
false
Customer's email address.
paymentMethod
true
Payment method name. Should be "bankpay" in this case.
{
"beneficiaryAccountNumber": "TR330006100519786457841326",
"beneficiaryEmail": "[email protected]",
"beneficiaryName":"John Doe",
"currency": "TRY",
"amount": "50",
"customerId": "test_customer_id",
"paymentMethod": "bankpay"
}
TRY deposit and withdrawal amounts should be multiples of 50.
Crypto withdrawals
To initiate a withdrawal in any Crypto currency, please provide the following parameters in the withdrawal request
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
{
"address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
"currency": "ETH",
"amount": "0.1",
"customerId": "test_customer_id"
}
General API specification
Creates a withdrawal request.
Access to this endpoint requires a valid API key. The API key is sent in the x-api-key
header
on requests.
- The input that contains the request data.
Crypto:
- applicationId - The associated application ID.
- orderId - The order ID, that will be used to track the request.
- customerId - The ID of a customer who requests the withdrawal.
- currency - The currency of a withdrawal request.
- address - The recipient address.
- amount - The amount to be withdrawn.
Peer-to-peer:
- applicationId - The associated application ID.
- orderId - The order ID, that will be used to track the request.
- customerId - The ID of a customer who requests the withdrawal.
- currency - The currency of a withdrawal request.
- 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.
- orderId - The order ID, that will be used to track the request.
- customerId - The ID of a customer who requests the withdrawal.
- currency - The currency of a withdrawal request. Should be 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.
Peer-to-peer3:
- applicationId - The associated application ID.
- orderId - The order ID, that will be used to track the request.
- customerId - The ID of a customer who requests the withdrawal.
- currency - The currency of a withdrawal request. Should be TRY.
- amount - The amount to be withdrawn.
- beneficiaryAccountNumber - The bank account number of the beneficiary.
- beneficiaryName - The full name of the beneficiary as registered in their bank.
- beneficiaryEmail - The email of the beneficiary as registered in their bank.
- comment - Only applicable for RTGS transactions. Special characters are not allowed.
POST /api/v2/withdrawal HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 220
{
"address": "0xabc1234567890def",
"amount": "0.5",
"applicationId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
"currency": "BTC",
"customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
"orderId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8"
}
{
"data": "The transaction has been initiated. You will be notified once its status has changed.",
"success": true
}
Last updated