Checkout API: TEST & LIVE
The API key determines environment. TEST and LIVE checkout interfaces are intentionally different in the current implementation.
LIVE checkout-session interface
Section titled “LIVE checkout-session interface”POST /public/catalog/stores/:storeId/checkout-sessions
Use an authorized LIVE key only after separate activation. Send lineItems with product IDs, optional variant IDs and quantity; optional fields include checkoutType (native or stripe_hosted), checkoutLanguage (mk or en), orderRef, customerRef, return/success URLs and expiry.
Use a stable Idempotency-Key for one logical attempt. Header and body idempotency values must agree if both are supplied. Preserve the returned session reference for confirmation. Individual checkout remains one-time digital and buyer-market gated.
For Individual LIVE sales, the hosted checkout and buyer-location/tax checks are mandatory. A general native option in the shared Business contract does not enable a direct Individual card form.
TEST checkout interface
Section titled “TEST checkout interface”POST /public/catalog/stores/:storeId/test-checkout
Use a TEST key and a body containing productId. Individual requests also require testSaleMarket (US, CA or AU). These are TEST sale contexts, not confirmed LIVE market permissions. The response returns data.environment: TEST and a checkout URL; keep its token private.
TEST keys support catalog reads, plus this specific TEST checkout creation path. The general checkout-session POST and payment-confirmation GET are not supported with TEST keys in the current handler. Do not promise identical API coverage across environments or change headers to bypass it.
Integration sequence
Section titled “Integration sequence”- Read the store catalog server-side with the matching key.
- Choose the correct checkout interface for the environment.
- Redirect the buyer to the returned checkout URL.
- For LIVE sessions, confirm server-side before fulfillment. For isolated TEST flow, inspect the supported TEST result and TEST status UI; never infer LIVE readiness.
Related guides
Section titled “Related guides”Authentication · Payment confirmation · Actual TEST interface