> ## 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. # Rotate refresh token - Payments API > Exchange a refresh token for a new access token and refresh token pair. Each refresh token works once, so store the new one. ## OpenAPI ````yaml /openapi/radiumone-payments-api.yaml post /v1/auth/token/refresh 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/auth/token/refresh: post: tags: - Authentication summary: Rotate refresh token description: >- Exchange a refresh token for a new access token and a new refresh token. Refresh tokens are single-use: the token you send is invalidated as soon as it is accepted, so always store the refresh token returned by this call. Presenting a token that was already used returns 401 and revokes every outstanding refresh token issued to that API key. Returns 401 as well for an expired, revoked or unknown token, or if the API key or merchant account is no longer active. If a new access token cannot be issued, the call returns 503 and the new refresh token is not usable -- obtain a fresh token pair from `POST /v1/auth/token` with your API key. operationId: refresh_token_v1_auth_token_refresh_post requestBody: content: application/json: schema: $ref: '#/components/schemas/RefreshRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SuccessResponse_TokenResponse_' 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. '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. security: [] x-codeSamples: - lang: bash label: cURL source: > #!/usr/bin/env bash # Rotate a refresh token for a new access + refresh pair. The old refresh # token is single-use; replaying a CONSUMED token revokes all refresh tokens # for that key, so store the new one immediately and only once. set -euo pipefail API_BASE="${RADIUMONE_API_BASE:-https://api-sandbox.radiumone.io/gateway}" curl -sS -X POST "$API_BASE/v1/auth/token/refresh" \ -H "Content-Type: application/json" \ -d @request.json - lang: javascript label: Node.js source: > #!/usr/bin/env node // Rotate a refresh token. Node 18+ ESM fetch. // Env: RADIUMONE_REFRESH_TOKEN, RADIUMONE_API_BASE (optional override). import { readFileSync } from "node:fs"; const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway"; const body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url))); if (process.env.RADIUMONE_REFRESH_TOKEN) body.refresh_token = process.env.RADIUMONE_REFRESH_TOKEN; async function refreshAccessToken() { const res = await fetch(`${API_BASE}/v1/auth/token/refresh`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), }); const payload = await res.json(); if (!res.ok) { throw new Error(`auth/token/refresh failed: ${payload.type ?? payload.code} (${res.status})`); } // Store the NEW refresh_token immediately — the old one is single-use. return payload; } refreshAccessToken().then((r) => console.log(JSON.stringify(r, null, 2))); - lang: python label: Python source: > #!/usr/bin/env python3 """Rotate a refresh token for a new access + refresh pair. 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 refresh_access_token() -> dict: body = json.loads((Path(__file__).parent / "request.json").read_text()) if os.environ.get("RADIUMONE_REFRESH_TOKEN"): body["refresh_token"] = os.environ["RADIUMONE_REFRESH_TOKEN"] resp = requests.post(f"{API_BASE}/v1/auth/token/refresh", json=body, timeout=30) payload = resp.json() if not resp.ok: raise RuntimeError(f"auth/token/refresh failed: {payload.get('type') or payload.get('code')} ({resp.status_code})") # Store the NEW refresh_token immediately — the old one is single-use. return payload if __name__ == "__main__": print(json.dumps(refresh_access_token(), indent=2)) components: schemas: RefreshRequest: description: Request body for POST /auth/token/refresh. properties: refresh_token: description: >- Opaque refresh token previously issued by /auth/token or /auth/token/refresh. maxLength: 53 minLength: 53 pattern: ^r1rt_[0-9a-f]{48}$ title: Refresh Token type: string required: - refresh_token title: RefreshRequest type: object SuccessResponse_TokenResponse_: description: >- Standard success envelope. Every successful response has this shape, with the operation's own payload under `data`. properties: data: anyOf: - $ref: '#/components/schemas/TokenResponse' - 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[TokenResponse] 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 TokenResponse: description: >- The result of exchanging an API key for an access token. `refresh_token`, `refresh_expires_in` and `merchant_id` are returned only when you authenticate with a secret API key. They are omitted for publishable keys. properties: access_token: description: Access token to send as the Bearer token on your API requests. title: Access Token type: string expires_in: description: Access token lifetime in seconds. title: Expires In type: integer merchant_id: anyOf: - type: string - type: 'null' description: Merchant UUID. Omitted with refresh_token. title: Merchant Id publishable_key: anyOf: - type: string - type: 'null' description: >- Merchant's active publishable key (r1pk_*), plaintext. Returned only when authenticating with a SECRET key. null if the merchant has no active publishable key provisioned. title: Publishable Key redirect_secret: anyOf: - type: string - type: 'null' description: >- Merchant's redirect signing secret (rsec_*), plaintext. Returned only when authenticating with a SECRET key. null if the merchant has not rotated a redirect secret. title: Redirect Secret refresh_expires_in: anyOf: - type: integer - type: 'null' description: Refresh token lifetime in seconds. Omitted with refresh_token. title: Refresh Expires In refresh_token: anyOf: - type: string - type: 'null' description: Opaque refresh token (rotated on use). Omitted for publishable keys. title: Refresh Token token_type: default: Bearer description: Token type, always 'Bearer'. title: Token Type type: string required: - access_token - expires_in title: TokenResponse 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 ````