Checkouts

Checkout endpoints create a payment attempt and return a checkout_id. Verification endpoints accept that same checkout_id after the payment provider completes the checkout.

Checkout fields

Field	Meaning
`checkout_id`	Public checkout reference returned by the API.
`redirect_url`	Hosted checkout URL when the gateway uses redirects.
`embedded_checkout_token`	Short-lived embedded checkout token. Treat it as sensitive and only pass it to the payment collection component.
`success_url`	URL the user returns to after successful checkout. Optional, and accepted on subscription and plan checkouts only.
`cancel_url`	URL the user returns to after canceling checkout. Optional, and accepted on subscription and plan checkouts only.

Add-on checkouts and copyright wallet top-ups do not take return URLs. Add-on checkout takes an optional return_to path instead; copyright top-ups take neither. Both are resolved with the returned checkout reference and its status endpoint.

Verification pattern

curl --request POST 'https://enterprise.spacemedia.uk/api/v1/order/checkout/verify' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --header 'Content-Type: application/json' \
  --data '{"checkout_id":"39b189c1-8f8e-4df2-8632-176f87f791a1"}'

Checkout matrix

Flow	Create endpoint	Verify or status endpoint	Store	Recovery
Release checkout, Stripe	`POST /api/v1/order/{release_id}/checkout/stripe`	`POST /api/v1/order/checkout/verify`	`checkout_id`, `release_id`	Verify after provider return. If timeout happens, check checkout state before creating another checkout.
Release checkout, PayPal	`POST /api/v1/order/{release_id}/checkout/paypal`	`POST /api/v1/order/checkout/verify`	`checkout_id`, `release_id`	Verify after provider return and keep the original release reference.
Release checkout, Airwallex	`POST /api/v1/order/{release_id}/checkout/airwallex`	`POST /api/v1/order/checkout/verify`	`checkout_id`, `release_id`	If embedded checkout data expires, create a new checkout only after the first attempt is known to be unusable.
Credits checkout	`POST /api/v1/order/credits/checkout`	`POST /api/v1/order/credits/checkout/verify`	`checkout_id`	Verify before increasing local credit balances or unlocking credit-backed actions.
Subscription checkout	`POST /api/v1/subscriptions/subscribe/{package_id}/checkout/stripe`, `/paypal`, or `/airwallex`	`POST /api/v1/subscriptions/subscribe/{package_id}/payment-verify`	`checkout_id`, `package_id`	Verify before marking a package active in a customer system.
Add-on checkout	`POST /api/v1/addons/{addon_slug}/checkout`	`GET /api/v1/addons/checkout/{checkout_id}/status`	`checkout_id`, add-on slug	Read add-on status after checkout before calling install or activate again.
Copyright wallet top-up	`POST /api/v1/copyright/wallet/top-up`	`GET /api/v1/copyright/wallet/top-up/{checkout_id}/status`	`checkout_id`, wallet reference when returned	Verify before updating customer-side wallet balance.
Payment method setup	Payment method setup endpoints under `/api/v1/billing/payment-methods/*`	Matching setup verify endpoint when provided	`payment_method_id` after success	Do not show a payment method as usable until verification succeeds.

Status handling

Status family	Meaning	Client action
Pending	Checkout was created but final provider outcome is not known.	Show pending state and verify again with backoff.
Completed	Payment or setup completed.	Read related billing, subscription, wallet, or add-on state before unlocking access.
Failed	Provider or gateway rejected the attempt.	Show a recovery action and allow a new checkout when the previous attempt is terminal.
Cancelled	User cancelled the checkout.	Return the user to the cart or billing action.
Expired	Checkout can no longer be completed.	Create a new checkout only if the customer still wants to proceed.

Invoice downloads

Billing history items include an invoice_pdf_url when a PDF is available. The URL uses the same public checkout_id style as checkout creation and verification:

curl --request GET 'https://enterprise.spacemedia.uk/api/v1/billing/invoices/39b189c1-8f8e-4df2-8632-176f87f791a1/pdf' \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
  --output night-shift-records-invoice.pdf

Safe client behavior

Store checkout_id with the local cart, release, subscription, or wallet top-up workflow.
Verify once the user returns from the provider or the embedded payment component reports completion.
Show a retry option for recoverable gateway errors.
Do not automatically create another checkout after a timeout. Read the current state first.
Do not expose API keys, webhook secrets, or live provider references in client-side logs.

Common questions

Can I trust the redirect the customer comes back on? No. Query parameters on a return URL are navigation data. Always verify server side before granting anything.

My checkout timed out. Should I create another? Check whether a checkout_id was returned and whether the related order state changed first. A second checkout can mean a second charge.

How long should I keep polling a pending checkout? Until it reaches a terminal state: complete, failed, cancelled, or expired. Poll after the customer returns, then back off.

What should I never log? Short-lived payment tokens such as embedded_checkout_token. Keep the checkout_id as your durable reference instead.