Create a Checkout
Merchant route confirmed. Check applicability.
Object and complete fields · Authentication, amounts and errors · Integration guide
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"
}