# Creating an invoice **POST** `https://api.heleket.com/v1/payment` ## Request ### Body parameters | Name | Parameter type | Default value | Definition | | --- | --- | --- | --- | | amount (required) | string | | Amount to be paid.
If there are pennies in the amount, then send them with a separator '.'
Example: 10.28| | currency (required) | string | | Currency code| | order\_id (required) | string
min: 1
max: 128
alpha\_dash| | Order ID in your system
The 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 payments
When 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 | string
min: 6
max: 255
url| 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 | string
min: 6
max: 255
url| null | After successful payment, the user can click on the button on the payment form and return to this URL. | | url\_callback | string
min: 6
max: 255
url| 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 | integer
min: 300
max: 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**: BTC
The API will swap 20 USD amount to its equivalent in BTC based on the current exchange rate and the user will pay in BTC
The **to\_currency** should always be the cryptocurrency code, not a fiat currency code.| | subtract | integer
min: 0
max: 100| 0 | Percentage of the payment commission charged to the client
If 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 | numeric
min: 0
max: 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 | string
max: 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](https://doc.heleket.com/methods/payments/creating-invoice.md#response_parameters) | | except\_currencies | array | null | List of excluded currencies for payment [Structure](https://doc.heleket.com/methods/payments/creating-invoice.md#except_currencies) | | course\_source | string
min: 4
max: 20
Available 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 | integer
min: -99
max: 100| null | 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: -10
The 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 | string
null| null | Payer's email | | theme | string
null
Available values
• dark
• light| null | Theme | ### Structure of _Currencies_ (currency) | Name | Definition | | --- | --- | | currency (required) | Currency code | | network | Blockchain network code | ### Structure of _except\_currencies_ | Name | Definition | | --- | --- | | currency (required) | Currency code | | network | Blockchain network code | > 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.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" }' ``` ## 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. | | 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.75
i.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 if
1) 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 made
3) 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](https://doc.heleket.com/methods/payments/payment-statuses.md) | | 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 USDT
The _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](https://doc.heleket.com/methods/payments/creating-invoice.md#convert) | ### Structure of _convert_ | 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| ### Response example ``` { "state": 0, "result": { "uuid": "1ec87133-b22d-4643-988f-cac29a6ac85d", "order_id": "3", "amount": "20000.00", "payment_amount": null, "payment_amount_usd": "0.00", "payer_amount": "254.92", "payer_amount_exchange_rate": "78.45392451", "discount_percent": 0, "discount": "0.00", "payer_currency": "USDT", "currency": "RUB", "comments": null, "merchant_amount": "249.82816502", "network": "bsc", "address": "0x2b...", "from": null, "txid": null, "payment_status": "check", "url": "https://new-pay.heleket.com/pay/1ec87133-b22d-4643-988f-cac29a6ac85d?theme=light", "expired_at": 1753202502, "status": "check", "is_final": false, "additional_data": null, "created_at": "2025-07-22T18:41:42+03:00", "updated_at": "2025-07-22T18:42:31+03:00", "commission": "5.09853397", "address_qr_code": "data:image/png;base64 ..." } } ``` ### 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. ``` { "amount": "20", "currency": "USDT", "order_id": "1", "network": "tron" } ``` Request data to create an invoice for 25 USD and allow clients to pay only by USDT in any network. ``` { "amount": "25", "currency": "USD", "order_id": "1", "to_currency": "USDT" } ``` 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. ``` { "amount": "25", "currency": "USD", "order_id": "1", "to_currency": "USDT", "network": "tron" } ``` Request data to create an invoice for 20 USDT and allow clients to pay in all available networks ``` { "amount": "20", "currency": "USDT", "order_id": "1" } ``` 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. ``` { "amount": "20", "currency": "USD", "order_id": "1", "to_currency": "BTC" } ``` 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. ``` { "amount": "0.5", "currency": "BTC", "order_id": "1" } ``` ## Possible errors ### Validation errors code : 422 example responses: If some parameter is required and not passed: ``` { "state": 1, "errors": { "amount": ["validation.required"] } } ``` If you provided the network code that is not supported ``` { "state": 1, "message": "The network was not found" } ``` If we don’t support the currency code you provided in _currency_ parameter: ``` { "state": 1, "message": "The currency was not found" } ``` If your payments are blocked. In this case you need to contact support. ``` { "state": 1, "message": "You are forbidden" } ``` If we don’t find the payment service of the currency that was passed in _to\_currency_ parameter: ``` { "state": 1, "message": "Not found service to_currency" } ``` If accidentally something happens when swapping to _to\_currency_: ``` { "state": 1, "message": "Error convert to_currency" } ``` If the payment amount is less than the minimum supported amount for cryptocurrency, you will receive this error message: ``` { "state": 1, "message": "Minimum amount 0.5 USDT" } ``` If the payment amount is greater than the maximum supported amount for cryptocurrency, you will receive this error message: ``` { "state": 1, "message": "Maximum amount 10000000 USDT" } ``` If you will not have an active merchant wallet with a cryptocurrency of the payment, you will receive this error: ``` { "state": 1, "message": "Wallet not found" } ``` If technical work occurs and the payment is temporarily unavailable, you can receive this error messages: ``` { "state": 1, "message": "Gateway error" } ``` ``` { "state": 1, "message": "The terminal was not found" } ``` ``` { "state": 1, "message": "Server error" } ``` ### Internal server error code : 500 example responses: ``` { "message": "Server error, #1", "code": 500, "error": null } ```