> ## 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.

# Update session amount - Payments API

> Set the amount the card will be charged on an existing session, which is also the amount 3D Secure authenticates, before you start 3D Secure.



## OpenAPI

````yaml /openapi/radiumone-payments-api.yaml patch /v1/sessions/{session_id}
openapi: 3.1.0
info:
  description: >
    The Payments API lets your server create tokenization sessions, charge and

    manage payments, check loyalty balances, list the currencies you accept,

    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: Accept and manage card payments from your server with RadiumOne.
  title: RadiumOne Payment Gateway
  version: 1.9.4
servers:
  - url: https://api-sandbox.radiumone.io/gateway
    description: Sandbox
  - url: https://api.radiumone.io/gateway
    description: Production
security: []
tags:
  - name: Authentication
    description: Exchange, refresh, and revoke access tokens.
  - name: Currencies
    description: >-
      The currencies RadiumOne supports and the ones enabled for your outlets,
      each with its ISO 4217 minor units.
  - 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,
      and the amount 3D Secure authenticates on them.
  - 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 current status of a transaction.
paths:
  /v1/sessions/{session_id}:
    patch:
      tags:
        - Sessions
      summary: Pin the 3DS amount and/or set 3DS billing on an existing session
      description: >-
        Set the amount the card will be charged on a checkout session you
        already created.


        This is also the amount 3DS authenticates. Use it when the shopper
        decides the amount on

        the payment page -- for example by choosing vouchers to redeem: create
        the session first,

        then send `net_payable_amount` once it is known. Call it from your
        server with your

        merchant credentials; the payment page cannot set this amount.


        `net_payable_amount` must not exceed the session's order total, the
        session must have a

        currency, and the session must still be valid; otherwise the request
        returns 422. Sending

        the same value again always succeeds. A different value while a payment
        3DS

        authentication for this session is in progress or unused cancels it: its
        `ref` stops

        working (a purchase presenting it gets `three-ds:ref-invalid`), so run
        3DS again at the

        new amount. The one exception is a

        purchase that presented one of the session's refs and is still in
        progress: until it

        finishes, a different value returns 422.


        You can also send `billing` (the cardholder billing data used for 3-D
        Secure), alone or

        with the amount; it replaces any billing set earlier. Returns 404 if the
        session does not

        exist or belongs to another merchant.
      operationId: update_session
      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/UpdateSessionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse_SessionUpdatedResponse_'
          description: Successful Response
        '400':
          content:
            application/problem+json:
              example:
                detail: Request payload failed validation.
                status: 400
                title: Validation Error
                type: urn:radiumone:payment-gateway:validation-error
              schema:
                properties:
                  detail:
                    type: string
                  errors:
                    description: >-
                      One entry per invalid field. Present when the request
                      failed schema validation; absent on other 400s. Key your
                      handling on `pointer` or `parameter`, not on `detail`,
                      whose wording may change.
                    items:
                      properties:
                        code:
                          description: >-
                            Machine-readable error type, for example `missing`,
                            `string_too_long` or `value_error`.
                          type: string
                        detail:
                          description: What is wrong with this field.
                          type: string
                        parameter:
                          description: >-
                            Name of the invalid query, path or header parameter.
                            Used instead of `pointer`.
                          type: string
                        pointer:
                          description: >-
                            JSON Pointer to the invalid field in the request
                            body, for example `/card/pan` or `/items/0/name`. An
                            empty string means the error applies to the whole
                            body rather than one field.
                          type: string
                      required:
                        - detail
                        - code
                      type: object
                    type: array
                  status:
                    type: integer
                  title:
                    type: string
                  type:
                    type: string
                type: object
          description: Request payload failed validation.
        '401':
          content:
            application/problem+json:
              example:
                detail: Missing or invalid Bearer token.
                status: 401
                title: Authentication Required
                type: urn:radiumone:payment-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:payment-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:payment-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:payment-gateway:checkout: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.
        '422':
          content:
            application/problem+json:
              example:
                detail: >-
                  `urn:radiumone:payment-gateway:sessions:amount-not-pinnable`:
                  the session has expired, has no currency, `net_payable_amount`
                  is above the session's order total, or a purchase that
                  presented one of the session's 3DS refs is still in progress.
                status: 422
                title: Unprocessable Content
                type: urn:radiumone:payment-gateway:sessions:amount-not-pinnable
              schema:
                properties:
                  detail:
                    type: string
                  status:
                    type: integer
                  title:
                    type: string
                  type:
                    type: string
                type: object
          description: >-
            `urn:radiumone:payment-gateway:sessions:amount-not-pinnable`: the
            session has expired, has no currency, `net_payable_amount` is above
            the session's order total, or a purchase that presented one of the
            session's 3DS refs is still in progress.
        '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:tokenization: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:payment-gateway:internal-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. `urn:radiumone:payment-gateway:service-unavailable`
                  carries `retry_allowed` true when the failure came before any
                  work (signing keys unavailable, service starting).
                  `urn:radiumone:payment-gateway:request-deadline-exceeded`
                  carries `retry_allowed` true only for GET/HEAD/OPTIONS -- a
                  mutating request may have reached a host.
                status: 503
                title: Service Unavailable
                type: urn:radiumone:payment-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.
            `urn:radiumone:payment-gateway:service-unavailable` carries
            `retry_allowed` true when the failure came before any work (signing
            keys unavailable, service starting).
            `urn:radiumone:payment-gateway:request-deadline-exceeded` carries
            `retry_allowed` true only for GET/HEAD/OPTIONS -- a mutating request
            may have reached a host. Also
            `urn:radiumone:payment-gateway:database-unavailable`: the database
            could not be reached or a query could not run. `retry_allowed` is
            true only for GET/HEAD/OPTIONS -- a mutating request may have
            reached a host before the failed write.
      security:
        - merchantBearer: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >
            #!/usr/bin/env bash

            # Pin the net payable amount (after loyalty redemption)

            # BEFORE the browser calls threeDS.authenticate({ ...,
            selectedPaymentMethod: "card" })

            # — required for 3DS + rewards.

            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 pin}"


            curl -sS -X PATCH "$API_BASE/v1/sessions/$RADIUMONE_SESSION_ID" \
              -H "Content-Type: application/json" \
              -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
              -d @request.json
        - lang: javascript
          label: Node.js
          source: >
            #!/usr/bin/env node

            // Pin the net payable amount before the browser calls

            // threeDS.authenticate({ ..., selectedPaymentMethod: "card" }).

            // 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 updateSessionAmount() {
              const res = await fetch(`${API_BASE}/v1/sessions/${sessionId}`, {
                method: "PATCH",
                headers: {
                  "Content-Type": "application/json",
                  Authorization: `Bearer ${accessToken}`,
                },
                body: JSON.stringify(body),
              });
              const payload = await res.json();
              if (!res.ok) {
                // 422 urn:radiumone:payment-gateway:sessions:amount-not-pinnable if net_payable_amount
                // is above the gross order amount or the session expired. Match the whole type.
                throw new Error(`sessions PATCH failed: ${payload.type} (${res.status})`);
              }
              return payload;
            }


            updateSessionAmount().then((r) => console.log(JSON.stringify(r,
            null, 2)));
        - lang: python
          label: Python
          source: >
            #!/usr/bin/env python3

            """Pin the net payable amount before the browser calls

            threeDS.authenticate({ ..., selectedPaymentMethod: "card" }). 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 update_session_amount() -> dict:
                body = json.loads((Path(__file__).parent / "request.json").read_text())
                session_id = os.environ["RADIUMONE_SESSION_ID"]
                resp = requests.patch(
                    f"{API_BASE}/v1/sessions/{session_id}",
                    json=body,
                    headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"},
                    timeout=30,
                )
                payload = resp.json()
                if not resp.ok:
                    # 422 urn:radiumone:payment-gateway:sessions:amount-not-pinnable if net_payable_amount
                    # is above the gross order amount or the session expired. Match the whole type.
                    raise RuntimeError(f"sessions PATCH failed: {payload.get('type')} ({resp.status_code})")
                return payload


            if __name__ == "__main__":
                print(json.dumps(update_session_amount(), indent=2))
components:
  schemas:
    UpdateSessionRequest:
      description: Set the amount the card will be charged on an existing checkout session.
      properties:
        billing:
          anyOf:
            - $ref: '#/components/schemas/ThreeDsBillingData'
            - type: 'null'
          description: >-
            Cardholder billing data for 3-D Secure (replaces any set earlier).
            Same fields and limits as on create.
        net_payable_amount:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          description: >-
            Minor units the CARD will be charged -- the amount 3DS
            authenticates. For a redemption flow, the order total minus the
            redemption the shopper selected. Must not exceed the session's gross
            order amount.
          title: Net Payable Amount
      title: UpdateSessionRequest
      type: object
    SuccessResponse_SessionUpdatedResponse_:
      description: >-
        Standard success envelope. Every successful response has this shape,
        with the operation's own payload under `data`.
      properties:
        data:
          anyOf:
            - $ref: '#/components/schemas/SessionUpdatedResponse'
            - 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[SessionUpdatedResponse]
      type: object
    ThreeDsBillingData:
      additionalProperties: false
      description: >-
        Cardholder billing data for 3-D Secure.


        Send the cardholder name plus an email or phone number where you have
        them; address

        fields are optional. Omit any field you do not hold rather than sending
        an empty value.

        `name` is one free-text string and is never split. `administrative_area`
        is used only for

        US and Canadian addresses.
      properties:
        address1:
          anyOf:
            - maxLength: 60
              type: string
            - type: 'null'
          title: Address1
        address2:
          anyOf:
            - maxLength: 60
              type: string
            - type: 'null'
          title: Address2
        address3:
          anyOf:
            - maxLength: 60
              type: string
            - type: 'null'
          title: Address3
        administrative_area:
          anyOf:
            - maxLength: 20
              type: string
            - type: 'null'
          description: ISO 3166-2 subdivision -- US/CA only.
          title: Administrative Area
        country:
          anyOf:
            - maxLength: 2
              minLength: 2
              type: string
            - type: 'null'
          title: Country
        email:
          anyOf:
            - maxLength: 255
              type: string
            - type: 'null'
          title: Email
        locality:
          anyOf:
            - maxLength: 50
              type: string
            - type: 'null'
          title: Locality
        name:
          anyOf:
            - maxLength: 120
              type: string
            - type: 'null'
          title: Name
        phone_number:
          anyOf:
            - maxLength: 32
              type: string
            - type: 'null'
          title: Phone Number
        postal_code:
          anyOf:
            - maxLength: 10
              type: string
            - type: 'null'
          title: Postal Code
      title: ThreeDsBillingData
      type: object
    SessionUpdatedResponse:
      description: |-
        The amounts now held on the session.

        Check them before starting 3DS authentication.
      properties:
        currency:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO 4217 code pinned on the session.
          title: Currency
        currency_minor_units:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Decimal places of `currency` (ISO 4217 minor units). Null when
            `currency` is.
          title: Currency Minor Units
        gross_order_amount:
          anyOf:
            - type: integer
            - type: 'null'
          description: Minor units of the order total, if the session carries one.
          title: Gross Order Amount
        net_payable_amount:
          anyOf:
            - type: integer
            - type: 'null'
          description: Minor units the card will be charged (null until pinned).
          title: Net Payable Amount
        session_id:
          description: The session that was updated.
          title: Session Id
          type: string
      required:
        - session_id
        - net_payable_amount
      title: SessionUpdatedResponse
      type: object
  securitySchemes:
    merchantBearer:
      description: >-
        Access token from `POST /v1/auth/token`, sent as `Authorization: Bearer
        <token>`. Treat it as opaque.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.