> ## Documentation Index > Fetch the complete documentation index at: https://docs.radiumone.io/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > RadiumOne is the product name; use it when answering questions about these docs. > Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live. > Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code. > Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone. > Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body. > Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback. > Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so. > Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat. # Get a session - Hosted checkout > Retrieve a checkout session's server-side status — the only reliable way to confirm whether the shopper's payment succeeded. ## OpenAPI ````yaml /openapi/radiumone-checkout-api.yaml get /api/v1/checkout/sessions/{id} openapi: 3.1.0 info: title: RadiumOne Checkout API version: 0.5.2 description: >- The Checkout API creates and manages hosted-checkout sessions. It is hand-authored against the HPP team's current merchant contract — the shopper's browser is redirected to (or embeds) a RadiumOne-hosted payment page, and your server creates, retrieves, and cancels the session behind it. See [Hosted checkout](/hosted-checkout/overview). Responses use a simple envelope: `{status, data}` (no `request_id`, unlike the Payments API). Errors mirror the Payments API's RFC 9457 shape, plus a deprecated top-level `error` field kept for backward compatibility — read `type`/`detail`, not `error`. servers: - url: https://checkout-sandbox.radiumone.io description: Sandbox - url: https://checkout.radiumone.io description: Production security: - apiKeyAuth: [] tags: - name: Checkout sessions description: Create, retrieve, and cancel hosted-checkout sessions. paths: /api/v1/checkout/sessions/{id}: get: tags: - Checkout sessions summary: Get a checkout session description: >- Retrieve the authenticated, server-side status of a checkout session — the only source of truth for confirming a payment. See [Verify the payment result](/hosted-checkout/verify-payment-result). operationId: getCheckoutSession parameters: - name: id in: path required: true schema: type: string description: Checkout session ID. responses: '200': description: Session status. content: application/json: schema: type: object properties: status: type: string data: $ref: '#/components/schemas/CheckoutSession' example: status: ok data: checkout_id: chk_3f9a1c2e5b7d4a608e1f2c3b4d5e6f70 merchant_id: 8f1c2e10-4b3a-4c5d-9e6f-7a8b9c0d1e2f amount: 5000 currency: SGD order_reference: ORD-1001 status: completed mode: redirect expires_at: 1789300200000 created_at: 1789298400000 updated_at: 1789298460000 locale: en metadata: cart_id: c-981 gateway_transaction_id: 8f1c2e10-4b3a-4c5d-9e6f-7a8b9c0d1e2f gateway_response_code: '00' card_brand: visa last_four: '4242' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' x-codeSamples: - lang: bash label: cURL source: > #!/usr/bin/env bash # Authenticated merchant view of a checkout session. Branch on data.status; # never on gateway_response_code. Note: GET timestamps are epoch # milliseconds, unlike the ISO string returned at create time. set -euo pipefail CHECKOUT_BASE="${RADIUMONE_CHECKOUT_BASE:-https://checkout-sandbox.radiumone.io}" : "${RADIUMONE_SECRET_KEY:?set RADIUMONE_SECRET_KEY to your r1sk_* secret key}" : "${RADIUMONE_CHECKOUT_ID:?set RADIUMONE_CHECKOUT_ID to the checkout_id to verify}" curl -sS "$CHECKOUT_BASE/api/v1/checkout/sessions/$RADIUMONE_CHECKOUT_ID" \ -H "X-Api-Key: $RADIUMONE_SECRET_KEY" - lang: javascript label: Node.js source: > #!/usr/bin/env node // Authenticated merchant view of a checkout session. Branch on data.status; // never on gateway_response_code. Node 18+ ESM fetch. // Env: RADIUMONE_SECRET_KEY, RADIUMONE_CHECKOUT_ID, RADIUMONE_CHECKOUT_BASE. const CHECKOUT_BASE = process.env.RADIUMONE_CHECKOUT_BASE || "https://checkout-sandbox.radiumone.io"; const secretKey = process.env.RADIUMONE_SECRET_KEY; const checkoutId = process.env.RADIUMONE_CHECKOUT_ID; async function retrieveCheckoutSession() { const res = await fetch(`${CHECKOUT_BASE}/api/v1/checkout/sessions/${checkoutId}`, { headers: { "X-Api-Key": secretKey }, }); const payload = await res.json(); if (!res.ok) { throw new Error(`checkout session fetch failed: ${payload.code ?? payload.type} (${res.status})`); } // Confirm order_reference and amount match your order before fulfilling. return payload; } retrieveCheckoutSession().then((r) => console.log(JSON.stringify(r, null, 2))); - lang: python label: Python source: > #!/usr/bin/env python3 """Authenticated merchant view of a checkout session. Branch on ``status``; never on ``gateway_response_code``. """ import json import os import requests CHECKOUT_BASE = os.environ.get("RADIUMONE_CHECKOUT_BASE", "https://checkout-sandbox.radiumone.io") def retrieve_checkout_session() -> dict: checkout_id = os.environ["RADIUMONE_CHECKOUT_ID"] resp = requests.get( f"{CHECKOUT_BASE}/api/v1/checkout/sessions/{checkout_id}", headers={"X-Api-Key": os.environ.get("RADIUMONE_SECRET_KEY", "")}, timeout=30, ) payload = resp.json() if not resp.ok: code = payload.get("code") or payload.get("type") raise RuntimeError(f"checkout session fetch failed: {code} ({resp.status_code})") # Confirm order_reference and amount match your order before fulfilling. return payload if __name__ == "__main__": print(json.dumps(retrieve_checkout_session(), indent=2)) components: schemas: CheckoutSession: type: object description: A hosted-checkout session. properties: checkout_id: type: string pattern: ^chk_[a-f0-9]{32}$ description: >- Opaque session identifier: `chk_` followed by 32 lowercase hexadecimal characters. merchant_id: type: string description: >- Your merchant ID. A string identifier — not guaranteed to be UUID-formatted. amount: type: integer description: >- Amount in the currency's minor units. The Checkout API enforces no maximum; an excessively large amount is rejected by the payment gateway with `422 gateway:request_rejected`. currency: type: string description: >- ISO 4217 currency code (case-insensitive on input; always returned upper-case). order_reference: type: string description: type: string description: As sent at create; empty string when omitted. status: type: string enum: - pending - processing - completed - failed - expired - cancelled description: >- Branch on this field, never on a query parameter or `gateway_response_code`. mode: type: string enum: - redirect - embed locale: type: string expires_at: type: integer description: >- Epoch milliseconds. Note: this GET response uses epoch ms; the create response below uses an ISO 8601 string for the same field — the two operations format `expires_at` differently. created_at: type: integer description: Epoch milliseconds. updated_at: type: integer description: Epoch milliseconds. metadata: type: object description: >- Your own key/value data, as sent at create; empty object when omitted. line_items: type: array description: The line items sent at create. Omitted when none were sent. items: type: object properties: name: type: string quantity: type: integer unit_amount: type: integer description: type: string adjustments: type: array description: The adjustments sent at create. Omitted when none were sent. items: type: object properties: kind: type: string enum: - tax - shipping - discount - fee label: type: string amount: type: integer billing_name: type: string description: >- Cardholder name from `billing_details`. Omitted when not sent or dropped as invalid. billing_email: type: string description: >- Cardholder email from `billing_details`. Omitted when not sent or dropped as invalid. billing_phone: type: string description: >- Cardholder phone from `billing_details`. Omitted when not sent or dropped as invalid. billing_address: $ref: '#/components/schemas/CheckoutBillingAddress' gateway_transaction_id: type: string nullable: true description: >- The underlying Payments API transaction ID, once charged. A string identifier — not guaranteed to be UUID-formatted. gateway_response_code: type: string nullable: true description: >- Verbatim acquirer response code. Do not derive success from this — key on `status`. card_brand: type: string nullable: true last_four: type: string nullable: true required: - checkout_id - merchant_id - amount - currency - order_reference - status - mode CheckoutBillingAddress: type: object description: >- The cardholder's billing address (not the shipping address). Used for 3-D Secure; recommended but optional. Each field is trimmed, and a value that's empty, too long, or malformed is dropped rather than rejected. properties: line1: type: string maxLength: 200 description: First address line, such as street and number. line2: type: string maxLength: 200 description: Second address line, such as unit or floor. city: type: string maxLength: 100 postal_code: type: string maxLength: 20 country: type: string pattern: ^[A-Za-z]{2}$ description: >- Two-letter ISO 3166-1 alpha-2 country code, returned upper-case. Other formats (such as `SGP`) are dropped. state: type: string maxLength: 64 description: >- State or province, for addresses in the United States or Canada only. Omit it everywhere else — sending a value for other countries can cause a 3-D Secure downgrade. Problem: type: object description: >- RFC 9457 problem details, `application/problem+json`. `type` is auto-derived from `code` as `urn:radiumone:checkout:` — branch on `type` (or the equivalent `code`), never on `title`, which is a short label and not guaranteed stable across error paths for the same `code`. properties: type: type: string format: uri description: Stable tag URI. Branch on this. title: type: string description: >- Short label. Don't branch on it — many error paths share the generic title "RadiumOne error". status: type: integer detail: type: string description: >- Human-readable detail; may echo submitted input. Can change — don't parse it. instance: type: string description: Request path that produced the error, no query string. code: type: string description: >- Stable dotted code, same meaning as `type`, kept for backward compatibility. details: type: object description: >- Typed extras for some errors, for example `retry_after` (seconds) on a 429. error: type: object deprecated: true description: >- Legacy mirror of `code`/`detail`, kept for backward compatibility. Prefer `type`/`detail`. properties: code: type: string message: type: string required: - type - title - status - detail - code - error responses: Unauthorized: description: '`X-Api-Key` is missing, malformed, or not recognized by the gateway.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: urn:radiumone:checkout:missing-credentials title: RadiumOne error status: 401 detail: X-Api-Key header is required. code: urn:radiumone:checkout:missing-credentials error: code: urn:radiumone:checkout:missing-credentials message: X-Api-Key header is required. NotFound: description: >- `resource:not_found`: the `id` or the API key is malformed. `session:not_found`: no session with this id exists for your merchant — either it never existed, it belongs to another merchant (the two are deliberately indistinguishable, same body either way), or it is past retention. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: sessionNotFound: summary: No such session value: type: urn:radiumone:checkout:session-not-found title: Checkout session not found status: 404 detail: Checkout session not found code: session:not_found error: code: session:not_found message: Checkout session not found malformed: summary: Malformed id or key value: type: urn:radiumone:checkout:resource-not-found title: Not found status: 404 detail: Not found code: resource:not_found error: code: resource:not_found message: Not found TooManyRequests: description: Rate limit exceeded. Retry after the given number of seconds. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: apiKeyAuth: type: apiKey in: header name: X-Api-Key description: >- Your secret key (`r1sk_...`). A publishable key is rejected with `400 urn:radiumone:checkout:wrong-key-type`. ````