Skip to main content
Beyond the required amount, currency, order_reference, success_url, and cancel_url on create a checkout session, a checkout session accepts several optional fields to shape what the shopper sees and what you get back.
Amounts are always integers in the currency’s minor units. For example, 5000 for SGD means SGD 50.00. Only currencies with 2 minor units are accepted today — read each currency’s minor units from the API rather than from your own table. See Currencies and amounts.

Line items and adjustments

Add an itemized breakdown with line_items[] (name, quantity, unit_amount) and optional adjustments[] (kind: tax, shipping, discount, or fee; label; signed amount). adjustments requires line_items — an adjustments-only payload is rejected, since there’s no base total for the deltas to apply to. The math is enforced: the sum of line_items amounts plus the sum of adjustments amounts must equal the session’s top-level amount, or the request is rejected with 400 urn:radiumone:checkout-hpp:validation-line-items-mismatch. Discount adjustments must be zero or negative; tax, shipping, and fee adjustments must be zero or positive. Each line_items entry must be a JSON object with a string name — a null or non-object entry, or a non-string name, returns 400 urn:radiumone:checkout-hpp:validation-invalid-input instead of a generic server error.

Shopper and billing details

Send what you know about the shopper’s billing details with billing_details — cardholder name, email, phone, and billing address. It’s shown to the shopper on the pay page and passed to the card issuer for 3D Secure (see 3DS with hosted checkout):
Every field is optional and none of them ever fail the request on their own — an invalid or over-length sub-field is dropped rather than rejected, so omit a field entirely rather than sending an empty string.
Breaking change: customer is no longer accepted. Sending it — any value, including null — returns 400 urn:radiumone:checkout-hpp:validation-invalid-input. Send billing_details instead.
If you’re embedding checkout in an iframe and it isn’t rendering after you’ve set these fields, the cause is almost always domain registration or CSP, not these fields — see Fix embedded checkout that won’t load.

Branding profile

Reference a branding profile configured for your account with branding_profile_id (optional, at most 64 characters). If you omit it, or the ID doesn’t match a configured profile, your account’s default branding applies — the request never fails because of a bad branding_profile_id. You can also override individual settings for just this checkout with a branding object. See Brand the payment page for how profiles are set up, how a checkout resolves which branding to use, and the full settings and override reference.

Locale

Set locale to one of the accepted values. Only some of the accepted locales currently render translated copy — everything else falls back to English: An unrecognized locale value is rejected outright — pick one from the accepted list even if it isn’t yet rendered.

Currency and amount

currency is a three-letter ISO 4217 code, case-insensitive on input (always returned upper-case). Hosted checkout keeps no currency list of its own: the currency must be enabled for your merchant account, and today only currencies with two decimal places are accepted. A currency that isn’t enabled for you, isn’t an active ISO 4217 code, or doesn’t have two decimal places is rejected with 400 urn:radiumone:checkout-hpp:validation-invalid-input. To see which currencies are enabled for your account, call GET /v1/merchant/currencies; Currencies and amounts explains minor units in full. The session GET returns currency_minor_units — the currency’s decimal places (always 2 today). amount divided by 10 to that power is the amount in major units, so 4999 is 49.99 in every currency accepted today, IDR included. Format amounts with currency_minor_units rather than a currency table of your own. amount must be an integer in minor units and at least 50 (for example, the minimum for SGD is 50 = SGD 0.50) — smaller amounts are rejected. There’s no enforced maximum on the Checkout API itself; an excessively large amount is instead rejected by the payment gateway with 422 urn:radiumone:checkout-hpp:gateway-request-rejected.

Metadata

Attach your own key-value data with metadata. Metadata must be a JSON object. Serialized as compact JSON, it can be at most 4096 UTF-16 code units, limit included. Most characters count as 1 unit, including Chinese and Thai; emoji count as 2. A larger object is rejected with 400 urn:radiumone:checkout-hpp:validation-invalid-input — the error’s detail text may still say “under 4096 bytes”, but the limit is measured in UTF-16 code units as described here. Use it for your own order/customer references; it’s echoed back on the session but never interpreted by RadiumOne.

state and outlet_id

Next steps

Redirect to hosted checkout

Put these fields to use in a full integration.

3DS with hosted checkout

How billing_details feeds 3D Secure.

Fix embedded checkout that won't load

Domain registration and CSP for embedded mode.
Last modified on October 25, 2026