Skip to content
CryptonlyCryptonlyCryptonly

Retrieve an invoice

GET
/invoice

Retrieves a single invoice by its id (UUID) or the merchant orderId on the account bound to the API key. At least one of id or orderId must be supplied; if both are present, id takes precedence. The response always includes paymentPageUrl for the hosted payment page.

Required scope: invoices.list.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
id
string format: uuid

Invoice ID (UUID) returned from POST /invoice. Mutually optional with orderId.

orderId
string

Merchant orderId supplied when the invoice was created. Mutually optional with id.

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
data
required
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

Section titled “400”

Neither id nor orderId was supplied, or a supplied value failed validation.

401

Section titled “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

Section titled “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"
}

404

Section titled “404”

Invoice not found.

429

Section titled “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

Section titled “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"
}