Create Checkout Payment

Creates a new fiat-denominated checkout payment session (invoice) and returns a hosted payment page URL. The customer will select a cryptocurrency on the payment page. This behaves similarly to KingPay’s /checkout/request/ endpoint.

Optional confirmations sets the incoming confirmation threshold for new addresses on UTXO, EVM and TRON. If omitted, the core API default applies. Existing addresses are not changed. Solana uses a network confirmation stage, not custom numeric depth. TRON distribution waits separately for its safety threshold and a successful solidified receipt.

GET https://api-service.kingpay.online/checkout/request/

All parameters are passed via query string. The response contains a payment_url you can redirect the customer to.

Notices

This endpoint creates a fiat-based invoice. The customer chooses the cryptocurrency on the payment page.
The invoice is linked to a specific project, resolved from your apikey.
If currency is omitted, the project’s default active fiat currency is used.
If redirect_url is not provided, the project's configured redirect URL is used. One of them must exist.
If notify_url is not provided, the project’s default IPN callback URL is used if configured. If neither exists, no IPN callbacks will be sent.
Fiat currencies must be active in your merchant configuration.
post=1 forces all callbacks for this invoice to use HTTP POST instead of GET.

Query parameters (required)

apikey string • required

Project API key generated in your merchant dashboard. Identifies which project this checkout belongs to.

May be sent either as a query parameter or as an apikey HTTP header.

value float • required

Fiat amount to charge the customer. Denominated in currency (or the project’s default fiat currency).

Must be a positive number.

Query parameters (optional)

redirect_url string • optional

URL where the customer should be redirected after payment. Required if your project does not have a default redirect URL configured.

currency string • optional

Fiat currency code (USD, EUR, ...) used for value. Must be active. If omitted, the project’s default active fiat currency is used.

item_description string • optional

Free-form description of the product or order (e.g. “Order #1234, Premium plan”). May be shown on the payment page or used in your internal system.

external_id string • optional

Merchant-side order identifier or reference (e.g. ORDER-12345). Stored in the invoice and returned in callbacks so you can easily match payments to your internal orders.

customer_email string • optional

Customer email address. Stored in the invoice for your records and may be used in notifications.

customer_name string • optional

Customer name or identifier. Saved to the invoice metadata and may be displayed on the payment page.

notify_url string • optional

Custom IPN callback URL for this checkout. If omitted, the project’s default IPN callback URL will be used (if set). If neither is configured, no IPN callbacks will be sent.

expire_at integer • optional

Lifetime in seconds from creation, not a Unix timestamp: 3600 to 604800 (1 hour to 7 days). Defaults to 3600.

json integer · optional

json=1 sends callbacks as POST application/json, preserving types and null values for signature verification. Takes precedence over post. Omit both flags for GET; use only post=1 for form-encoded POST.

post integer • optional

post=1 — send IPN callbacks for this invoice using HTTP POST instead of GET when JSON mode is not selected. Without either flag callbacks use GET. The payload format is the same.

Request example (cURL)

curl -G \
  'https://api-service.kingpay.online/checkout/request/' \
  --data-urlencode 'apikey=YOUR_PROJECT_API_KEY' \
  --data-urlencode 'value=99.90' \
  --data-urlencode 'currency=USD' \
  --data-urlencode 'item_description=Order #1234 – Premium plan' \
  --data-urlencode 'external_id=ORDER-1234' \
  --data-urlencode '[email protected]' \
  --data-urlencode 'customer_name=John Doe' \
  --data-urlencode 'redirect_url=https://example.com/thank-you' \
  --data-urlencode 'notify_url=https://example.com/ipn/cryptapi' \
  --data-urlencode 'post=1'

Response (200 • application/json)

{
  "status": "success",
  "payment_id": "e1f3d8b9a24c4f2e9b4d6a3c1f2a9c3b",
  "success_token": "8c0d3a9b9a1c4f3e8b1d2c3a4f6e7b1f4c0d9a8e1b2c3d4e5f6a7b8c9d0e1f2",
  "payment_url": "https://pay.yourdomain.com/pay/e1f3d8b9a24c4f2e9b4d6a3c1f2a9c3b"
}

Response fields

status — request result. "success" on successful session creation.
payment_id — internal invoice UID. Store it in your system to match callbacks and logs.
success_token — token returned to your redirect URL after a successful payment. Use it to securely confirm the transaction on your side.
payment_url — hosted payment page URL. Redirect the customer or open it in a new tab.

Error responses

401 • apikey is required — missing API key.
401 • Invalid API key — API key not found or project inactive.
400 • value is required — missing payment amount.
400 • value must be a valid positive number — amount is not a valid number.
400 • amount must be positive — amount is zero or negative.
400 • Unsupported FIAT currency: XXX — currency code is not active or not configured.
400 • Fiat currency is not provided and project has no default active fiat currency — no currency parameter and no default project currency.
400 • redirect_url is required — no redirect URL provided and none configured in the project.
400 • expire_at must be a positive number of seconds — invalid expire_at format.
400 • expire_at must be at least 1 hour — expiration time is too soon.
500 • Internal server error — unexpected server-side error.