Finrax API
HomeChangelogIntegration GuideResources
HomeChangelogIntegration GuideResources
  1. Payments and Withdrawals
  • Getting Started
    • Introduction
    • Environments
    • Errors
    • Authorization
      • API Key Management
      • Signature
      • Code Snippets
  • Payments and Withdrawals
    • Crypto Payments
      • Fetch payment by ID
      • 🔒Fetch payments
      • Submit crypto payment
      • Request crypto payment
    • Fetch withdrawals
      GET
    • Fetch withdrawal metadata
      GET
    • Request crypto withdrawal
      POST
    • Fetch whitelisted addresses
      GET
    • Whitelist an address
      POST
    • Fetch crypto withdrawal approval by ID
      GET
    • Fetch business by ID
      GET
    • Fetch business balance
      GET
    • Unwhitelist an address
      DELETE
  • Callbacks
    • Deposit received notification
    • Withdrawal broadcast notification
    • Withdrawal approved/rejected notification
  • Address validation
    • Validate address
      GET
    • Validate address and destination tag
      GET
  • Rates and metadata
    • Fetch market rates
      GET
    • Fetch fiat rates
      GET
    • Fetch deposit rates
      GET
    • Fetch all currencies
      GET
  1. Payments and Withdrawals

Request crypto withdrawal

POST
/api/v1/withdrawals
An endpoint for initiating cryptocurrency withdrawals. The amount can be selected either in fiat or crypto which is defined by the targetAmountPolicy.
When FIAT is selected as policy the resulting amount of the withdrawal in crypto will be calculated according to the fiat amount passed in targetAmount field. When CRYPTO is selected as policy the resulting amount of the withdrawal will be exactly the same as the amount passed in targetAmount field (subject to a negligible difference due to market conditions i.e. market step size)

Request

Authorization
Add parameter in header
FRX-API
Example:
FRX-API: ********************
Body Params application/json
businessId
string <uuid>
required
ID of the business from which the withdrawal should be executed.
clientWithdrawalId
string 
required
Withdrawal identifier provided by the merchant.
recipientAddress
string 
required
Wallet address of the recipient.
destinationTag
string 
optional
XLM/XRP destination tag.
network
enum<string> 
optional
Specifies the network that should be used in this withdrawal.
For ERC20 Tokens you can choose between ETH, TRX and BSC as values for the network field.
ETH stands for Ethereum network. This will be set as the default value when none is provided.
TRX stands for TRON network. Before executing any withdrawals through this network, please make sure your address supports it.
BSC stands for Binance Smart Chain. Before executing any withdrawals through this network, please make sure your address supports it.
These are the following networks supported for each currency.
CurrencyNetwork
BTCBTC
BCHBCH
ETHETH, BSC
LINKETH
LTCLTC
SOLSOL
USDCETH, BSC, SOL
USDTETH, BSC, SOL, TRX
XLMXLM
XRPXRP
Allowed values:
BCHBTCLTCXLMXRPETHBSCSOLTRX
withdrawCurrency
enum<string> 
required
Cryptocurrency that will be withdrawn.
Allowed values:
BCHBNBBTCETHLINKLTCSOLTRXUSDCUSDTXLMXRP
displayCurrency
enum<string> 
required
Fiat currency.
Allowed values:
AEDARSAUDBDTBGNBRLCADCHFCLPCNYCZKDKKEURGBPHKDHRKHUFIDRILSINRISKJPYKESKRWMXNMYRNGNNOKNZDPENPHPPLNQARRONRUBSEKSGDTHBTRYUSDVNDZAR
targetAmountPolicy
enum<string> 
required
Specifies if the targetAmount will be requested in fiat or crypto.
Allowed values:
CRYPTOFIAT
targetAmount
string 
required
The requested amount to be withdrawn in fiat or crypto, depending on the provided targetAmountPolicy.
withdrawalAccount
enum<string> 
optional
Specifies which balance account should be charged for the withdrawal.
Allowed values:
CRYPTOFIAT
Default:
the organisation's default setting
blockchainFeePaidBy
enum<string> 
optional
Specifies who pays the blockchain fee for the withdrawal.
Allowed values:
USERMERCHANT
Default:
the business' default setting
Example
{
    "businessId": "407710f4-de33-454b-a47f-dda792e272c8",
    "clientWithdrawalId": "test-withdrawal-23-12-19-2",
    "recipientAddress": "0x5CF631Db2eB6be3eecB5E9fD0f31a19AC0F4C504",
    "network": "BSC",
    "withdrawCurrency": "USDC",
    "displayCurrency": "EUR",
    "targetAmount": "21",
    "targetAmountPolicy": "FIAT",
    "withdrawalAccount": "FIAT"
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://payments.finrax.com/api/v1/withdrawals' \
--header 'Content-Type: application/json' \
--header 'FRX-API;' \
--data-raw '{
    "businessId": "407710f4-de33-454b-a47f-dda792e272c8",
    "clientWithdrawalId": "test-withdrawal-23-12-19-2",
    "recipientAddress": "0x5CF631Db2eB6be3eecB5E9fD0f31a19AC0F4C504",
    "network": "BSC",
    "withdrawCurrency": "USDC",
    "displayCurrency": "EUR",
    "targetAmount": "21",
    "targetAmountPolicy": "FIAT",
    "withdrawalAccount": "FIAT"
}'

Responses

🟢201Withdrawal request created successfully.
application/json
Body
withdrawId
string <uuid>
required
clientWithdrawId
string 
required
Withdrawal identifier provided by the merchant.
recipientAddress
string 
required
Wallet address of the recipient.
recipientTag
string 
optional
XLM/XRP destination tag.
network
enum<string> 
required
Network on which this withdrawal was initiated.
Allowed values:
BCHBTCLTCXLMXRPETHBSCSOLTRX
initiatedBy
string 
required
Initiator of the withdrawal request. When initiated from the Dashboard, the dashboard user's email is stored. When initiated from API, the backend URL is stored.
status
enum<string> 
required
Allowed values:
PENDINGCOMPLETEDFAILEDBLOCKED
displayCurrency
enum<string> 
required
Fiat currency.
Allowed values:
AEDARSAUDBDTBGNBRLCADCHFCLPCNYCZKDKKEURGBPHKDHRKHUFIDRILSINRISKJPYKESKRWMXNMYRNGNNOKNZDPENPHPPLNQARRONRUBSEKSGDTHBTRYUSDVNDZAR
estimatedDisplayAmount
string 
required
Amount in displayCurrency requested for this withdrawal.
displayServiceFee
string 
optional
Amount debited for fees from the merchant's balance in displayCurrency.
withdrawCurrency
enum<string> 
required
Cryptocurrency to be withdrawn.
Allowed values:
BCHBNBBTCETHLINKLTCSOLTRXUSDCUSDTXLMXRP
estimatedWithdrawAmount
string 
required
Estimated amount for this withdrawal. Can be different than actualWithdrawAmount.
settlementCurrency
enum<string> 
required
Currency in which the merchant's account was debited. Can be either fiat or cryptocurrency.
Allowed values:
BTCUSDCUSDTEURGBPUSD
settlementDeductedAmount
string 
required
Amount debited from the merchant's balance in settlementCurrency.
settlementServiceFee
string 
required
Amount debited for fees from the merchant's balance in settlementCurrency.
uniformCurrency
string 
required
Always EUR.
uniformAmount
string 
required
Amount in uniformCurrency requested for this withdrawal.
uniformServiceFee
string 
optional
Amount debited for fees from the merchant's balance in uniformCurrency.
createdAt
integer <int64>
required
UNIX seconds at which the withdrawal was requested.
Examples
{
    "withdrawId": "5724d752-6084-3822-9590-a6ccdf91f603",
    "clientWithdrawId": "test-withdrawal-23-12-19-2",
    "recipientAddress": "0x5CF631Db2eB6be3eecB5E9fD0f31a19AC0F4C504",
    "network": "BSC",
    "initiatedBy": "john.doe@gmail.com",
    "status": "PENDING",
    "displayCurrency": "EUR",
    "estimatedDisplayAmount": "21",
    "displayServiceFee": "0.25",
    "withdrawCurrency": "USDC",
    "estimatedWithdrawAmount": "23.01742298",
    "settlementCurrency": "EUR",
    "settlementDeductedAmount": "21.25",
    "settlementServiceFee": "0.25",
    "uniformCurrency": "EUR",
    "uniformAmount": "21",
    "uniformServiceFee": "0.25",
    "createdAt": 1702999367
}
🟢202Withdrawal requested and pending approval.
Modified at 2024-07-24 14:04:47
Previous
Fetch withdrawal metadata
Next
Fetch whitelisted addresses
Built with