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.

SEPA Secure Withdrawal

Use the following payload example to initiate a withdrawal.

To be able to initiate a SEPA Secure withdrawal please follow this guide first to complete all preconditions.

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. GBP in the example below

Payoload example

{
  "amount": "1000",
  "currency": "GBP",
  "customerId": "test_customer_id",
  "orderId": "test_order_id"
}

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": "+11111111111",
  "beneficiaryName": "John Doe",
  "beneficiaryAccountNumber": "123456789",
  "beneficiaryIfsc": "ASDF0000161",
  "purpose": "VendorPayouts",
  "transferMode": "IMPS"
}

Minimum amount for INR deposits and withdrawals is 300 INR

TRY Papara withdrawals

To initiate a withdrawal in TRY currency from your Papara account, please provide the following parameters in the withdrawal request

Parameter

Mandatory

Description

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.

Payload example

{
    "beneficiaryAccountNumber": "2004169722",
    "beneficiaryEmail": "[email protected]",
    "beneficiaryName":"John Doe",
    "currency": "TRY",
    "amount": "50",
    "customerId": "test_customer_id",
    "paymentMethod": "papara"
}

Deposit and withdrawal amounts in TRY must be multiples of 50.

TRY Papel withdrawals

To initiate a withdrawal in TRY currency from your Papel account, please provide the following parameters in the withdrawal request

Parameter

Mandatory

Description

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 Papel account number. Should be 10 digit string.

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 "papel" in this case.

Payload example

{
    "beneficiaryAccountNumber": "2004169722",
    "beneficiaryEmail": "[email protected]",
    "beneficiaryName":"John Doe",
    "currency": "TRY",
    "amount": "50",
    "customerId": "test_customer_id",
    "paymentMethod": "papel"
}

Deposit and withdrawal amounts in TRY must be multiples of 50.

TRY Parolapara withdrawals

To initiate a withdrawal in TRY currency from your Parolapara account, please provide the following parameters in the withdrawal request

Parameter

Mandatory

Description

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 Parolapara account number. Should be 10 digit string.

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 "parolapara" in this case.

Payload example

{
    "beneficiaryAccountNumber": "2004169722",
    "beneficiaryEmail": "[email protected]",
    "beneficiaryName":"John Doe",
    "currency": "TRY",
    "amount": "50",
    "customerId": "test_customer_id",
    "paymentMethod": "parolapara"
}

Deposit and withdrawal amounts in TRY must 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

Parameter

Mandatory

Description

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.

Payload example

{
    "beneficiaryAccountNumber": "TR330006100519786457841326",
    "beneficiaryEmail": "[email protected]",
    "beneficiaryName":"John Doe",
    "currency": "TRY",
    "amount": "50",
    "customerId": "test_customer_id",
    "paymentMethod": "bankpay"
}

Deposit and withdrawal amounts in TRY must be multiples of 50.

Crypto withdrawals

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

Withdrawal currency must be specified using the unique currency code from the supported currencies list (see the Currency column there). Cryptocurrencies with the same currency symbol can be deployed on different networks and under different contracts. Use network-specific currency codes, such as pUSDC for a Polygon-based asset, to avoid ambiguity.

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.

General API specification

Creates a withdrawal request (V2).

post

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.

Authorizations

Body

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:

amount - The amount to be withdrawn in cryptocurrency.
applicationId - The associated application ID.
currency - The fiat currency that the customer will receive to their bank account.
customerId - The ID of a customer who requests the withdrawal.
orderId - The order ID, that will be used to track the request.

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.

amountstringRequired

customerIdstringRequired

applicationIdstringOptional

orderIdstringOptional

currencystring · enumRequired

Represents all currencies in the payment processing system.

Used to specify the currency of accounts, exchange rates, and transactions in the payment processing system.

It provides a controlled and standardized list of supported currencies for all transactions and balances in the payment processing system.

New currencies can be added to the payment processing system as additional members.

Supported cryptocurrencies:

BNB - Binance Coin
bUSDT - Tether (pegged to USD), issued on BNB Smart Chain network (BEP20 token)
BTC - Bitcoin
ETH - Ether
eUSDC - USD Coin (pegged to USD), issued on Ethereum network (ERC20 token)
eUSDT - Tether (pegged to USD), issued on Ethereum network (ERC20 token)
FTN - Fasttoken
POL - POL
pUSDC - USD Coin (pegged to USD), issued on Polygon network (ERC20 token)
SOL - SOL
sUSDT - Tether (pegged to USD), issued on Solana network (SPL token)
tUSDC - USD Coin (pegged to USD), issued on Tron network (TRC20 token)
tUSDT - Tether (pegged to USD), issued on Tron network (TRC20 token)
wpUSDC - wrapped USD Coin (pegged to USD), issued on Polygon network (ERC20 token)
wpUSDT - wrapped Tether (pegged to USD), issued on Polygon network (ERC20 token).

Supported fiat currencies:

AZN - Azerbaijani Manat
BDT - Bangladeshi Taka
EUR - Euro
GBP - Pound Sterling
INR - Indian Rupee
JPY - Japanese Yen
KES - Kenyan Shilling
PKR - Pakistani Rupee
RUB - Russian Ruble
TRY - Turkish Lira
USD - United States Dollar
UZS - Uzbekistani Som.

Possible values:

Other propertiesanyOptional

Responses

201

Created

application/json

400

Database violation

application/json

401

Unauthorized

application/json

402

Payment required

application/json

403

Forbidden

application/json

404

Not found

application/json

422

Unprocessable content

application/json

500

Internal server error

application/json

post

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
}

Callback on Withdraw request

The system will send a callback when the request is processed. The callback will have a special type and will be sent to the same URL that is used for deposit callbacks. More information can be found on this page.

PreviousKYC callback NextDisputes resolution

Last updated 12 days ago