Create a Hosted Checkout

Hosted Checkout accepts the minimum stable Payment facts, creates a linked Payment intent in requires_payment_method, and returns a signed payer URL. It does not contact a Provider during creation.

POST /checkouts

Minimum request

curl -s -X POST "$API_BASE/checkouts" \
  -u "$API_PUBLIC_KEY:$API_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000",
    "currency": "MYR",
    "country": "MY",
    "merchant_reference": "order_12345"
  }'

The only required JSON fields are amount, currency, country, and merchant_reference. customer, return_url, and metadata are optional. You may also provide the Provider-neutral payment_method and its flat payment_method_options to freeze the method before the payer opens the link. payment_method_options requires payment_method; Checkout validates the selected route and payer data before execution. provider and checkout_mode are not part of this contract.

Response

{
  "object": "checkout",
  "id": "hchk_01K2VK4V0C7Y6HG4H3ED4HPR2F",
  "status": "open",
  "amount": "10000",
  "currency": "MYR",
  "country": "MY",
  "merchant_reference": "order_12345",
  "payment_intent_id": "dord_01K2VK4V0C7Y6HG4H3ED4HPR2F",
  "payment_status": "requires_payment_method",
  "failure_code": null,
  "failure_message": null,
  "checkout_url": "https://checkout.example/pay/signed-token",
  "expires_at": "2026-08-16T10:15:00.000Z",
  "created_at": "2026-08-16T10:00:00.000Z",
  "processing_stale_at": null,
  "provider_status": null,
  "updated_at": "2026-08-16T10:00:00.000Z"
}

Redirect the payer to checkout_url. The Checkout identity and expiry are separate from its linked Payment lifecycle. Closing or expiring the payer interaction does not turn an uncertain or already processing Provider operation into a failure.