Skip to main content

Checkouts

Check API availability and confirm access in your target environment before integrating.

OperationMethod and routeAvailability
Create a CheckoutPOST /v1/checkoutsMerchant route confirmed
Retrieve a CheckoutGET /v1/checkouts/{id}Merchant route confirmed
List CheckoutsGET /v1/checkoutsMerchant route confirmed
Close a CheckoutPOST /v1/checkouts/{id}/closeMerchant route confirmed
List payment detailsGET /v1/checkouts/{id}/paymentsAvailability pending

A Checkout represents a collection session. After creating it, show the returned url to the payer. The payer selects a payment network and pays in the platform's hosted checkout. Merchants retrieve payment outcomes by querying the session or, where available, receiving Webhooks, without managing underlying payment attempts.

Follow the common merchant API conventions.

See Payment methods for available currency/network combinations, Refunds for payment details and refunds, and Webhooks for notification handling and signature verification.

Confirm your account and environment support Checkout creation, retrieval, listing and closure; consult API availability. Payment details and merchant Checkout Webhook delivery remain pending availability. Use server-side Checkout retrieval while notification delivery is unavailable. The payment lifecycle guide explains fulfillment decisions.

Checkout Object​

Attributes​

AttributeTypeDescription
idstringUnique Checkout identifier
amountstringAmount to collect
currencystringCollection currency: usdc, usdt
transaction_speedstringConfirmation speed: high, medium, low; default low; see below
statusstringPrimary session state: open, processing, succeeded, failed; see below
failure_reasonstring / nullReason the session ended: expired or closed; populated only for failed, otherwise null
exception_statusstring / nullCurrent funds exception: paidOver or paidPartial; null when none exists
order_idstring / nullMerchant order reference; uniqueness is not required; null when unset
descriptionstring / nullCollection description shown to the payer; null when unset
metadataobjectMerchant-defined string key/value pairs, or {} when empty; at most 50 pairs, keys up to 40 characters, values up to 500 characters
urlstringHosted checkout URL; remains accessible to view results after the session ends
return_urlstring / nullDestination of the hosted checkout's “Return to merchant” button; null when unset, in which case no button is shown
expires_atstringExpiry fixed at creation; defaults to 30 minutes after successful creation
created_atstringCreation time
updated_atstringLast change to externally visible information, including primary state or funds exceptions

There is no Checkout update endpoint after creation. Reopening the page, switching payment networks, or retrying does not extend its lifetime.

status​

ValueMeaning
openWaiting for payment; the payer can select or switch networks before an on-chain payment is detected
processingAn on-chain payment has been detected and is awaiting the selected confirmation requirement; hosted checkout displays progress rather than inviting another payment
succeededBefore expiry or merchant closure, the platform confirmed that payment reached the selected transaction_speed; inspect exception_status and apply exception/order rules before fulfillment
failedConfirmation requirements were not met when the session expired or was closed; this collection session has ended, but the payer may still have spent funds

After a network switch, only the current payment attempt can make the session succeed. Funds received using old payment information are treated as exceptional receipts and do not prevent the current payment. If a confirming payment becomes invalid before the session ends, the session can return to open so the payer can continue.

succeeded and failed are terminal. Later receipts, refunds, or invalidated funds neither reverse the primary status nor reopen payment. Receipts or confirmation messages arriving after failure are treated as funds exceptions rather than retroactively making the Checkout successful. The outcome depends on the platform's confirmation decision before expiry or merchant closure.

failure_reason​

ValueMeaning
expiredThe selected confirmation requirement was not met at expiry
closedThe selected confirmation requirement was not met when the merchant server closed the session

Closing the browser page or returning to the merchant website does not end the session. While it remains active and unexpired, the original url can resume payment or display confirmation progress.

transaction_speed​

Selects when the Checkout becomes succeeded. Faster confirmation carries a higher risk that payment later becomes invalid. Choose according to how difficult it is to recover delivered goods or services, and apply order rules if funds subsequently become insufficient.

ValueMeaning
highFast: the payment transaction executed successfully and was included in a block
mediumStandard: the payment's block reached the native safe confirmation head (safe)
lowConservative: the payment's block reached the native finalized confirmation head (finalized); default

The session lifetime includes both paying and waiting for confirmation. Even an on-chain payment results in failed if it has not reached the selected confirmation requirement by session end.

exception_status​

Primary status and funds exceptions are independent. An exception describes current funds, not manual case-processing progress. Handle it together with order fulfillment rather than relying only on the primary status.

ValueMeaning
nullNo current funds exception, including before any payment
paidOverAdditional received funds have not been fully refunded, such as duplicate payments or receipts after session failure
paidPartialFunds previously recognized as the normal payment no longer meet collection requirements, for example after a chain rollback or confirmation downgrade

The first successfully recognized normal payment source is fixed. If it becomes invalid, other receipts cannot replace it. When the original payment regains the selected confirmation requirement, the shortfall exception can clear. If both a shortfall and extra receipts exist, paidPartial takes precedence.

For a successful session, paidOver can clear once all extra funds have been successfully refunded. For a failed session, all received funds must be successfully refunded. Pending refunds reserve refundable capacity and do not clear an overpayment early. Ordinary after-sales refunds reduce the normal funds that must be retained and do not themselves cause paidPartial.

The notification contract uses checkout.exception_updated when an exception appears, changes, clears, or its underlying funds change without changing exception type. Merchant delivery remains pending. Clearing an exception does not change the primary status or mean that order or after-sales work has been completed.

url and return_url​

url provides a hosted checkout entry point, not a QR code. After success or failure, the original page displays the result. Funds exceptions show an appropriate message without inviting further payment.

return_url is only the destination of the “Return to merchant” button, with no automatic redirect. Returning changes no payment state. Verify outcomes using server-side retrieval or available Webhooks; a return page is not proof of payment.

Object example​

{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"transaction_speed": "low",
"status": "open",
"failure_reason": null,
"exception_status": null,
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"url": "https://pay.example.com/c/checkout_example",
"return_url": "https://merchant.example.com/orders/ORDER_001",
"expires_at": "2026-10-28T08:30:00Z",
"created_at": "2026-10-28T08:00:00Z",
"updated_at": "2026-10-28T08:00:00Z"
}

Create a Checkout​

POST /v1/checkouts

Creates a collection session and returns a Checkout in open state. Show its url to the payer to begin. After the payer selects a network, hosted checkout prepares payment information without another merchant confirmation call.

Attributes​

AttributeLocationTypeRequiredDescription
Idempotency-KeyheaderstringYesUnique key for this operation; retain it for retries
amountbodystringYesAmount to collect
currencybodystringYesCollection currency: usdc, usdt
transaction_speedbodystringNohigh, medium, low; default low
expires_atbodystringNoMust be later than the platform's session-creation time; default 30 minutes after successful creation
order_idbodystringNoMerchant order reference; uniqueness is not required and one order may have multiple Checkouts
descriptionbodystringNoCollection description shown to the payer
metadatabodyobjectNoMerchant-defined information, subject to Checkout Object limits
return_urlbodystringNoDestination of the hosted checkout's “Return to merchant” button

Checkouts for the same order remain independent. Save the order/Checkout association and prevent duplicate fulfillment at the order level.

Request example​

POST /v1/checkouts
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"amount": "10",
"currency": "usdc",
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"return_url": "https://merchant.example.com/orders/ORDER_001"
}

Response example​

200 OK, returning the complete Checkout object.

{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"transaction_speed": "low",
"status": "open",
"failure_reason": null,
"exception_status": null,
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"url": "https://pay.example.com/c/checkout_example",
"return_url": "https://merchant.example.com/orders/ORDER_001",
"expires_at": "2026-10-28T08:30:00Z",
"created_at": "2026-10-28T08:00:00Z",
"updated_at": "2026-10-28T08:00:00Z"
}

Retrieve a Checkout​

GET /v1/checkouts/{id}

Retrieves current session status and funds exceptions for result polling, page recovery, or rechecking a Webhook. Does not return payment details.

Attributes​

AttributeLocationTypeRequiredDescription
idpathstringYesUnique Checkout identifier

Request example​

GET /v1/checkouts/checkout_example
Authorization: Bearer inv_test_...

Response example​

200 OK, returning the complete Checkout object.

{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"transaction_speed": "low",
"status": "succeeded",
"failure_reason": null,
"exception_status": null,
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"url": "https://pay.example.com/c/checkout_example",
"return_url": "https://merchant.example.com/orders/ORDER_001",
"expires_at": "2026-10-28T08:30:00Z",
"created_at": "2026-10-28T08:00:00Z",
"updated_at": "2026-10-28T08:02:00Z"
}

List Checkouts​

GET /v1/checkouts

Lists the current merchant's sessions in descending creation-time order, then descending ID for equal creation times. Multiple filters apply together.

Attributes​

AttributeLocationTypeRequiredDescription
order_idquerystringNoExact merchant order reference; may return multiple Checkouts
statusquerystringNoopen, processing, succeeded, failed
has_exceptionquerybooleanNotrue selects sessions with funds exceptions, false those without; omitted means either
created_fromquerystringNoInclusive creation-time lower bound
created_toquerystringNoExclusive creation-time upper bound
page_sizequeryintegerNoItems per page; default 20, range 1–100
page_tokenquerystringNoPrevious page's next_page_token; omit on the first page

Request example​

GET /v1/checkouts?order_id=ORDER_001&status=succeeded&page_size=20
Authorization: Bearer inv_test_...

Response example​

200 OK. Each item in data is a complete Checkout without payment details.

{
"data": [
{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"transaction_speed": "low",
"status": "succeeded",
"failure_reason": null,
"exception_status": null,
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"url": "https://pay.example.com/c/checkout_example",
"return_url": "https://merchant.example.com/orders/ORDER_001",
"expires_at": "2026-10-28T08:30:00Z",
"created_at": "2026-10-28T08:00:00Z",
"updated_at": "2026-10-28T08:02:00Z"
}
],
"next_page_token": ""
}

Close a Checkout​

POST /v1/checkouts/{id}/close

Only the merchant server can explicitly close a session. Send {} as the body.

  • open, processing: changes to failed with failure_reason=closed.
  • Already failed: returns the current object without changing the original failure reason.
  • Already succeeded: rejects closure with 400 checkout_invalid_state.

Later receipts remain recognizable after closure but become funds exceptions. They neither reopen payment nor make the session successful.

Attributes​

AttributeLocationTypeRequiredDescription
Idempotency-KeyheaderstringYesUnique key for this operation; retain it for retries
idpathstringYesUnique Checkout identifier

Request example​

POST /v1/checkouts/checkout_example/close
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: ec3a7e90-673e-41a1-94d0-6724fba6a339
{}

Response example​

200 OK, returning the complete Checkout object.

{
"id": "checkout_example",
"amount": "10",
"currency": "usdc",
"transaction_speed": "low",
"status": "failed",
"failure_reason": "closed",
"exception_status": null,
"order_id": "ORDER_001",
"description": "Order payment",
"metadata": {},
"url": "https://pay.example.com/c/checkout_example",
"return_url": "https://merchant.example.com/orders/ORDER_001",
"expires_at": "2026-10-28T08:30:00Z",
"created_at": "2026-10-28T08:00:00Z",
"updated_at": "2026-10-28T08:05:00Z"
}

List payment details​

Pending: payment-item retrieval is awaiting availability confirmation. Do not depend on it until availability is confirmed; see API availability.

GET /v1/checkouts/{id}/payments

Returns payment items with detected receipts, excluding attempts with no payment. Fields are defined under Payment details.

Repeated receipts for the same payment item update its accumulated amount; different items appear separately. Historical payments and later receipts remain queryable after success or failure. Details sort by descending creation time, then descending attempt_id when creation times match.

Receipts without final confirmation do not count toward amount_received or refundable funds. A detected payment that has not finalized can therefore show "0". The platform revalidates refundable capacity when creating a refund.

Attributes​

AttributeLocationTypeRequiredDescription
idpathstringYesUnique Checkout identifier
page_sizequeryintegerNoItems per page; default 20, range 1–100
page_tokenquerystringNoPrevious page's next_page_token; omit on the first page

Request example​

GET /v1/checkouts/checkout_example/payments?page_size=20
Authorization: Bearer inv_test_...

Response example​

Contract example: 200 OK, returning a payment-details list. Select an attempt_id, then specify the amount through Create a refund.

{
"data": [
{
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"amount_received": "10",
"amount_refunded": "0",
"amount_refundable": "10",
"currency": "usdc",
"chain": 56
}
],
"next_page_token": ""
}

With no detected receipt, the response is {"data":[],"next_page_token":""}.

Checkout Webhook events​

Pending: merchant Checkout event delivery is awaiting availability confirmation; use Checkout retrieval for current results until delivery is available.

The platform's notification contract sends lightweight events to configured Webhook endpoints. related_object.type is checkout; related_object.id is the session identifier. Retrieve its current status using Retrieve a Checkout.

typeTrigger
checkout.succeededSession first becomes succeeded
checkout.failedSession first becomes failed
checkout.exception_updatedA funds exception appears, changes type, clears, or its underlying funds change

Each Checkout produces only one success or failure event. Later funds changes do not produce another terminal event. Network switches, payment-attempt creation, and confirmation progress do not send merchant events.

checkout.exception_updated can occur without a type change: additional exceptional receipts, successful refunds reducing exceptional funds still to return, and invalidation or recovery of payment funds all qualify. Pending refunds only reserve capacity and do not count as returned exceptional funds. Reprocessing the same funds facts does not produce another event.

Event example​

{
"id": "evt_example",
"type": "checkout.succeeded",
"related_object": {
"id": "checkout_example",
"type": "checkout"
},
"created_at": "2026-10-28T08:02:00Z"
}

Notifications can arrive more than once or out of order. Deduplicate by event id, retrieve the Checkout's current state, and prevent repeated fulfillment by order. Even a success event requires inspecting current exception_status; do not fulfill from event type alone.

See Webhooks for signatures, reception, and delivery rules.

Error codes​

error.codeHTTP statusMeaningOperations
checkout_not_found404Session missing or inaccessibleRetrieve, close, list payment details
checkout_invalid_state400Operation not allowed in current state, such as closing a successful sessionClose