> ## 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. # Verify session token - Payments API > Confirm that a card token belongs to a tokenization session your merchant account owns before you charge it. ## OpenAPI ````yaml /openapi/radiumone-payments-api.yaml post /v1/sessions/{session_id}/verify openapi: 3.1.0 info: description: | The Payments API lets your server create tokenization sessions, charge and manage payments, check loyalty balances, and manage your hosted-checkout branding and redirect secret. Generated for merchant integrators — internal, admin, and service-to-service surfaces are excluded. All responses share an envelope: `{status, data, request_id}`. The envelope's `request_id` is an HTTP correlation ID — it echoes your `X-Request-Id` request header (letters, digits, hyphens, max 36 characters) or one is generated for you. It is **not** the idempotency key you send in a transaction request body (also confusingly named `request_id` there) — the two are unrelated; see [Request conventions](/get-started/api-basics/request-conventions). Errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` bodies — see [Authentication](/get-started/api-basics/authentication) and [Request conventions](/get-started/api-basics/request-conventions) for the shared error shape, and [Problem format and retries](/payments-api/errors/problem-format-and-retries) for the response shape, status guide, and retry rules. summary: Transaction orchestration and processor aggregation for RadiumOne. title: RadiumOne Payment Gateway version: 1.3.0 servers: - url: https://api-sandbox.radiumone.io/gateway description: Sandbox - url: https://api.radiumone.io/gateway description: Production security: - bearerAuth: [] tags: - name: Authentication description: Exchange, refresh, and revoke access tokens. - name: Merchant settings description: >- Manage your hosted-checkout redirect secret, checkout configuration, and account config. - name: Payment methods description: Discover which payment methods and brands are available. - name: Sessions description: Tokenization sessions used to collect card data with RadiumOne Elements. - name: Settlement description: Settlement batch status lookup. - name: Payments description: Create and manage card transactions. - name: Rewards description: UOB Rewards loyalty balance inquiry. - name: Refunds description: Return funds to a shopper. - name: Transactions description: Check the live status of a transaction. paths: /v1/sessions/{session_id}/verify: post: tags: - Sessions summary: Verify tokenization session token description: >- Verify that a token is bound to one of your tokenization sessions. Returns 200 when the token matches the session and 422 when it does not. Returns 404 if the session is unknown, 403 if it belongs to a different merchant, and 503 if verification is temporarily unavailable. operationId: verify_session_v1_sessions__session_id__verify_post parameters: - description: Tokenization session identifier. in: path name: session_id required: true schema: description: Tokenization session identifier. maxLength: 64 title: Session Id type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/VerifySessionRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SuccessResponse_VerifySessionResponse_' description: Successful Response '400': description: The request body failed validation. x-docs-interim: true content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': content: application/problem+json: example: detail: Missing or invalid Bearer token. status: 401 title: Authentication Required type: urn:radiumone:gateway:authentication-required schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: Missing or invalid Bearer token. '403': content: application/problem+json: example: detail: Insufficient permissions for this operation. status: 403 title: Permission Denied type: urn:radiumone:gateway:permission-denied schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: Insufficient permissions for this operation. '404': content: application/problem+json: example: detail: The requested resource does not exist. status: 404 title: Not Found type: urn:radiumone:gateway:not-found schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: The requested resource does not exist. '409': content: application/problem+json: example: detail: >- Your merchant account is not yet set up for card tokenization and could not be set up automatically. Retry later; contact support if the problem continues. status: 409 title: Merchant Not Provisioned type: urn:radiumone:gateway:merchant-not-provisioned schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: >- Your merchant account is not yet set up for card tokenization and could not be set up automatically. Retry later; contact support if the problem continues. '429': content: application/problem+json: example: detail: >- Too many bind attempts for this session; the session is temporarily locked. This is a lockout, not a transient error -- do not auto-retry. status: 429 title: Bind Rate Limit type: urn:radiumone:gateway:bind-rate-limit schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: >- Too many bind attempts for this session; the session is temporarily locked. This is a lockout, not a transient error -- do not auto-retry. '500': content: application/problem+json: example: detail: An unexpected error occurred. status: 500 title: Internal Server Error type: urn:radiumone:gateway:internal-server-error schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: An unexpected error occurred. '503': content: application/problem+json: example: detail: >- A downstream dependency is unavailable or did not respond in time. status: 503 title: Service Unavailable type: urn:radiumone:gateway:service-unavailable schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: A downstream dependency is unavailable or did not respond in time. x-codeSamples: - lang: bash label: cURL source: > #!/usr/bin/env bash # Confirm a card token is bound to a session before your server trusts it. set -euo pipefail API_BASE="${RADIUMONE_API_BASE:-https://api-sandbox.radiumone.io/gateway}" : "${RADIUMONE_ACCESS_TOKEN:?set RADIUMONE_ACCESS_TOKEN to a Bearer access token}" : "${RADIUMONE_SESSION_ID:?set RADIUMONE_SESSION_ID to the session to verify}" curl -sS -X POST "$API_BASE/v1/sessions/$RADIUMONE_SESSION_ID/verify" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \ -d @request.json - lang: javascript label: Node.js source: > #!/usr/bin/env node // Confirm a card token is bound to a session. Node 18+ ESM fetch. // Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_SESSION_ID, RADIUMONE_API_BASE. import { readFileSync } from "node:fs"; const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway"; const accessToken = process.env.RADIUMONE_ACCESS_TOKEN; const sessionId = process.env.RADIUMONE_SESSION_ID; const body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url))); async function verifySessionToken() { const res = await fetch(`${API_BASE}/v1/sessions/${sessionId}/verify`, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${accessToken}`, }, body: JSON.stringify(body), }); const payload = await res.json(); if (!res.ok) { // 422 token:verification-failed on a mismatch. throw new Error(`sessions verify failed: ${payload.type ?? payload.code} (${res.status})`); } return payload; } verifySessionToken().then((r) => console.log(JSON.stringify(r, null, 2))); - lang: python label: Python source: > #!/usr/bin/env python3 """Confirm a card token is bound to a session. Python 3.10+, requests.""" import json import os from pathlib import Path import requests API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway") def verify_session_token() -> dict: body = json.loads((Path(__file__).parent / "request.json").read_text()) session_id = os.environ["RADIUMONE_SESSION_ID"] resp = requests.post( f"{API_BASE}/v1/sessions/{session_id}/verify", json=body, headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"}, timeout=30, ) payload = resp.json() if not resp.ok: # 422 token:verification-failed on a mismatch. code = payload.get("type") or payload.get("code") raise RuntimeError(f"sessions verify failed: {code} ({resp.status_code})") return payload if __name__ == "__main__": print(json.dumps(verify_session_token(), indent=2)) components: schemas: VerifySessionRequest: description: Request body for POST /v1/sessions/{id}/verify. properties: token: description: EMV-numeric payment token to verify against the session. maxLength: 64 minLength: 1 title: Token type: string required: - token title: VerifySessionRequest type: object SuccessResponse_VerifySessionResponse_: description: >- Standard success envelope. Every successful response has this shape, with the operation's own payload under `data`. properties: data: anyOf: - $ref: '#/components/schemas/VerifySessionResponse' - type: 'null' description: >- The operation's result. Its shape is documented per operation; omitted on responses that carry no payload. message: anyOf: - type: string - type: 'null' description: >- Optional human-readable note. Omitted from the response when not set, which is the case for every payment operation today. Never parse it. title: Message request_id: anyOf: - type: string - type: 'null' description: >- Correlation ID for this HTTP request, for logs and support. Send your own in the `X-Request-Id` header (letters, digits and hyphens, up to 36 characters -- other characters are stripped) or the gateway generates one. This is NOT the `request_id` idempotency key you send in a transaction body; the two are unrelated. title: Request Id status: default: ok description: >- Always `ok` on a successful (2xx) response. Errors use a different body shape entirely (RFC 9457 problem details), so branch on the HTTP status code, not on this field. title: Status type: string title: SuccessResponse[VerifySessionResponse] type: object Problem: type: object x-docs-interim: true description: >- RFC 9457 problem details. Returned with `Content-Type: application/problem+json`. Interim: not yet a named component in the gateway team's published contract — every response there inlines its own smaller ad-hoc object; this shape reflects what our error pages and error-catalog.json actually document. properties: type: type: string format: uri description: >- A URN identifying the error condition, e.g. `urn:radiumone:gateway:validation-error`. title: type: string description: Short human-readable summary of the error type.: null status: type: integer description: The HTTP status code repeated in the body for convenience.: null detail: type: string description: Human-readable explanation specific to this occurrence. instance: type: string description: The request path that produced this error. request_id: type: string description: >- Correlation ID for this request (see the envelope `request_id` note above). Include it when contacting support. code: type: string description: Optional short machine-readable code distinct from `type`.: null retry_allowed: type: boolean description: >- When present, whether it's safe to retry with the same idempotency key. errors: type: array description: >- Present on most `urn:radiumone:gateway:validation-error` (400) responses — one entry per invalid field. Some 400s of this type are raised by checks that run after validation and have no `errors` array; always handle it being absent. Rely on `pointer`/`parameter` and `code`, not the wording of `detail`, which can change. items: type: object properties: pointer: type: string description: >- JSON Pointer to the invalid field in the request body, e.g. `/amount/currency` or `/items/0/name`. An empty string means the whole request (e.g. the body isn't valid JSON). parameter: type: string description: >- Name of the invalid query or path parameter. Set instead of `pointer` when the failing value came from the URL, not the body. code: type: string description: >- Machine-readable error type for this field, e.g. `missing` or `string_too_long`. detail: type: string description: Human-readable explanation for this field. required: - type - title - status - detail VerifySessionResponse: description: >- Response body for POST /v1/sessions/{id}/verify (pass-through from tokenization). properties: session_id: description: Tokenization session identifier. title: Session Id type: string status: anyOf: - type: string - type: 'null' description: Session status after verify (e.g. bound). title: Status token: anyOf: - type: string - type: 'null' description: >- Verified numeric EMV vault-surrogate token (digits only, 999900 token-BIN). title: Token required: - session_id title: VerifySessionResponse type: object securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer access token from `POST /v1/auth/token`. Treat it as an opaque string — do not depend on its internal encoding, which has changed before and isn't part of the contract. x-docs-interim: true ````