Main
/Payments
/Creating an invoice
Copy page
| 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 swapping the invoice amount. When creating an invoice, you provide an amount and currency, and the API will swap 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 swap 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 | If not passed, Heleket 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 Heleket 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 Heleket 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. |
| payer_email | stringnull | null | Payer's email |
| theme | stringnullAvailable values• dark• light | null | Theme |
* - mandatory parameter
| Name | Definition |
|---|---|
| currency* | Currency code |
| network | Blockchain network code |
* - mandatory parameter
| Name | Definition |
|---|---|
| currency* | Currency code |
| network | Blockchain network code |
* - mandatory parameter
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.heleket.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"
}'| 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. |
| payer_amount_exchange_rate | Exchange rate of the payer_currency at the moment of invoice creation |
| 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 |
| comments | Internal service comments on the payment, null if there are none |
| 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 in the blockchain.The txid field will not exist if1) The payment was made via p2p (The payer withdrew funds from his Heleket account to the address specified in the invoice, and the payment was made without blockchain, only in our system)2) The payment was not made3) Something went wrong with the payment or the customer made a mistake and we marked it as 'paid' manually |
| payment_status | Payment status All payment statuses |
| status | Duplicates payment_status and is kept for backward compatibility |
| 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 |
| address_qr_code | QR code with the wallet address for payment |
| payment_amount_usd | Amount actually paid by the client in US dollars |
| commission | Heleket commission amount |
| convert | Information about the currency to which the payment will be automatically swapped. Conversion is performed from payer_currency to USDTThe convert field will not exist if you have not enabled the automatic conversion function for payer_currency (e.g. auto convert BTC to USDT) Structure |
| Name | Definition |
|---|---|
| to_currency | The currency code to which the payment will be swapped |
| commission | Conversion fee |
| rate | Conversion rate |
| amount | Swap amount in to_currency that was added to the merchant's balance, with all commissions subtracted.amount here equals merchant_amount * rate |
1{
2 "state": 0,
3 "result": {
4 "uuid": "1ec87133-b22d-4643-988f-cac29a6ac85d",
5 "order_id": "3",
6 "amount": "20000.00",
7 "payment_amount": null,
8 "payment_amount_usd": "0.00",
9 "payer_amount": "254.92",
10 "payer_amount_exchange_rate": "78.45392451",
11 "discount_percent": 0,
12 "discount": "0.00",
13 "payer_currency": "USDT",
14 "currency": "RUB",
15 "comments": null,
16 "merchant_amount": "249.82816502",
17 "network": "bsc",
18 "address": "0x2b...",
19 "from": null,
20 "txid": null,
21 "payment_status": "check",
22 "url": "https://new-pay.heleket.com/pay/1ec87133-b22d-4643-988f-cac29a6ac85d?theme=light",
23 "expired_at": 1753202502,
24 "status": "check",
25 "is_final": false,
26 "additional_data": null,
27 "created_at": "2025-07-22T18:41:42+03:00",
28 "updated_at": "2025-07-22T18:42:31+03:00",
29 "commission": "5.09853397",
30 "address_qr_code": "data:image/png;base64 ..."
31 }
32}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}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}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}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}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}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}code : 422
example responses:
If some parameter is required and not passed:
1{
2 "state": 1,
3 "errors": {
4 "amount": ["validation.required"]
5 }
6}If you provided the network code that is not supported
1{
2 "state": 1,
3 "message": "The network was not found"
4}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}If your payments are blocked. In this case you need to contact support.
1{
2 "state": 1,
3 "message": "You are forbidden"
4}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}If accidentally something happens when swapping to to_currency:
1{
2 "state": 1,
3 "message": "Error convert to_currency"
4}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}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}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}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}
1{
2 "state": 1,
3 "message": "The terminal was not found"
4}
1{
2 "state": 1,
3 "message": "Server error"
4}code : 500
example responses:
1{
2 "message": "Server error, #1",
3 "code": 500,
4 "error": null
5}