# How to create a crypto invoice priced in USD

> Bill in dollars, get paid in crypto: create a CryptoLike invoice in the cabinet or with POST /v1/invoices, lock the rate, set the time to pay and track the status.

Source: https://cryptolike.net/guides/create-crypto-invoice
Published: 2026-09-24 · Updated: 2026-10-11 · Author: CryptoLike team

To bill in dollars and get paid in crypto with CryptoLike, create a payment with the amount in USD — in the cabinet (Invoices → Create invoice) or with `POST /v1/invoices` and `"currency": "USD"`. The exchange rate is locked when the coin is known, the customer pays on a checkout page with a timer, and the status moves from `new` to `pending` to `paid`.

A [crypto invoice](https://cryptolike.net/glossary/crypto-invoice) is a one-off payment for a fixed amount with a time limit. It fits B2B bills, orders placed by message and anything priced in fiat — see [crypto invoicing for business](https://cryptolike.net/use-cases/invoicing) for the scenario, and [rate lock](https://cryptolike.net/glossary/rate-lock) for how the dollar price turns into a crypto amount.

## Before you start

A CryptoLike account is enough to create a USD-priced invoice in the cabinet. For the API you also need a key with the `create_invoice` and `read` permissions, its secret kept on your server, and optionally a webhook endpoint. A test key (`ck_test_`) with the test API URL from CryptoLike support lets you rehearse the whole flow on test networks first; on mainnet it is refused with `401 auth.test_key`.

- **Cabinet path:** no code; you send the customer a payment link.
- **API path:** requests are signed with HMAC-SHA256 — see [API authentication](https://cryptolike.net/docs/auth).
- **Assets:** BTC, LTC, ETH, USDT and USDC (ERC20), TRX and USDT (TRC20); your enabled list is in `GET /v1/currencies`. Invoices offer only the coins with both switches on in Coins: Enabled and For invoices.

## 1. Open the invoice form and enter the amount in USD

In the CryptoLike cabinet, open Invoices and press Create invoice. Type the amount as a decimal, for example `250.00`, and choose the currency in the Currency list: it starts on your Default fiat currency from Settings, and the Fiat group lists every fiat currency enabled for your account. With a specific coin selected, the form shows an approximate crypto amount at the current rate — a preview only, because the server locks the rate itself.

To bill in crypto instead, choose a ticker such as `USDT` from the Crypto group: no conversion happens, and either you pick the network in the Coin field or the customer picks it on the payment page.

## 2. Fix the coin now or let the customer choose

CryptoLike locks the exchange rate at the moment the coin becomes known, and it stays fixed for the invoice's whole time to pay. Under How the payer pays, In a specific coin means you pick the asset now: the rate is locked at creation and the deposit address is issued immediately. The payer chooses means the customer picks a coin on the payment page and the rate is locked at that moment.

With The payer chooses, the field Coins the payer can choose starts with every coin available for invoices in this currency; remove some to offer fewer. If only one coin is available, the form fixes it. On the payment page each coin shows an approximate amount marked ≈, and the exact amount and rate are fixed when the customer chooses.

| Aspect | Fix the coin | Customer chooses |
|---|---|---|
| Rate locked | At creation | When the customer picks the coin |
| Address and crypto amount | In the invoice right away | After the choice |
| Checkout page | Amount, network, address, QR | "Choose what to pay with" first, with a ≈ amount for each coin |
| Good for | You agreed on the asset with the customer | You accept several assets |

The invoice stores `amount_fiat`, the locked rate `rate_locked` (1 coin = N USD), `rate_locked_at` and the crypto amount due.

## 3. Set the time to pay and the invoice details

CryptoLike closes an unpaid invoice when its time to pay ends: the status becomes `expired`. In the form, choose 15 min, 30 min (the default), 1 h, 6 h or 24 h; under Advanced, Custom lifetime sets a lifetime in minutes, up to 30 days. Add an Order ID and a Description so the payment is easy to find and reconcile later.

Advanced also holds three integration fields:

- **Return URL** — the "back to the shop" link shown after payment.
- **Webhook URL** — this invoice's events are also sent there (`https`, public host), signed with the secret of your oldest enabled endpoint. It needs an enabled endpoint in Developers → Webhooks; without one the invoice is refused with an error on this field.
- **Platform fee paid by** — Merchant (deducted from what you receive, the default) or Payer (added to what the customer sends). The rates are on the [pricing page](https://cryptolike.net/pricing).

## 4. Share the payment link with the customer

After Create invoice, CryptoLike opens the invoice card with a Share payment link block: copy the link, show the QR code, or copy a ready message with the amount and the expiry time that you can edit before sending. The customer opens the payment page and sees the amount, the network, the address, the time left and the live status.

An expired or cancelled invoice has no link to share: create a new payment. More ways to send a [payment link](https://cryptolike.net/glossary/payment-link): [payment links from the cabinet or Telegram](https://cryptolike.net/use-cases/payment-links), and every sharing option in the [payment link guide](https://cryptolike.net/guides/crypto-payment-link).

## 5. Create the same invoice through the API

With the CryptoLike API, one signed request creates the invoice: `POST /v1/invoices` with `amount` as a decimal string and `currency: "USD"`. Add `coin_id` from `GET /v1/currencies` to fix the coin now, or omit it to let the customer choose; `allowed_coin_ids` (1 to 100 ids, not together with `coin_id`) narrows that choice for this invoice. Send an `Idempotency-Key`: a retry within 24 hours returns the original invoice instead of creating a second one.

```bash
# Signing lines (TS, SIG) as in the API authentication docs; CRYPTOLIKE_API_URL = the test API URL while testing
BODY='{"amount":"250.00","currency":"USD","order_id":"INV-2026-0042","description":"Consulting, September","ttl_seconds":86400,"return_url":"https://example.com/thanks"}'
curl -s "${CRYPTOLIKE_API_URL:-https://api.cryptolike.net}/v1/invoices" \
  -H "Content-Type: application/json" -H "Idempotency-Key: INV-2026-0042" \
  -H "X-API-Key: $KEY_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" -d "$BODY"
```

The response carries `status: "new"`, the dollar amount in `amount_fiat`, `fiat_currency: "USD"` and `checkout_url` — the page to send the customer to. Without `coin_id`, the fields `coin_id`, `address`, `amount_crypto` and `rate_locked` stay `null` until the customer chooses. `ttl_seconds` accepts 60 to 2,592,000 seconds (30 days); the account default is 30 minutes. The response's `allowed_coin_ids` is the list CryptoLike kept: ids of coins you do not offer for invoices in this currency are dropped, and `null` means every coin you offer. The [SDKs](https://cryptolike.net/docs/sdk) wrap the same call and take the same list.

## 6. Track the status until the invoice is paid

CryptoLike reports every status change of the invoice by a signed webhook — `invoice.pending`, `invoice.paid`, `invoice.underpaid`, `invoice.expired` — and the same status is in `GET /v1/invoices/{id}` and in the cabinet. Ship the order or close the bill on `paid`: the funds are confirmed and credited to your balance. Verify every webhook first, as in the [webhook verification guide](https://cryptolike.net/guides/verify-crypto-payment-webhooks).

| Status | What happened | What to do |
|---|---|---|
| `new` | Created, nothing received | Wait, or cancel it (only from `new`). |
| `pending` | Transfer detected, waiting for confirmations | Wait; do not ship yet. |
| `paid` | Full amount confirmed and credited | Fulfil the order. |
| `underpaid` | Less than due confirmed | The customer sends `remaining_amount` to the same address before the time runs out. |
| `expired` | Time to pay ended, nothing confirmed | Create a new payment. |
| `cancelled` | You cancelled it | Create a new payment if needed. |

An overpayment is still `paid`, with `overpaid_amount` greater than zero. Funds that arrive after the invoice closed are credited too, with `late_payment: true` and an `invoice.late_payment` webhook; the status does not change, so decide with the customer whether to fulfil or refund. More in [underpaid and late payments](https://cryptolike.net/blog/underpaid-crypto-payments).

## Errors and fixes

CryptoLike returns every API error in one envelope with a machine `code`, a human `message` and `details`; the field at fault is in `details.field`. The table lists the errors you are most likely to meet when creating a USD-priced invoice, with the fix for each.

| HTTP · code | What happened | What to do |
|---|---|---|
| 400 `validation_error`, field `amount` | Not a positive decimal string, converts to zero, or outside your account's limits | Send the amount as a string such as `"250.00"` within the limits. |
| 400 `validation_error`, field `currency` | Not an enabled fiat code nor an available ticker, or more decimals than the currency allows (2 for USD, EUR, UAH, GBP and CAD) | Use a code from `GET /v1/fiat-currencies` or a ticker from `GET /v1/currencies`. |
| 400 `validation_error`, field `coin_id` | The coin is switched off, not available for invoices, or does not match `currency` | Turn the coin on in Coins (Enabled and For invoices), or pick another `coin_id`. |
| 422 `no_allowed_coins` | None of `allowed_coin_ids` is offered for invoices in this currency | Send other ids, or turn For invoices on for one of them in Coins. |
| 401 `auth.*` | Signature, key or timestamp problem | Check the signing steps in [API authentication](https://cryptolike.net/docs/auth). |
| 403 `auth.permission_denied` | The key lacks `create_invoice` | Grant the permission in the cabinet. |
| 422 `idempotency.mismatch` | Same `Idempotency-Key`, different body | Use a new key for a new invoice. |
| 503 `unavailable` | No fresh exchange rate, or the coin is under maintenance | Retry later, or create the invoice in crypto. |

For invoices that repeat every billing period, see [crypto payments for subscriptions](https://cryptolike.net/use-cases/subscriptions).

## FAQ

These answers cover what businesses ask most often about USD-priced invoices on CryptoLike: whether the price moves after creation, what happens with a short payment, how long an invoice stays open, and how to fix an amount entered by mistake.

### Does the crypto amount change if the market moves?

No. Once the coin is known, the rate is locked for the invoice's whole time to pay, and the crypto amount due does not change. Before the choice the payment page shows only approximate amounts marked ≈; the exact amount is calculated again and locked when the customer picks the coin.

### What if the customer sends less than the amount due?

The invoice becomes `underpaid`, the payment page shows the remaining amount, and the customer can top it up to the same address until the time to pay ends. A small shortfall within your account's underpayment tolerance still counts as `paid`.

### How long can a crypto invoice stay open?

From 60 seconds to 30 days. The cabinet offers presets from 15 minutes to 24 hours plus a custom lifetime in minutes; the API takes `ttl_seconds`. The default for your account is 30 minutes.

### Can I change the amount of an invoice I already sent?

Cancel it while it is still `new` — nothing received yet — and create a new invoice with the right amount. An invoice with a detected or confirmed transfer cannot be cancelled.