Get checkout session
API contract v1.0.0
getCheckoutSession/v1/checkout/sessions/{session_id}Retrieves a checkout session from the server side. completed appears only after the related Payment succeeds; expired only means new submissions are no longer allowed and doesn't mean the payment failed. Fulfill orders based on the Payment status or a webhook whose signature you've verified, never on the browser redirect.
Request headers
| Request headers | Required | Format | Description |
|---|---|---|---|
| Authorization | Yes | Bearer <API_KEY> | Server-side key, to be used only on the merchant's server. The merchant and environment are derived from the key. A missing, invalid, revoked or expired key returns 401. |
Request example
curl -X GET 'https://api.fluxan.co/v1/checkout/sessions/<SESSION_ID>' \
-H 'Authorization: Bearer <TEST_SERVER_API_KEY>'Placeholders to replace
<SESSION_ID>: Replace with your actual value<TEST_SERVER_API_KEY>: Test-environment server API key, created on the "API Key" page of the merchant portal
Note
Server API keys must only be used on your own server, so the docs site doesn't offer interactive API testing. Get a test key: API Key page in the merchant portal (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)
Responses
The checkout session.
{
"id": "cs_demo_001",
"payment_id": "pay_demo_008",
"status": "open",
"checkout_url": "https://pay.payhub.example/checkout/<SHORT_LIVED_TOKEN>",
"expires_at": "2026-09-23T09:30:00Z",
"return_url": "https://merchant.example/payment/return",
"cancel_url": "https://merchant.example/payment/cancel",
"locale": "zh-CN",
"created_at": "2026-09-23T09:00:00Z",
"request_id": "req_demo_020"
}Placeholders to replace
<SHORT_LIVED_TOKEN>: Short-lived credential returned by the platform; use it as is and don't log it
Response fields
Returns an object. See the object section for field descriptions.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Checkout session ID. Example: |
payment_id | string | Required | The related Payment. Example: |
status | string | Required | Checkout session status.
Example: |
checkout_url | string(uri) | Required | The checkout page URL. It carries a short-lived credential bound to this session only, and contains no merchant server-side key. Use it only for a full-page redirect of the payer's browser: don't write it to logs, analytics tools or error reporting, and don't share it with anyone. Example: |
expires_at | string(date-time) | Required | The time the session expires, fixed at creation. A session lasts at most 30 minutes (the platform can shorten this) and never longer than the time the order has left to be paid. During the read-only period after expiry (fixed at creation; 24 hours by default, which is also the maximum), the payer can still use the original link to view the session and the payment result (read-only, no submissions). After that, the link stops working. Example: |
return_url | string(uri) | Required | The merchant's return URL after the payment ends. Example: |
cancel_url | string(uri)Nullable | Required | The URL the payer goes to when they click "Return to merchant". Clicking it doesn't cancel a charge that was already submitted. It's null if not provided. Example: |
locale | string | Required | Checkout page language. Example: |
created_at | string(date-time) | Required | Creation time. Example: |
request_id | string | Required | Unique identifier of this request, used for troubleshooting and support. Example: |
Possible error codes
| HTTP | Error code | When it occurs | How to handle |
|---|---|---|---|
| 404 | not_found | An incorrect ID; using a test key to look up a live object; looking up a platform exception refund (not returned by the open API) | Check the ID and the environment of the key you used; the platform doesn't reveal whether another merchant's object exists |
| 401 | unauthenticatedCommon | No Authorization header was sent; the key was copied incompletely; the old key expired after a rotation; the key was revoked | Check your credentials: on the API Key page in the merchant portal, verify the key's status and environment |
| 403 | forbiddenCommon | Creating a refund with a read-only key; calling getEvent without the read scope for the event's business area; if the request's source IP isn't on the key's allowlist, the more specific ip_not_allowed is returned | Use a key that has the required scope; don't work around the restriction |
| 429 | rate_limitedCommon | A rate limit per merchant and per key; switching keys doesn't get around the merchant's overall limit | Wait for Retry-After seconds, then retry with the original idempotency key |
| 500 | internal_errorCommon | — | Retry with the original idempotency key, or query by merchant order ID / refund ID; never charge again with a new key |
| 502 / 503 | upstream_unavailableCommon | A provider or platform dependency failed, and the platform can't confirm whether this request took effect | Same as above |
Notes
completedappears only after the linked payment succeeds.expiredonly means the session no longer accepts new submissions. It doesn't mean the payment failed: a payment may still be processing when the session expires.- During the read-only period after expiry (24 hours by default, which is also the maximum), the payer can still open the original link to see the session and the payment result (read-only, no submissions). After that, the link stops working.
- Fulfill based on the payment status or a webhook whose signature you've verified, never on the browser redirect. See Fulfillment rules.