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 withline_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 withbilling_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.
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 withbranding_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
Setlocale 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 withmetadata. 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
state: an opaque string (1–512 characters) you choose. It’s echoed back unchanged on yoursuccess_url/cancel_urlredirects (when present) so you can carry your own request-scoped nonce through the flow. It is not part of the redirect signature — verify it independently if you rely on it.outlet_id: only needed for multi-outlet merchants. Omit it to use your key’s bound outlet (or your account default). It must be a canonical UUID — a malformed value returns400urn:radiumone:checkout-hpp:validation-invalid-input. A well-formed value that isn’t your outlet returns422urn:radiumone:checkout-hpp:outlet-not-found, one that conflicts with your key’s bound outlet returns422urn:radiumone:checkout-hpp:outlet-binding-violation, and a disabled outlet returns422urn:radiumone:checkout-hpp:outlet-disabled.
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.