Creating an invoice

post

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

COPY

Request

Query parameters

Name	Parameter type	Default value	Definition
amount*	string		Amount to be paid.If there are pennies in the amount, then send them with a separator '.' Example: 10.28
currency*	string		Currency code
order_id*	stringmin: 1max: 128alpha_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 invoices/static wallets/recurrence paymentsWhen we find an existing invoice with order_id, we return its details, a new invoice will not be created.
network	string	null	Blockchain network code
url_return	stringmin: 6max: 255url	null	Before paying, the user can click on the button on the payment form and return to the store page at this URL.
url_success	stringmin: 6max: 255url	null	After successful payment, the user can click on the button on the payment form and return to this URL.
url_callback	stringmin: 6max: 255url	null	Url to which webhooks with payment status will be sent
is_payment_multiple	boolean	true	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.
lifetime	integermin: 300max: 43200	3600	The lifespan of the issued invoice (in seconds)
to_currency	string		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: BTCThe 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.
subtract	integermin: 0max: 100	0	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.
accuracy_payment_percent	numericmin: 0max: 5	0	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
additional_data	stringmax: 255	null	Additional information for you (not shown to the client)
currencies	array	The 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_currencies	array	null	List of excluded currencies for payment Structure
course_source	stringmin: 4max: 20Available values• Binance• BinanceP2P• Exmo• Kucoin• Garantexio	If not passed, Cryptomus exchange rates are used.	The service from which the exchange rates are taken for conversion in the invoice.
from_referral_code	string	null	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.
discount_percent	integermin: -99max: 100	null	Positive numbers: Allows you to set a discount. To set a 5% discount for the payment, you should pass a value: 5Negative 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_refresh	boolean	false	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.

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: BTCThe 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
Available values- Binance- BinanceP2P- Exmo- Kucoin- Garantexio

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: 5Negative 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

Name	Definition
currency*	Currency code
network	Blockchain network code

: Definition
Currency code
: Definition
Blockchain network code

* - mandatory parameter

Structure of except_currencies

Name	Definition
currency*	Currency code
network	Blockchain 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

Name	Definition
uuid	Invoice uuid
order_id	Order ID in your system
amount	The amount of the invoice
payment_amount	Amount paid by client
payer_amount	The amount in payer_currency that the customer must pay, including a discount or additional commission.
discount_percent	Percentage of discount or additional commission, that was passed in request parameters
discount	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
payer_currency	The currency in which the customer must make the payment.
currency	Invoice currency code
merchant_amount	Amount in crypto that will be credited to your balance. If invoice payer_currency is not specified, the value will be null.
network	Blockchain network code
address	Wallet address for payment
from	The address of the wallet from which the payment was made
txid	Transaction hash
payment_status	Payment status All payment statuses
url	URL payment page
expired_at	Timestamp of expiration of the invoice
is_final	Whether the invoice is finalized.When invoice is finalized it is impossible to pay an invoice (it's either paid or expired)
additional_data	Additional information
created_at	Creation date of the invoice. Timezone is UTC+3
updated_at	Last 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