Checkout API operations
Additional public operations used by hosted checkout.
Most integrations should use the checkout URL returned by invoice creation. The hosted checkout already handles token selection, network selection, rate previews, and confirmation progress.
Available operations
| Method and path | Purpose |
|---|---|
GET /api/invoices/:id | Read the current public invoice. |
GET /api/invoices/:id/rate?token_code=... | Preview the amount for a token. |
POST /api/invoices/:id/rate | Compatibility form of the rate preview; body contains token_code. |
POST /api/invoices/:id/method | Issue a method using network_code and, when needed, token_code. |
POST /api/invoices/:id/tokens | Read token codes eligible for this invoice, including its issued route. |
GET /api/networks?token_code=... | Read global active network codes, optionally filtered by token. |
These operations are public and must not receive a merchant secret. The downloadable OpenAPI includes every operation below, with the same request schemas and HTTP success codes as the gateway. All return 200; the two merchant invoice creation operations return 201.
Preview a token quote
/api/invoices/{id}/ratePreview a token quote without issuing a payment address. Public endpoint. Merchant credentials are not required.
| Field | Type | Required | Description |
|---|---|---|---|
idpath | string | Yes | Invoice ID returned at creation. |
token_codequery | string | Yes | Eligible token code. Duplicate and unknown rate query parameters are rejected. |
Source: download OpenAPI 3.1. Examples below use illustrative values.
Set CRYPTIUM_API_URL to your API origin. Authenticated examples also use CRYPTIUM_MERCHANT_ID and CRYPTIUM_API_KEY from your server environment. Replace the example IDs and asset codes with values from your deployment.
curl --silent --show-error --fail-with-body --max-time 15 \
--request GET "${CRYPTIUM_API_URL%/}/api/invoices/22222222-2222-4222-8222-222222222222/rate?token_code=USDT"cURL requires OpenSSL and cURL 7.76+. JavaScript uses Node.js 18+; Python 3 uses the standard library; PHP requires the cURL extension. JSON bodies are compact UTF-8: sign the serialization described in authentication.
The response contains decimal strings rate and payment_amount, for example { "rate": "1", "payment_amount": "81.2" }. The customer charge includes a customer-paid service fee. The rate query requires token_code and rejects duplicate or unknown query parameters.
Compatibility POST quote
/api/invoices/{id}/rateCompatibility form of the token quote. Public endpoint. Merchant credentials are not required.
| Field | Type | Required | Description |
|---|---|---|---|
token_code | string | Yes | Token eligible for this invoice. |
idpath | string | Yes | Invoice ID returned at creation. |
Source: download OpenAPI 3.1. Examples below use illustrative values.
Set CRYPTIUM_API_URL to your API origin. Authenticated examples also use CRYPTIUM_MERCHANT_ID and CRYPTIUM_API_KEY from your server environment. Replace the example IDs and asset codes with values from your deployment.
body='{"token_code":"USDT"}'
curl --silent --show-error --fail-with-body --max-time 15 \
--request POST "${CRYPTIUM_API_URL%/}/api/invoices/22222222-2222-4222-8222-222222222222/rate" \
--header 'Content-Type: application/json' \
--data-binary "$body"cURL requires OpenSSL and cURL 7.76+. JavaScript uses Node.js 18+; Python 3 uses the standard library; PHP requires the cURL extension. JSON bodies are compact UTF-8: sign the serialization described in authentication.
This accepts { "token_code": "USDT" } in the JSON body and returns the same quote shape.
Read invoice tokens
/api/invoices/{id}/tokensRead token codes available to this invoice. Public endpoint. Merchant credentials are not required.
| Field | Type | Required | Description |
|---|---|---|---|
idpath | string | Yes | Invoice ID returned at creation. |
Source: download OpenAPI 3.1. Examples below use illustrative values.
Set CRYPTIUM_API_URL to your API origin. Authenticated examples also use CRYPTIUM_MERCHANT_ID and CRYPTIUM_API_KEY from your server environment. Replace the example IDs and asset codes with values from your deployment.
curl --silent --show-error --fail-with-body --max-time 15 \
--request POST "${CRYPTIUM_API_URL%/}/api/invoices/22222222-2222-4222-8222-222222222222/tokens"cURL requires OpenSSL and cURL 7.76+. JavaScript uses Node.js 18+; Python 3 uses the standard library; PHP requires the cURL extension. JSON bodies are compact UTF-8: sign the serialization described in authentication.
Send no body. The result is an array such as [{ "token_code": "USDT" }], derived from this invoice's public tokens list. It includes an already issued route even if that asset is later disabled for new selections. A missing invoice returns 404 INVOICE_NOT_FOUND.
Issue a payment method
/api/invoices/{id}/methodIssue a payment method and return the updated public invoice. Public endpoint. Merchant credentials are not required.
| Field | Type | Required | Description |
|---|---|---|---|
network_code | string | Yes | Eligible network code from the public invoice. |
token_code | string | No | Required for FIAT invoices. If omitted for CRYPTO, the invoice currency is used. |
idpath | string | Yes | Invoice ID returned at creation. |
Source: download OpenAPI 3.1. Examples below use illustrative values.
Set CRYPTIUM_API_URL to your API origin. Authenticated examples also use CRYPTIUM_MERCHANT_ID and CRYPTIUM_API_KEY from your server environment. Replace the example IDs and asset codes with values from your deployment.
body='{"network_code":"ERC20","token_code":"USDT"}'
curl --silent --show-error --fail-with-body --max-time 15 \
--request POST "${CRYPTIUM_API_URL%/}/api/invoices/22222222-2222-4222-8222-222222222222/method" \
--header 'Content-Type: application/json' \
--data-binary "$body"cURL requires OpenSSL and cURL 7.76+. JavaScript uses Node.js 18+; Python 3 uses the standard library; PHP requires the cURL extension. JSON bodies are compact UTF-8: sign the serialization described in authentication.
network_code is required. For a FIAT invoice also pass token_code; for CRYPTO it defaults to the invoice's currency. Unknown JSON properties are rejected. The response is the updated public invoice, including the issued pay object.
If FIAT token_code is omitted, the current gateway returns 400 with message UNKNOWN_ERROR and no machine-readable code. Handle the HTTP status; do not depend on TOKEN_REQUIRED for this gateway-level case.
Read global networks
/api/networksRead global active network codes; not invoice eligibility. Public endpoint. Merchant credentials are not required.
| Field | Type | Required | Description |
|---|---|---|---|
token_codequery | string | No | Optional exact token-code filter. This global catalog does not validate invoice eligibility. |
Source: download OpenAPI 3.1. Examples below use illustrative values.
Set CRYPTIUM_API_URL to your API origin. Authenticated examples also use CRYPTIUM_MERCHANT_ID and CRYPTIUM_API_KEY from your server environment. Replace the example IDs and asset codes with values from your deployment.
curl --silent --show-error --fail-with-body --max-time 15 \
--request GET "${CRYPTIUM_API_URL%/}/api/networks?token_code=USDT"cURL requires OpenSSL and cURL 7.76+. JavaScript uses Node.js 18+; Python 3 uses the standard library; PHP requires the cURL extension. JSON bodies are compact UTF-8: sign the serialization described in authentication.
Returns an array such as [{ "network_code": "ERC20" }]. The optional token_code filters the global active catalog by exact code; repeated networks are possible.
Quote versus issued amount
A rate preview does not allocate an address or lock a payment amount. After selecting a method, use the returned pay.amount_expected and address. A fiat-priced invoice needs an explicit token when selecting a method.
A method-selection response can fail after the method was committed, for example if the following read times out. Reconcile the public invoice before changing your operation.
Network lists and invoice eligibility
The network-list operation is global. It does not establish whether an asset is accepted for a specific merchant or invoice. The invoice-token operation is scoped to the invoice; use the public invoice's tokens and indexed networks combinations to choose a complete route. The method operation validates eligibility.
An expired invoice cannot obtain a new payment method or quote. An identical replay of an already issued method returns its saved instructions.