Creating an invoice

post
https://api.cryptomus.com/v1/payment
COPY

Request

Query parameters

NameParameter typeDefault valueDefinition
amount*stringAmount to be paid.If there are pennies in the amount, then send them with a separator '.'
Example: 10.28
currency*stringCurrency code
order_id*stringmin: 1max: 128alpha_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 invoices/static wallets/recurrence paymentsWhen we find an existing invoice with order_id, we return its details, a new invoice will not be created.
networkstringnullBlockchain network code
url_returnstringmin: 6max: 255urlnullBefore paying, the user can click on the button on the payment form and return to the store page at this URL.
url_successstringmin: 6max: 255urlnullAfter successful payment, the user can click on the button on the payment form and return to this URL.
url_callbackstringmin: 6max: 255urlnullUrl to which webhooks with payment status will be sent
is_payment_multiplebooleantrueWhether the user is allowed to pay the remaining amount. This is useful when the user has not paid the entire amount of the invoice for one transaction, and you want to allow him to pay up to the full amount. If you disable this feature, the invoice will finalize after receiving the first payment and you will receive funds to your balance.
lifetimeintegermin: 300max: 432003600The lifespan of the issued invoice (in seconds)
to_currencystringThe parameter is used to specify the target currency for converting the invoice amount. When creating an invoice, you provide an amount and currency, and the API will convert that amount to the equivalent value in the to_currency.For example, to create an invoice for 20 USD in bitcoin:
amount: 20
currency: USD
to_currency: BTC
The API will convert 20 USD amount to its equivalent in BTC based on the current exchange rate and the user will pay in BTCThe to_currency should always be the cryptocurrency code, not a fiat currency code.
subtractintegermin: 0max: 1000Percentage of the payment commission charged to the clientIf you have a rate of 1%, then if you create an invoice for 100 USDT with subtract = 100 (the client pays 100% commission), the client will have to pay 101 USDT.
accuracy_payment_percentnumericmin: 0max: 50Acceptable inaccuracy in payment.For example, if you pass the value 5, the invoice will be marked as Paid even if the client has paid only 95% of the amount.The actual payment amount will be credited to the balance
additional_datastringmax: 255nullAdditional information for you (not shown to the client)
currenciesarrayThe array of available currencies from your merchant's settings is used (if the parameter is not set, all supported cryptocurrencies are used by default).The available currencies are set in the merchant settings section.List of allowed currencies for payment. This is useful if you want to limit the list of coins that your customers can use to pay invoices. Structure
except_currenciesarraynullList of excluded currencies for payment Structure
course_sourcestringmin: 4max: 20If not passed, Cryptomus exchange rates are used.The service from which the exchange rates are taken for conversion in the invoice.
from_referral_codestringnullThe merchant who makes the request connects to a referrer by code.For example, you are an application that generates invoices via the Cryptomus API and your customers are other stores.
They enter their api key and merchant id in your application, and you send requests with their credentials and passing your referral code.
Thus, your clients become referrals on your Cryptomus account and you will receive income from their turnover.
discount_percentintegermin: -99max: 100nullPositive numbers:
Allows you to set a discount.
To set a 5% discount for the payment, you should pass a value: 5
Negative numbers:
Allows you to set custom additional commission.
To set an additional commission of 10% for the payment, you should pass a value: -10The discount percentage when creating an invoice is taken into account only if the invoice has a specific cryptocurrency.
is_refreshbooleanfalseUsing this parameter, you can update the lifetime and get a new address for the invoice if the lifetime has expired.To do that, you need to pass all required parameters, and the invoice with passed order_id will be refreshed.Only address, payment_status and expired_at are changed. No other fields are changed, regardless of the parameters passed.

Parameter type

string

Definition

Amount to be paid.If there are pennies in the amount, then send them with a separator '.'
Example: 10.28

Parameter type

string

Definition

Currency code

Parameter type

stringmin: 1max: 128alpha_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 invoices/static wallets/recurrence paymentsWhen we find an existing invoice with order_id, we return its details, a new invoice will not be created.

Parameter type

string

Definition

Blockchain network code

Parameter type

stringmin: 6max: 255url

Definition

Before paying, the user can click on the button on the payment form and return to the store page at this URL.

Parameter type

stringmin: 6max: 255url

Definition

After successful payment, the user can click on the button on the payment form and return to this URL.

Parameter type

stringmin: 6max: 255url

Definition

Url to which webhooks with payment status will be sent

Parameter type

boolean

Definition

Whether the user is allowed to pay the remaining amount. This is useful when the user has not paid the entire amount of the invoice for one transaction, and you want to allow him to pay up to the full amount. If you disable this feature, the invoice will finalize after receiving the first payment and you will receive funds to your balance.

Parameter type

integermin: 300max: 43200

Definition

The lifespan of the issued invoice (in seconds)

Parameter type

string

Definition

The parameter is used to specify the target currency for converting the invoice amount. When creating an invoice, you provide an amount and currency, and the API will convert that amount to the equivalent value in the to_currency.For example, to create an invoice for 20 USD in bitcoin:
amount: 20
currency: USD
to_currency: BTC
The API will convert 20 USD amount to its equivalent in BTC based on the current exchange rate and the user will pay in BTCThe to_currency should always be the cryptocurrency code, not a fiat currency code.

Parameter type

integermin: 0max: 100

Definition

Percentage of the payment commission charged to the clientIf you have a rate of 1%, then if you create an invoice for 100 USDT with subtract = 100 (the client pays 100% commission), the client will have to pay 101 USDT.

Parameter type

numericmin: 0max: 5

Definition

Acceptable inaccuracy in payment.For example, if you pass the value 5, the invoice will be marked as Paid even if the client has paid only 95% of the amount.The actual payment amount will be credited to the balance

Parameter type

stringmax: 255

Definition

Additional information for you (not shown to the client)

Parameter type

array

Definition

List of allowed currencies for payment. This is useful if you want to limit the list of coins that your customers can use to pay invoices. Structure

Parameter type

array

Definition

List of excluded currencies for payment Structure

Parameter type

stringmin: 4max: 20

Definition

The service from which the exchange rates are taken for conversion in the invoice.

Parameter type

string

Definition

The merchant who makes the request connects to a referrer by code.For example, you are an application that generates invoices via the Cryptomus API and your customers are other stores.
They enter their api key and merchant id in your application, and you send requests with their credentials and passing your referral code.
Thus, your clients become referrals on your Cryptomus account and you will receive income from their turnover.

Parameter type

integermin: -99max: 100

Definition

Positive numbers:
Allows you to set a discount.
To set a 5% discount for the payment, you should pass a value: 5
Negative numbers:
Allows you to set custom additional commission.
To set an additional commission of 10% for the payment, you should pass a value: -10The discount percentage when creating an invoice is taken into account only if the invoice has a specific cryptocurrency.

Parameter type

boolean

Definition

Using this parameter, you can update the lifetime and get a new address for the invoice if the lifetime has expired.To do that, you need to pass all required parameters, and the invoice with passed order_id will be refreshed.Only address, payment_status and expired_at are changed. No other fields are changed, regardless of the parameters passed.

* - mandatory parameter

Structure of Currencies

NameDefinition
currency*Currency code
networkBlockchain network code

Definition

Currency code

Definition

Blockchain network code

* - mandatory parameter

Structure of except_currencies

NameDefinition
currency*Currency code
networkBlockchain network code

Definition

Currency code

Definition

Blockchain network code

* - mandatory parameter

The invoice will have a specific cryptocurrency and address at the time of creation only if currency or to_currency parameter is a cryptocurrency and the network parameter is passed (or a cryptocurrency has only one network, for example BTC).

Request example

Below is a sample example with the minimum required number of parameters. In this case, an invoice will be created with the fiat currency USD. On the payment page, the user will be able to select the cryptocurrency and network to pay this bill.


curl https://api.cryptomus.com/v1/payment \
-X POST \
-H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
-H 'sign: fe99035f86fa436181717b302b95bacff1' \
-H 'Content-Type: application/json' \
-d '{
	"amount": "15",
	"currency": "USD",
	"order_id": "1",
}'
COPY

Response

Response parameters

NameDefinition
uuidInvoice uuid
order_idOrder ID in your system
amountThe amount of the invoice
payment_amountAmount paid by client
payer_amountThe amount in payer_currency that the customer must pay, including a discount or additional commission.
discount_percentPercentage of discount or additional commission, that was passed in request parameters
discountActual amount of discount or additional commission in cryptocurrency.For example, if invoice amount is 15 USDT and discount_percent is -5, the discount value will be -0.75i.e. amount + discount = payer_amount
payer_currencyThe currency in which the customer must make the payment.
currencyInvoice currency code
merchant_amountAmount in crypto that will be credited to your balance. If invoice payer_currency is not specified, the value will be null.
networkBlockchain network code
addressWallet address for payment
fromThe address of the wallet from which the payment was made
txidTransaction hash
payment_statusPayment status All payment statuses
urlURL payment page
expired_atTimestamp of expiration of the invoice
is_finalWhether the invoice is finalized.When invoice is finalized it is impossible to pay an invoice (it's either paid or expired)
additional_dataAdditional information
created_atCreation date of the invoice. Timezone is UTC+3
updated_atLast invoice updated date. Timezone is UTC+3

Definition

Invoice uuid

Definition

Order ID in your system

Definition

The amount of the invoice

Definition

Amount paid by client

Definition

The amount in payer_currency that the customer must pay, including a discount or additional commission.

Definition

Percentage of discount or additional commission, that was passed in request parameters

Definition

Actual amount of discount or additional commission in cryptocurrency.For example, if invoice amount is 15 USDT and discount_percent is -5, the discount value will be -0.75i.e. amount + discount = payer_amount

Definition

The currency in which the customer must make the payment.

Definition

Invoice currency code

Definition

Amount in crypto that will be credited to your balance. If invoice payer_currency is not specified, the value will be null.

Definition

Blockchain network code

Definition

Wallet address for payment

Definition

The address of the wallet from which the payment was made

Definition

Transaction hash

Definition

Payment status All payment statuses

Definition

URL payment page

Definition

Timestamp of expiration of the invoice

Definition

Whether the invoice is finalized.When invoice is finalized it is impossible to pay an invoice (it's either paid or expired)

Definition

Additional information

Definition

Creation date of the invoice. Timezone is UTC+3

Definition

Last invoice updated date. Timezone is UTC+3

Response example


1{
2	"state": 0,
3	"result": {
4		"uuid": "26109ba0-b05b-4ee0-93d1-fd62c822ce95",
5		"order_id": "1",
6		"amount": "15.00",
7		"payment_amount": null,
8		"payer_amount": null,
9		"discount_percent": null,
10		"discount": "0.00000000",
11		"payer_currency": null,
12		"currency": "USD",
13		"merchant_amount": null,
14		"network": null,
15		"address": null,
16		"from": null,
17		"txid": null,
18		"payment_status": "check",
19		"url": "https://pay.cryptomus.com/pay/26109ba0-b05b-4ee0-93d1-fd62c822ce95",
20		"expired_at": 1689098133,
21		"status": "check",
22		"is_final": false,
23		"additional_data": null,
24		"created_at": "2023-07-11T20:23:52+03:00",
25		"updated_at": "2023-07-11T21:24:17+03:00"
26	}
27}
COPY

More examples

Request data to create an invoice for 20 USDT in tron network. The invoice will have an address at the time of creation.


1{
2	"amount": "20",
3	"currency": "USDT",
4	"order_id": "1",
5	"network": "tron"
6}
COPY

Request data to create an invoice for 25 USD and allow clients to pay only by USDT in any network.


1{
2	"amount": "25",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "USDT"
6}
COPY

Request data to create an invoice for 25 USD and allow clients to pay only by USDT in tron network. The invoice will have an address at the time of creation.


1{
2	"amount": "25",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "USDT",
6	"network": "tron"
7}
COPY

Request data to create an invoice for 20 USDT and allow clients to pay in all available networks


1{
2	"amount": "20",
3	"currency": "USDT",
4	"order_id": "1",
5}
COPY

Request data to create an invoice for 20 USD and allow clients to pay in bitcoin only. The invoice will have an address at the time of creation.


1{
2	"amount": "20",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "BTC"
6}
COPY

Request data to create an invoice for 0.5 BTC and allow clients to pay in bitcoin only. The invoice will have an address at the time of creation.


1{
2	"amount": "0.5",
3	"currency": "BTC",
4	"order_id": "1",
5}
COPY

Possible errors

Validation errors

code : 422

example responses:

If some parameter is required and not passed:


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

If you provided the network code that is not supported


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

If we don’t support the currency code you provided in currency parameter:


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

If your payments are blocked. In this case you need to contact support.


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

If we don’t find the payment service of the currency that was passed in to_currency parameter:


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

If accidentally something happens when converting to to_currency:


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

If the payment 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 payment 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 will not have an active merchant wallet with a cryptocurrency of the payment, you will receive this error:


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

If technical work occurs and the payment is temporarily unavailable, you can receive this error messages:


1{
2    "state": 1,
3    "message": "Gateway error"
4}
COPY


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


1{
2    "state": 1,
3    "message": "Server error"
4}
COPY

Internal server error

code : 500

example responses:


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