Create an invoice

POST

/invoice

Creates a new invoice on the account bound to the API key. The response includes a hosted payment page URL your customer can use to complete payment in crypto.

Required scope: invoices.create.

Authorizations

• TENANT_API_KEY

Request Body^required

Media typeapplication/json

object

amount

Fiat amount charged by the invoice. If a positive amount is sent, it is the invoice total even when items are also sent. Provide at least one of amount or items.

number

Example

49.99

items

Optional line items shown on the payment page. Used to compute the total only when amount is omitted.

Array<object>

object

name

required

string

quantity

required

number

cost

required

number

fiatCurrencyCode

required

ISO-4217 fiat currency code (e.g. USD, EUR).

string

Example

USD

orderId

required

Merchant-side idempotency key. Must be unique within your tenant. Retrying the request with the same orderId returns a 409.

string

<= 256 characters

Example

order_2026_04_001

description

Free-form description shown on the payment page.

string

<= 512 characters

webhookUrl

HTTPS URL to receive webhook notifications about this invoice. Must be a public, TLD-qualified HTTPS URL.

string

Example

https://merchant.example.com/webhooks/cryptonly

returnUrl

HTTP(S) URL for the “Return to merchant” CTA when the invoice is cancelled or expired. Accepts any http(s) URL, including local development hosts such as http://localhost:8000/....

string

<= 512 characters

Example

https://merchant.example.com/orders/order_2026_04_001

successUrl

HTTP(S) URL for the “Return to merchant” CTA when the invoice is paid or overpaid. Accepts any http(s) URL, including local development hosts such as http://localhost:8000/....

string

<= 512 characters

Example

https://merchant.example.com/orders/order_2026_04_001/success

failedUrl

HTTP(S) URL for the “Return to merchant” CTA when the invoice is failed, suspended, or partially_paid. Accepts any http(s) URL, including local development hosts such as http://localhost:8000/....

string

<= 512 characters

Example

https://merchant.example.com/orders/order_2026_04_001/failed

expiresInMinutes

Invoice expiry in minutes from creation. Clamped to a server-side maximum. Maximum is 30 days.

number

>= 15 <= 43200

customerId

Customer ID from your system.

string

<= 52 characters

Example

customer_1234567890

customPayload

Custom payload to be sent to the webhook.

string

<= 2048 characters

Example

{"key1":"value1","key2":"value2"}

number

Optional reference shown to the customer on the payment page (e.g. order or invoice id). If empty - orderId is shown instead.

string

<= 256 characters

Responses

201

Invoice created.

Media typeapplication/json

object

data

required

Invoice data (same shape as GET /invoice).

object

id

required

string

accountId

required

string format: uuid

orderId

string

amount

required

number

fiatCurrencyCode

required

string

items

required

Array<object>

object

name

required

string

quantity

required

number

cost

required

number

status

required

string

Allowed values: created processing paid partially_paid overpaid expired cancelled failed suspended

cryptoCurrencyCode

string

Allowed values: USDT_TRC20 USDT_ERC20 USDT_BEP20 USDC_ERC20 USDC_BEP20 USDC_BASE EURC_BASE LINK_ERC20 LINK_BEP20 ETH TRX BNB BTC ETH_BASE

cryptoAmountExpected

number

cryptoAmountReceived

number

address

string

txHash

string

settlement

object

amountPaid

required

number

amountPaidUsd

required

number

commissionAmount

required

number

commissionAmountUsd

required

number

networkFeeAmount

required

number

networkFeeAmountUsd

required

number

networkFeeCurrencyCode

required

string

netAmount

required

number

netAmountUsd

required

number

txHash

string

completedAt

required

string

description

string

number

Optional reference for the customer on the payment page, when set at creation.

string

<= 256 characters

webhookUrl

string

returnUrl

Browser CTA URL for cancelled / expired, when provided at creation.

string

successUrl

Browser CTA URL for paid / overpaid, when provided at creation.

string

failedUrl

Browser CTA URL for failed / suspended / partially_paid, when provided at creation.

string

expiresAt

required

ISO 8601 timestamp.

string

createdAt

required

ISO 8601 timestamp.

string

paidAt

When payment settled (ISO 8601), if applicable.

string

customerId

Merchant-supplied customer reference when provided at creation.

string

customPayload

Opaque string from creation; echoed on webhooks when set.

string

paymentPageUrl

required

Hosted payment page URL for this invoice.

string

source

Creation channel; omitted when unknown (rows created before this metadata existed).

string

Allowed values: api admin_panel

Example

{
  "data": {
    "status": "created",
    "cryptoCurrencyCode": "USDT_TRC20",
    "paymentPageUrl": "https://payment.cryptonly.com/invoice/...",
    "source": "api"
  }
}

400

Validation error, missing fiat currency, amount below the configured minimum, or the referenced customerId is blocked (exceptions.invoice.customerBlocked).

401

Missing or invalid x-tenant-api-key header. Code: exceptions.auth.invalidApiKey.

Media typeapplication/json

object

code

required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string

message

required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string

extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object

key

additional properties

any

Example

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

403

Request origin IP is not on the tenant API allowlist (exceptions.auth.ipNotAllowed), or the API key is missing the scope required by this operation (exceptions.auth.insufficientScope).

Media typeapplication/json

object

code

required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string

message

required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string

extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object

key

additional properties

any

Example

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

409

An invoice with the supplied orderId already exists.

429

Rate limit exceeded for this endpoint. Retry after the window resets. Code: exceptions.rateLimit.exceeded. The extension.msBeforeNext field tells you how long to wait.

Media typeapplication/json

object

code

required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string

message

required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string

extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object

key

additional properties

any

Example

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

500

Unexpected server error. Safe to retry idempotent operations after a backoff.

Media typeapplication/json

object

code

required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string

message

required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string

extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object

key

additional properties

any

Example

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}