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:

  1. 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.
  2. 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.
  3. 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.
  4. 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

NameParameter typeDefault valueDefinition
amount*stringPayout amount
currency*stringCurrency code for the payoutIf Currency if fiat, the to_currency parameter is required.
order_id*stringmin:1max:100alpha_dashOrder 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*stringThe address of the wallet to which the withdrawal will be made
is_subtract*booleanDefines where the withdrawal fee will be deductedtrue - from your balancefalse - from payout amount, the payout amount will be decreased
network*stringBlockchain network codeNot required when the currency/to_currency is a cryptocurrency and has only one network, for example BTC
url_callbackURL to which webhooks with payout status will be sent
to_currencyCryptocurrency code in which the payout will be made. It is used when the currency parameter is fiat. See examples below
course_sourcestringValue from merchant's settingsThe 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_currencystringnullAllows to automatically convert the withdrawal amount and use the from_currency balance. Only USDT is available.
prioritystringmin: 4max: 11recommendedAll 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.
memostringmin: 1max: 30Additional 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

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

Definition

All 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

NameDefinition
uuidUuid of the payout
amountPayout amount in currency
currencyCurrency code for the payout
networkThe code of the blockchain network in which the payment is made
addressThe address of the wallet to which the payment is made
txidTransaction ID in the blockchain
statusPayout status See all available statuses
is_finalWhether 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.
balanceThe remaining funds on the merchant's balance.
payer_currencyCryptocurrency code in which the payout will be actually made. The payout address will receive the payout currency.
payer_amountAmount 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