Skip to main content
POST
Tell Liddie the fiat amount you want to charge. It quotes that into crypto at the current rate, derives a unique deposit address, and hands you the hosted invoice URL.
When you omit currency (the AWAITING_CURRENCY path), the 201 body is only { "paymentId", "amount", "invoiceUrl", "status": "AWAITING_CURRENCY" } — and here amount is the fiat value echoed back, not a crypto quantity. There is no depositAddress, feeAmount/netAmount, expiresAt/quoteExpiresAt, or currency yet: those appear only once the payer (or Select pay currency) locks a currency. The fields documented below describe the currency-set response.
Always send an Idempotency-Key — a UUID per order. If your request times out or your process crashes mid-flight, retrying with the same key returns the same paymentId instead of creating a duplicate invoice.

​
Authorization

  • API-key scope: payments:create · JWT team permission: payments:manage
  • Your merchant account must be active.

​
Headers

​
string
Recommended: a UUID per order. 1–255 printable ASCII characters, no spaces. A second POST with the same key returns the same paymentId instead of creating a duplicate. Takes precedence over the idempotencyKey body field.

​
Body

​
number
required
Must be greater than 0. This is a fiat amount (your display currency, USD by default) — not a crypto amount. “Charge $75, payable in DOGE.” The response’s amount is the crypto quantity the payer must send, quoted at the current rate — e.g. {"currency":"DOGE","amount":75} returns amount: 1049.2885 DOGE with fiatAmount: 75, fiatCurrency: "USD" on the detail.
​
string
Ticker the payer will pay in, e.g. BTC, USDT_TRC20. Omit it and the payer chooses on the invoice page (status AWAITING_CURRENCY). Case-insensitive — upper-cased server-side.
​
string
Your own order reference. Max 256 characters.
​
any JSON
Max 8 KB. Opaque passthrough, echoed verbatim in webhooks/IPN. See the Webhooks & IPN guide.
​
string (URI)
Server-to-server IPN target. Max 2048 characters. HTTPS required in production; internal/private addresses are rejected; must match your callback-domain allowlist if you configured one.
​
string (URI)
Where the hosted invoice redirects the payer after payment. Max 2048 characters. Same URL rules as ipnCallbackUrl.
​
string (URI)
Redirect target for a terminal non-success outcome (expired / failed / cancelled). Max 2048 characters, same URL rules as ipnCallbackUrl. Falls back to invoiceCallbackUrl when omitted — set it to split success and cancel redirects.
​
number (seconds)
Invoice lifetime, 60–172800. Values outside that range are rejected with 400 (not clamped) — e.g. 200000 fails validation rather than yielding a 48 h invoice. Omit for the platform default.
​
string
Your own customer reference. Max 256 characters.
​
string
Free tag echoed back on the payment detail. Max 256 characters.
​
string
Body fallback for the header — the Idempotency-Key header wins when both are present. 1–255 printable ASCII characters, no spaces.
Unknown body fields are silently dropped, not rejected. The schema is additionalProperties: false, but the validator is configured to strip rather than refuse, so a misspelt field (amoutn for amount) does not answer 400 — the request succeeds and the platform default applies to the field you meant to set. Assert on the fields in the response rather than assuming your body arrived intact. This applies to every endpoint on this API.

​
Response fields

​
string
24-hex payment id. Use it for Get a payment, cancel, refunds, etc.
​
string
Unique to this payment. HD-derived: a fresh address is generated from your wallet for every payment — addresses are never reused.
​
number
The crypto quantity the payer must send, in crypto units of currency. Your fiat input is echoed on the payment detail as fiatAmount/fiatCurrency.
​
number
Platform commission + network-fee provision, in crypto units. Fee rounds up. With feeBearer: "customer" the fee is added on top of your price instead (the payer covers it — see grossFiat on the payment detail).
​
number
What you will be credited, in crypto units. Net rounds down.
​
string (ISO date)
Invoice expiry instant.
​
string (ISO date)
The crypto quote is only guaranteed until this instant; the hosted invoice refreshes it automatically.
​
string
The hosted checkout path, not a full URL. Prepend the checkout host to send a payer there: https://dash.liddie.io/i/exampleslug1 — the checkout is served from dash.liddie.io, not from the API host. Its last segment (exampleslug1) is the public invoiceId for GET /getInvoiceStatus.
​
string
The ticker the payer pays in.
​
string
Initial lifecycle status — WAITING, or AWAITING_CURRENCY if currency was omitted. See the Payments overview.

​
Errors

The ones you’ll hit most often:
Schema-level failures (bad types, out-of-range values like amount ≤ 0 or expiresIn out of range) use the {"ok":false,"error":{"code":"VALIDATION_ERROR","message":…}} envelope. Handler-emitted business errors use the flat {"error":"…"} shape shown in the full table below.

​
See also

  • Get a payment: fetch the full detail and fee breakdown once the payer starts paying.
  • Webhooks & IPN: get lifecycle transitions pushed to your server instead of polling.
  • Cancel a payment: void the invoice while it is still waiting for funds.