Creating a payout

post

https://api.cryptomus.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• Garantexio	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- Garantexio

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

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

Response example


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

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 converting 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 convert 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