Creating a Payout — how to send funds via API

Main

Payouts

Creating a payout

post

https://api.heleket.com/v1/payout

Copy

The payouts through API are made only from your business wallets balances.

Payouts can be made in different ways:

You can choose to receive the payout in a specific cryptocurrency and the payout will then be automatically processed in that specific cryptocurrency. To do so, ensure that you have sufficient balance in that particular currency to cover all associated fees.
Alternatively, you have the option to specify the payout amount in a fiat currency. In this case, the amount will be automatically converted to a specific cryptocurrency from your available balance. For instance, if you request a payout of 20 USD in LTC, the equivalent value will be deducted from your LTC balance. It is important to have enough funds in the corresponding cryptocurrency to cover all applicable fees.
Another possibility is to specify the payout amount in a fiat currency, which will be automatically converted to a specific cryptocurrency using your USDT balance. This option is particularly useful when you have autoconvert enabled, as funds from your invoices are automatically converted to USDT. For example, if you want to make a payout of 20 USD in LTC but only have a balance in USDT, make sure you have sufficient USDT funds to cover all fees.
Additionally, you can choose to specify the payout amount in any cryptocurrency of your preference. The payout will then be automatically processed in that specific cryptocurrency, utilizing your available USDT balance. It is crucial to have enough USDT balance to cover all associated fees.

Request

Query parameters

Name	Parameter type	Default value	Definition
amount*	string		Payout amount
currency*	string		Currency code for the payoutIf Currency if fiat, the to_currency parameter is required.
order_id*	stringmin:1max:100alpha_dash		Order ID in your systemThe parameter should be a string consisting of alphabetic characters, numbers, underscores, and dashes. It should not contain any spaces or special characters.The order_id must be unique within the merchant payoutsWhen we find an existing payout with order_id, we return its details, a new payout will not be created.
address*	string		The address of the wallet to which the withdrawal will be made
is_subtract*	boolean		Defines where the withdrawal fee will be deductedtrue - from your balancefalse - from payout amount, the payout amount will be decreased
network*	string		Blockchain network codeNot required when the currency/to_currency is a cryptocurrency and has only one network, for example BTC
url_callback			URL to which webhooks with payout status will be sent
to_currency			Cryptocurrency code in which the payout will be made. It is used when the currency parameter is fiat. See examples below
course_source	stringAvailable values• Binance• BinanceP2p• Exmo• Kucoin	Value from merchant's settings	The service from which the exchange rates are taken for conversion in the invoice.The parameter is applied only if the currency is fiat, otherwise the default value is taken from the merchant's settings.
from_currency	string	null	Allows to automatically convert the withdrawal amount and use the from_currency balance. Only USDT is available.
priority	stringmin: 4max: 11Available values• recommended• economy• high• highest	recommended	The parameter for selecting the withdrawal priority. The cost of the withdrawal fee depends on the selected parameter.This parameter is applied only in case of using the BTC, ETH, POLYGON, and BSC networks.
memo	stringmin: 1max: 30		Additional identifier for TON, used to specify a particular recipient or target

Parameter type string Definition Payout amount
Parameter type string Definition Currency code for the payoutIf Currency if fiat, the to_currency parameter is required.
Parameter type stringmin:1max:100alpha_dash Definition Order ID in your systemThe parameter should be a string consisting of alphabetic characters, numbers, underscores, and dashes. It should not contain any spaces or special characters.The order_id must be unique within the merchant payoutsWhen we find an existing payout with order_id, we return its details, a new payout will not be created.
Parameter type string Definition The address of the wallet to which the withdrawal will be made
Parameter type boolean Definition Defines where the withdrawal fee will be deductedtrue - from your balancefalse - from payout amount, the payout amount will be decreased
Parameter type string Definition Blockchain network codeNot required when the currency/to_currency is a cryptocurrency and has only one network, for example BTC
Definition URL to which webhooks with payout status will be sent
Definition Cryptocurrency code in which the payout will be made. It is used when the currency parameter is fiat. See examples below
Parameter type string Available values- Binance- BinanceP2p- Exmo- Kucoin Definition The service from which the exchange rates are taken for conversion in the invoice.The parameter is applied only if the currency is fiat, otherwise the default value is taken from the merchant's settings.
Parameter type string Definition Allows to automatically convert the withdrawal amount and use the from_currency balance. Only USDT is available.
Parameter type stringmin: 4max: 11 Available values- recommended- economy- high- highest Definition The parameter for selecting the withdrawal priority. The cost of the withdrawal fee depends on the selected parameter.This parameter is applied only in case of using the BTC, ETH, POLYGON, and BSC networks.
Parameter type stringmin: 1max: 30 Definition Additional identifier for TON, used to specify a particular recipient or target

* - mandatory parameter

Request example


curl https://api.heleket.com/v1/payout \
-X POST \
-H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
-H 'sign: fe99035f86fa436181717b302b95bacff1' \
-H 'Content-Type: application/json' \
-d '{
    "amount": "5",
    "currency": "USDT",
    "network": "TRON",
    "order_id": "1",
    "address": "TDD97yguPESTpcrJMqU6h2ozZbibv4Vaqm",
    "url_callback": "https://your.site/callback",
    "is_subtract": "1",
}'

Copy

Response

Response parameters

Name	Definition
uuid	uuid of the payout
amount	Payout amount in currency
currency	Currency code for the payout
network	The code of the blockchain network in which the payment is made
address	The address of the wallet to which the payment is made
txid	Transaction ID in the blockchain
status	Payout status See all available statuses
is_final	Whether the payout is finalizedThe payout process is considered finalized once it has been successfully paid or if it has failed. In the event of a payout failure, the funds will be returned to your balance, requiring you to initiate the payout process again.
balance	The remaining funds on the merchant's balance.
payer_currency	Cryptocurrency code in which the payout will be actually made. The payout address will receive the payout currency.
payer_amount	Amount in payer_currency of the payout
commission	Service commission
merchant_amount	The amount debited from the balance, taking into account all fees
convert	Conversion information. The conversion is from from_currency to to_currency.The convert field will not exist if you do not pass from_currency or it is the same as to_currency Structure

Definition uuid of the payout
Definition Payout amount in currency
Definition Currency code for the payout
Definition The code of the blockchain network in which the payment is made
Definition The address of the wallet to which the payment is made
Definition Transaction ID in the blockchain
Definition Payout status See all available statuses
Definition Whether the payout is finalizedThe payout process is considered finalized once it has been successfully paid or if it has failed. In the event of a payout failure, the funds will be returned to your balance, requiring you to initiate the payout process again.
Definition The remaining funds on the merchant's balance.
Definition Cryptocurrency code in which the payout will be actually made. The payout address will receive the payout currency.
Definition Amount in payer_currency of the payout
Definition Service commission
Definition The amount debited from the balance, taking into account all fees
Definition Conversion information. The conversion is from from_currency to to_currency.The convert field will not exist if you do not pass from_currency or it is the same as to_currency Structure

Structure of convert

Name	Definition
to_currency	The code of the currency into which the payment will be swapped
from_currency	The currency from which the payment is swapped
commission	Conversion fee
rate	Conversion rate
from_amount	The amount swapped to from_currency that was debited from the balance, minus all fees.

Definition The code of the currency into which the payment will be swapped
Definition The currency from which the payment is swapped
Definition Conversion fee
Definition Conversion rate
Definition The amount swapped to from_currency that was debited from the balance, minus all fees.

Response example


1{
2    "state": 0,
3    "result": {
4        "uuid": "a7c0caec-a594-4aaa-b1c4-77d511857594",
5        "amount": "3",
6        "currency": "USDT",
7        "commission": "0.001",
8        "merchant_amount": "3.001"
9        "network": "TRON",
10        "address": "TJ...",
11        "txid": null,
12        "status": "process",
13        "is_final": false,
14        "balance": 129,
15        "payer_currency": "USD",
16        "payer_amount": 3
17    }
18}
19

Copy

Possible errors

Validation errors

code : 422

example responses:


1{
2	"state": 1,
3	"errors": {
4		"amount": ["validation.required"]
5	}
6}

Copy

If the payout is blocked on your merchant or user, you will receive this error message. This happens, for example, when you change your password and payouts are blocked for 24 hours.


1{
2    "state": 1,
3    "message": "You are forbidden"
4}

Copy

If we don’t support the currency code you provided in currency parameter, you will receive this error message:


1{
2    "state": 1,
3    "message": "The currency was not found"
4}

Copy

If we can not find the service for executing payout, you will receive this error message. You have to make sure that the cryptocurrency is supported. Check the correctness of the entered values in. currency, network, from_currency, to_currency:


1{
2    "state": 1,
3    "message": "The service was not found"
4}

Copy

If the withdrawal amount is too small, you will receive this error message:


1{
2    "state": 1,
3    "message": "The withdrawal amount is too small"
4}

Copy

If you will not have an active merchant wallet with a cryptocurrency of the payout, you will receive this error:


1{
2    "state": 1,
3    "message": "Wallet not found"
4}

Copy

If the payout amount, including all commissions, is more than your balance, you will receive this error message:


1{
2    "state": 1,
3    "message": "Not enough funds"
4}

Copy

If we don’t find the payout service of the currency that was passed in to_currency parameter, you will receive this error message:


1{
2    "state": 1,
3    "message": "Not found service to_currency"
4}

Copy

If accidentally something happens when swapping to to_currency, you will receive this error message:


1{
2    "state": 1,
3    "message": "Error convert to_currency"
4}

Copy

If the payout amount is less than the minimum supported amount for cryptocurrency, you will receive this error message:


1{
2    "state": 1,
3    "message": "Minimum amount 0.5 USDT"
4}

Copy

If the payout amount is greater than the maximum supported amount for cryptocurrency, you will receive this error message:


1{
2    "state": 1,
3    "message": "Maximum amount 10000000 USDT"
4}

Copy

If you don’t have enough funds to make a payout, you will receive this error message:


1{
2    "state": 1,
3    "message": "Not enough funds"
4}

Copy

If you don't have enough funds to swap the payout amount from from_currency, you will receive this error message:


1{
2    "state": 1,
3    "message": "Not enough balance for convert USDT to LTC"
4}

Copy

If technical work occurs and the payout is temporarily unavailable, you will receive this error message


1{
2    "state": 1,
3    "message": "The terminal was not found"
4}

Copy

Internal server error

code : 500

example responses:


1{
2	"message": "Server error, #1",
3	"code": 500,
4	"error": null
5}

Copy