Checkouts
Check API availability and confirm access in your target environment before integrating.
| Operation | Method and route | Availability |
|---|---|---|
| Create a Checkout | POST /v1/checkouts | Merchant route confirmed |
| Retrieve a Checkout | GET /v1/checkouts/{id} | Merchant route confirmed |
| List Checkouts | GET /v1/checkouts | Merchant route confirmed |
| Close a Checkout | POST /v1/checkouts/{id}/close | Merchant route confirmed |
| List payment details | GET /v1/checkouts/{id}/payments | Availability 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
| Attribute | Type | Description |
|---|---|---|
id | string | Unique Checkout identifier |
amount | string | Amount to collect |
currency | string | Collection currency: usdc, usdt |
transaction_speed | string | Confirmation speed: high, medium, low; default low; see below |
status | string | Primary session state: open, processing, succeeded, failed; see below |
failure_reason | string / null | Reason the session ended: expired or closed; populated only for failed, otherwise null |
exception_status | string / null | Current funds exception: paidOver or paidPartial; null when none exists |
order_id | string / null | Merchant order reference; uniqueness is not required; null when unset |
description | string / null | Collection description shown to the payer; null when unset |
metadata | object | Merchant-defined string key/value pairs, or {} when empty; at most 50 pairs, keys up to 40 characters, values up to 500 characters |
url | string | Hosted checkout URL; remains accessible to view results after the session ends |
return_url | string / null | Destination of the hosted checkout's “Return to merchant” button; null when unset, in which case no button is shown |
expires_at | string | Expiry fixed at creation; defaults to 30 minutes after successful creation |
created_at | string | Creation time |
updated_at | string | Last 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
| Value | Meaning |
|---|---|
open | Waiting for payment; the payer can select or switch networks before an on-chain payment is detected |
processing | An on-chain payment has been detected and is awaiting the selected confirmation requirement; hosted checkout displays progress rather than inviting another payment |
succeeded | Before expiry or merchant closure, the platform confirmed that payment reached the selected transaction_speed; inspect exception_status and apply exception/order rules before fulfillment |
failed | Confirmation 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
| Value | Meaning |
|---|---|
expired | The selected confirmation requirement was not met at expiry |
closed | The 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.
| Value | Meaning |
|---|---|
high | Fast: the payment transaction executed successfully and was included in a block |
medium | Standard: the payment's block reached the native safe confirmation head (safe) |
low | Conservative: 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.
| Value | Meaning |
|---|---|
null | No current funds exception, including before any payment |
paidOver | Additional received funds have not been fully refunded, such as duplicate payments or receipts after session failure |
paidPartial | Funds 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
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Unique key for this operation; retain it for retries |
amount | body | string | Yes | Amount to collect |
currency | body | string | Yes | Collection currency: usdc, usdt |
transaction_speed | body | string | No | high, medium, low; default low |
expires_at | body | string | No | Must be later than the platform's session-creation time; default 30 minutes after successful creation |
order_id | body | string | No | Merchant order reference; uniqueness is not required and one order may have multiple Checkouts |
description | body | string | No | Collection description shown to the payer |
metadata | body | object | No | Merchant-defined information, subject to Checkout Object limits |
return_url | body | string | No | Destination 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
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique 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
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
order_id | query | string | No | Exact merchant order reference; may return multiple Checkouts |
status | query | string | No | open, processing, succeeded, failed |
has_exception | query | boolean | No | true selects sessions with funds exceptions, false those without; omitted means either |
created_from | query | string | No | Inclusive creation-time lower bound |
created_to | query | string | No | Exclusive creation-time upper bound |
page_size | query | integer | No | Items per page; default 20, range 1–100 |
page_token | query | string | No | Previous 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 tofailedwithfailure_reason=closed.- Already
failed: returns the current object without changing the original failure reason. - Already
succeeded: rejects closure with400 checkout_invalid_state.
Later receipts remain recognizable after closure but become funds exceptions. They neither reopen payment nor make the session successful.
Attributes
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Unique key for this operation; retain it for retries |
id | path | string | Yes | Unique 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
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique Checkout identifier |
page_size | query | integer | No | Items per page; default 20, range 1–100 |
page_token | query | string | No | Previous 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.
type | Trigger |
|---|---|
checkout.succeeded | Session first becomes succeeded |
checkout.failed | Session first becomes failed |
checkout.exception_updated | A 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.code | HTTP status | Meaning | Operations |
|---|---|---|---|
checkout_not_found | 404 | Session missing or inaccessible | Retrieve, close, list payment details |
checkout_invalid_state | 400 | Operation not allowed in current state, such as closing a successful session | Close |