> ## 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. # Authorize - Payments API > Authorize a card payment to hold funds without capturing them, then capture or void it later. A duplicate request ID returns the original response. ## OpenAPI ````yaml /openapi/radiumone-payments-api.yaml post /v1/transactions/auth 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/transactions/auth: post: tags: - Payments summary: Authorize a payment description: |- Submit an authorisation-only request (funds reserved, not yet captured). Idempotent: duplicate request_id returns the original response. Follow up with POST /v1/transactions/{id}/capture or /void. operationId: auth_transaction_v1_transactions_auth_post requestBody: content: application/json: schema: $ref: '#/components/schemas/AuthRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/SuccessResponse_TransactionResponse_' example: status: ok request_id: req_1b2c3d4e5f60 data: id: 1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081 request_id: ord-1002-auth-1 type: AUTHORIZE status: AUTHORIZED amount: 10000 currency: SGD payment_method_type: card order_reference: ORD-1002 response_code: '00' parent_transaction_id: null switch_request_id: sw-1b2c3d4e created_at: '2026-09-14T10:00:00.000Z' updated_at: '2026-09-14T10:00:01.000Z' 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: A resource with that identifier already exists. status: 409 title: Conflict type: urn:radiumone:gateway:conflict schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: A resource with that identifier already exists. '410': content: application/problem+json: example: detail: >- The payment token has expired or its card data is no longer available. status: 410 title: Gone type: urn:radiumone:gateway:gone schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: >- The payment token has expired or its card data is no longer available. '422': description: A business rule was violated. x-docs-interim: true content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '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 # Authorize only (reserve funds, capture later). Any 2xx is a response — branch # on data.status. On a timeout/5xx/PENDING, retry with the SAME request_id; # never mint a new one for the same order attempt. 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}" curl -sS -X POST "$API_BASE/v1/transactions/auth" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \ -d @request.json - lang: javascript label: Node.js source: > #!/usr/bin/env node // Authorize only (reserve funds, capture later). Any 2xx is a response — branch // on data.status. On a timeout/5xx/PENDING, retry with the SAME request_id; // never mint a new one for the same order attempt. // Node 18+ ESM fetch. Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_API_BASE (optional override). // // Shared result pattern: any 2xx is a response you branch on `data.status`. // On a network timeout, a 5xx, or `status:"PENDING"`, retry with the SAME // request_id — never mint a new one for the same attempt. 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 body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url))); // Exponential backoff with jitter: attempt 1 waits ~250-500ms, doubling each // attempt, capped at 4s -- avoids hammering the gateway in a tight retry loop. function backoffMs(attempt) { const base = Math.min(250 * 2 ** (attempt - 1), 4000); return base + Math.random() * base; } async function createAuthorization(maxAttempts = 3) { for (let attempt = 1; attempt <= maxAttempts; attempt += 1) { let res; try { res = await fetch(`${API_BASE}/v1/transactions/auth`, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${accessToken}`, }, body: JSON.stringify(body), // same request_id every attempt }); } catch (networkErr) { if (attempt === maxAttempts) throw networkErr; await new Promise((r) => setTimeout(r, backoffMs(attempt))); continue; } if (res.status >= 500) { if (attempt === maxAttempts) throw new Error(`server error ${res.status} after ${attempt} attempts`); await new Promise((r) => setTimeout(r, backoffMs(attempt))); continue; } const payload = await res.json(); if (!res.ok) { throw new Error(`request failed: ${payload.type ?? payload.code} (${res.status})`); } if (payload.data.status === "PENDING") { if (attempt === maxAttempts) return payload; await new Promise((r) => setTimeout(r, backoffMs(attempt))); continue; } return payload; // branch on data.status } throw new Error("unreachable"); } createAuthorization().then((r) => console.log(JSON.stringify(r, null, 2))); - lang: python label: Python source: > #!/usr/bin/env python3 """Authorize only (reserve funds, capture later). Any 2xx is a response — branch on data.status. On a timeout/5xx/PENDING, retry with the SAME request_id; never mint a new one for the same order attempt. Shared result pattern: any 2xx is a response you branch on 'status'. On a network timeout, a 5xx, or status 'PENDING', retry with the SAME request_id -- never mint a new one for the same attempt. """ import json import os import random import time from pathlib import Path import requests API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway") def backoff_seconds(attempt: int) -> float: """Exponential backoff with jitter: attempt 1 waits ~0.25-0.5s, doubling each attempt, capped at 4s -- avoids hammering the gateway in a loop.""" base = min(0.25 * 2 ** (attempt - 1), 4.0) return base + random.random() * base def create_authorization(max_attempts: int = 3) -> dict: body = json.loads((Path(__file__).parent / "request.json").read_text()) headers = {"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"} for attempt in range(1, max_attempts + 1): try: resp = requests.post(f"{API_BASE}/v1/transactions/auth", json=body, headers=headers, timeout=30) except requests.exceptions.Timeout: if attempt == max_attempts: raise time.sleep(backoff_seconds(attempt)) continue if resp.status_code >= 500: if attempt == max_attempts: raise RuntimeError(f"server error {resp.status_code} after {attempt} attempts") time.sleep(backoff_seconds(attempt)) continue payload = resp.json() if not resp.ok: code = payload.get("type") or payload.get("code") raise RuntimeError(f"request failed: {code} ({resp.status_code})") if payload["data"]["status"] == "PENDING": if attempt == max_attempts: return payload time.sleep(backoff_seconds(attempt)) continue return payload # branch on data.status raise RuntimeError("unreachable") if __name__ == "__main__": print(json.dumps(create_authorization(), indent=2)) components: schemas: AuthRequest: description: >- Request body for POST /v1/transactions/auth. Authorise-only: reserves funds without capturing. Use CAPTURE to complete. Idempotent via request_id scoped to the authenticated merchant. example: amount: currency: SGD value: '000000010000' card: token: '4111111111111111' channel: CARD_PRESENT request_id: auth-20260528-001 properties: amount: $ref: '#/components/schemas/MoneyAmount' description: Amount to authorize, as a {currency, value} money object. card: $ref: '#/components/schemas/CardToken' description: Card group carrying the network token (no raw PAN). channel: description: >- Transaction channel -- the source/manner of the payment. Shapes routing candidate selection and the capability/operation constraints applied downstream (acquirer_channel + acquirer_channel_operation gating). enum: - CARD_PRESENT - ECOMMERCE - MOTO - PAYMENT_LINK - IN_APP - RECURRING title: Channel type: string emv: anyOf: - type: string - additionalProperties: type: string type: object - type: 'null' description: >- EMV chip data read from the card, for card-present authorizations. Send it either as the hex string your terminal produced or as a map of EMV tag to hex value. Omit it for online payments made with a token. title: Emv metadata: anyOf: - additionalProperties: true type: object - type: 'null' description: Optional merchant-supplied metadata. title: Metadata order_reference: anyOf: - maxLength: 128 type: string - type: 'null' description: >- Merchant's order/cart reference for this authorization (common in ecommerce). Stored, searchable via the transaction list filter, and forwarded to the acquirer for reconciliation. Capture/void/refund inherit it from this transaction, so one acquirer-side lookup returns the whole order. Acquirers impose their own limits and character rules (commonly 20 characters, alphanumeric) and will shorten the value to fit, so prefer short references using letters, digits, '-', '.' and '_', and put the varying part LAST -- values are shortened from the front. title: Order Reference request_id: description: Merchant-supplied idempotency key. maxLength: 64 minLength: 8 title: Request Id type: string three_ds: anyOf: - $ref: '#/components/schemas/ThreeDsPurchaseInput' - type: 'null' description: >- 3DS result (one of {ref} | {mode:non_payer_auth} | {cavv,...}); absent == non-payer-auth. required: - request_id - amount - card - channel title: AuthRequest type: object SuccessResponse_TransactionResponse_: description: >- Standard success envelope. Every successful response has this shape, with the operation's own payload under `data`. properties: data: anyOf: - $ref: '#/components/schemas/TransactionResponse' - 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[TransactionResponse] 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 MoneyAmount: description: >- A money value: an ISO 4217 currency plus the amount in that currency's minor units. `value` is a numeric string in minor units -- the decimal point is implied by the currency (2 places for most currencies, so `"1050"` means 10.50). Up to 12 digits; leading zeros are optional. properties: currency: description: ISO 4217 currency code (e.g. SGD, USD). maxLength: 3 minLength: 3 title: Currency type: string value: description: >- Amount in minor units as a numeric string (e.g. '1050' or '000000001050' = 10.50). Zero-padding optional; up to 12 digits. maxLength: 12 minLength: 1 pattern: ^\d{1,12}$ title: Value type: string required: - currency - value title: MoneyAmount type: object CardToken: description: >- The card to charge, identified by its payment token. Send only the payment token issued for the card -- never the card number or expiry. The token stands in for both. properties: token: description: >- The card's payment token (digits only). Treat it as opaque -- it is not a card number. maxLength: 128 minLength: 8 title: Token type: string required: - token title: CardToken type: object ThreeDsPurchaseInput: additionalProperties: false description: >- The 3-D Secure result to attach to a purchase or authorization. Send exactly one of: `ref` (the reference returned when the gateway ran the authentication for you), `mode: non_payer_auth` (this payment was not authenticated), or a `cavv` block (you authenticated the cardholder through your own 3DS provider). Omitting `three_ds` altogether is the same as `mode: non_payer_auth`. properties: cavv: anyOf: - maxLength: 64 type: string - type: 'null' description: >- Cardholder Authentication Verification Value produced by your own 3DS provider. Send it only when you ran the authentication yourself, and send `eci`, `ds_transaction_id` and `version` alongside it. title: Cavv ds_transaction_id: anyOf: - maxLength: 64 type: string - type: 'null' description: >- The card scheme directory server's identifier for the authentication, from your own 3DS provider. Send it with `cavv`. title: Ds Transaction Id eci: anyOf: - maxLength: 2 type: string - type: 'null' description: >- Electronic Commerce Indicator from your own 3DS provider, recording how the card was authenticated and who carries liability. Send it with `cavv`. title: Eci mode: anyOf: - const: non_payer_auth type: string - type: 'null' description: Explicit non-payer-auth. title: Mode ref: anyOf: - maxLength: 80 type: string - type: 'null' description: Single-use 3DS authentication ref. title: Ref version: anyOf: - maxLength: 10 type: string - type: 'null' description: >- 3DS protocol version your provider used, for example `2.2.0`. Send it with `cavv`. title: Version title: ThreeDsPurchaseInput type: object TransactionResponse: description: >- A single transaction and its current outcome. `group_id` links the card and loyalty parts of a sale that used both, and `loyalty` carries the loyalty outcome when the purchase redeemed points. properties: amount: description: Amount in smallest currency unit. title: Amount type: integer created_at: description: ISO 8601 creation timestamp (UTC). title: Created At type: string currency: description: ISO 4217 currency code. title: Currency type: string group_id: anyOf: - type: string - type: 'null' description: >- Transaction group UUID shared by payment and loyalty legs in a split sale. title: Group Id id: description: Transaction UUID. title: Id type: string loyalty: anyOf: - $ref: '#/components/schemas/LoyaltyOutcomeComponent' - type: 'null' description: >- Loyalty leg outcome (present only when purchase included a redemption component). order_reference: anyOf: - type: string - type: 'null' description: Merchant order/cart reference supplied at auth/purchase (ecommerce). title: Order Reference parent_transaction_id: anyOf: - type: string - type: 'null' description: UUID of parent authorization (for capture/void/refund). title: Parent Transaction Id payment_method_type: description: Payment instrument category. title: Payment Method Type type: string request_id: description: Merchant-supplied idempotency key. title: Request Id type: string response_code: default: '' description: >- Verbatim acquirer response code, for display and reconciliation only. DO NOT derive success from it: an operator can classify a non-'00' code as APPROVED for an acquirer (or for one operation), in which case this field still shows the host's non-'00' value while the transaction is approved. Key on `status` instead. The gateway never rewrites this value, so it always matches what the acquirer's own statement will show. title: Response Code type: string status: description: >- Current transaction lifecycle status, and THE field to key the outcome on. Approved = the operation's success status (AUTHORIZE -> AUTHORIZED; PURCHASE/CAPTURE/REFUND -> CAPTURED; VOID -> VOIDED). DECLINED = the issuer declined (hard decline). FAILED = a system/network error, which is NOT a statement about the card. Derived from the resolved decline classification, not from response_code alone. title: Status type: string switch_request_id: anyOf: - type: string - type: 'null' description: >- The upstream processor's own reference for this transaction. Quote it when raising an issue with us about a specific transaction. title: Switch Request Id type: description: 'Transaction type: AUTHORIZE, CAPTURE, VOID, or REFUND.' title: Type type: string updated_at: description: ISO 8601 last-updated timestamp (UTC). title: Updated At type: string required: - id - request_id - type - status - amount - currency - payment_method_type - created_at - updated_at title: TransactionResponse type: object LoyaltyOutcomeComponent: description: >- What happened to the loyalty part of a sale. Present when the purchase included a loyalty redemption. It reports only the loyalty side, which can succeed or fail independently of the card payment, so read it alongside the transaction's own status rather than treating either as the whole result. properties: leg_status: anyOf: - type: string - type: 'null' description: >- Loyalty leg transaction status (CAPTURED, FAILED, PENDING, etc.) -- key the leg outcome on this, not on response_code. A sale can approve on the card leg and decline on the loyalty leg; the two are independent. title: Leg Status pools: anyOf: - items: $ref: '#/components/schemas/LoyaltyPool' type: array - type: 'null' description: Post-redemption pool balances (returned by some hosts). title: Pools redeemed_amount: anyOf: - type: integer - type: 'null' description: Points redeemed in minor currency units (host-confirmed). title: Redeemed Amount response_code: anyOf: - type: string - type: 'null' description: >- Verbatim acquirer response code from the loyalty leg, for display and reconciliation only. Not an outcome signal -- see leg_status. title: Response Code switch_request_id: anyOf: - type: string - type: 'null' description: >- The upstream processor's own reference for the loyalty part of this sale. Quote it when raising an issue with us about the redemption. title: Switch Request Id vouchers: anyOf: - items: $ref: '#/components/schemas/LoyaltyVoucher' type: array - type: 'null' description: Vouchers consumed in this redemption. title: Vouchers title: LoyaltyOutcomeComponent type: object LoyaltyPool: description: A loyalty point pool balance returned by a loyalty balance inquiry. properties: account_indicator: anyOf: - type: string - type: 'null' description: Account type indicator from the host. title: Account Indicator balance_sign: anyOf: - type: string - type: 'null' description: >- Sign of the balance: '0' = positive, '1' = negative. This is the authoritative sign -- prefer it over the sign of `point_balance`. It reports the sign only and does not say whether the pool can be redeemed. title: Balance Sign club_code: description: Loyalty club code (e.g. 'UNI'). title: Club Code type: string expiry_date: anyOf: - type: string - type: 'null' description: >- Point expiry date as DDMMYYYY, passed through as the loyalty programme returned it. '00000000' means the points do not expire. Expired pools are not filtered out, so hide them yourself if you don't want to show them. In sandbox, test cards return fixed profiles, so expiry dates there are not realistic. title: Expiry Date point_balance: description: >- Current pool balance as a signed decimal (2 decimal places). Fractional for monetary pools (e.g. a 'UNI$' cash-back pool returns 4534.56); whole for point pools. The sign always agrees with `balance_sign`, except at exactly zero, where the number carries no sign -- read `balance_sign` instead. title: Point Balance type: number pool_id: description: Pool identifier within the club. title: Pool Id type: string pool_name: description: Human-readable pool label (e.g. 'UNI$'). title: Pool Name type: string required: - club_code - pool_id - pool_name - point_balance title: LoyaltyPool type: object LoyaltyVoucher: description: A redeemable voucher offered against a loyalty pool. properties: description: description: Human-readable voucher label. title: Description type: string max_redeemable: description: Maximum vouchers redeemable in one order. title: Max Redeemable type: integer points_price: description: >- Points required to redeem one voucher. Fractional for monetary pools (e.g. a 'UNI$' cash-back voucher priced at 15.50); whole for point pools. Host-supplied, so accept both to avoid dropping decimals. title: Points Price type: number pool_name: description: Pool the voucher redeems against (e.g. 'UNI$'). title: Pool Name type: string redeem_value: description: >- Monetary value of the voucher in currency major units (e.g. 10.0 = $10.00). title: Redeem Value type: number voucher_code: description: Voucher identifier used to redeem. title: Voucher Code type: string required: - voucher_code - description - pool_name - points_price - redeem_value - max_redeemable title: LoyaltyVoucher 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 ````