#!/usr/bin/env bash# Create a tokenization session for Elements. Pass session_id/session_secret/# pubkey_jws to the browser unchanged — never re-serialize pubkey_jws.# net_payable_amount is the amount 3D Secure authenticates; billing (cardholder# name plus email or phone) is used only for 3D Secure. Omit fields you don't hold.set -euo pipefailAPI_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/sessions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \ -d @request.json
#!/usr/bin/env python3
"""Create a tokenization/checkout session for Elements. 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 create_payment_session() -> dict:
body = json.loads((Path(__file__).parent / "request.json").read_text())
resp = requests.post(
f"{API_BASE}/v1/sessions",
json=body,
headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"},
timeout=30,
)
payload = resp.json()
if not resp.ok:
raise RuntimeError(f"sessions create failed: {payload.get('type') or payload.get('code')} ({resp.status_code})")
# Pass session_id, session_secret and pubkey_jws to the browser byte-for-byte.
return payload
if __name__ == "__main__":
print(json.dumps(create_payment_session(), indent=2))
{
"detail": "Missing or invalid Bearer token, or `urn:radiumone:payment-gateway:authentication-required` because your merchant account is not active (suspended, disabled or deleted). Checked on every request, not only when the token is issued.",
"status": 401,
"title": "Authentication Required",
"type": "urn:radiumone:payment-gateway:authentication-required"
}
{
"detail": "Insufficient permissions for this operation; `urn:radiumone:payment-gateway:auth:outlet-binding-violation`: the request's `outlet_id` names a different outlet than the one your API key is bound to; or `urn:radiumone:payment-gateway:merchant:outlet-disabled` (`retry_allowed: false`): the outlet -- the one named, the one your key is bound to, or your DEFAULT outlet -- is disabled. Re-enabling the outlet restores service; the key is not revoked.",
"status": 403,
"title": "Permission Denied",
"type": "urn:radiumone:payment-gateway:auth:outlet-binding-violation"
}
{
"detail": "The requested resource does not exist, or `urn:radiumone:payment-gateway:checkout:outlet-not-found`: the outlet (named, key-bound, or your DEFAULT outlet) does not exist for your account. One answer on every surface (was 400 `payment-gateway:validation-error` on transactions).",
"status": 404,
"title": "Not Found",
"type": "urn:radiumone:payment-gateway:checkout:outlet-not-found"
}
{
"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"
}
{
"detail": "`urn:radiumone:payment-gateway:checkout:currency-not-supported` (the currency is not allowed for this outlet) or `urn:radiumone:payment-gateway:checkout:redirect-url-not-allowed` (`success_url` / `cancel_url` is not on your allowed domains). Currency: `urn:radiumone:payment-gateway:currency:unknown-currency` (the currency is well-formed but not an active ISO 4217 currency -- an unknown, fund, N.A. or withdrawn code; `errors[]` names the field, `retry_allowed: false`) or `urn:radiumone:payment-gateway:currency:minor-units-not-supported` (a valid ISO 4217 currency whose minor units are not 2, e.g. JPY or KWD -- only 2-decimal currencies are supported; `retry_allowed: false`).",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:checkout:currency-not-supported"
}
{
"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"
}
{
"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"
}
Create tokenization session - Payments API
Create a tokenization session so the Elements SDK can collect card details in the browser and return a card token to your server.
POST
/
v1
/
sessions
cURL
#!/usr/bin/env bash# Create a tokenization session for Elements. Pass session_id/session_secret/# pubkey_jws to the browser unchanged — never re-serialize pubkey_jws.# net_payable_amount is the amount 3D Secure authenticates; billing (cardholder# name plus email or phone) is used only for 3D Secure. Omit fields you don't hold.set -euo pipefailAPI_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/sessions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \ -d @request.json
#!/usr/bin/env python3
"""Create a tokenization/checkout session for Elements. 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 create_payment_session() -> dict:
body = json.loads((Path(__file__).parent / "request.json").read_text())
resp = requests.post(
f"{API_BASE}/v1/sessions",
json=body,
headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"},
timeout=30,
)
payload = resp.json()
if not resp.ok:
raise RuntimeError(f"sessions create failed: {payload.get('type') or payload.get('code')} ({resp.status_code})")
# Pass session_id, session_secret and pubkey_jws to the browser byte-for-byte.
return payload
if __name__ == "__main__":
print(json.dumps(create_payment_session(), indent=2))
{
"detail": "Missing or invalid Bearer token, or `urn:radiumone:payment-gateway:authentication-required` because your merchant account is not active (suspended, disabled or deleted). Checked on every request, not only when the token is issued.",
"status": 401,
"title": "Authentication Required",
"type": "urn:radiumone:payment-gateway:authentication-required"
}
{
"detail": "Insufficient permissions for this operation; `urn:radiumone:payment-gateway:auth:outlet-binding-violation`: the request's `outlet_id` names a different outlet than the one your API key is bound to; or `urn:radiumone:payment-gateway:merchant:outlet-disabled` (`retry_allowed: false`): the outlet -- the one named, the one your key is bound to, or your DEFAULT outlet -- is disabled. Re-enabling the outlet restores service; the key is not revoked.",
"status": 403,
"title": "Permission Denied",
"type": "urn:radiumone:payment-gateway:auth:outlet-binding-violation"
}
{
"detail": "The requested resource does not exist, or `urn:radiumone:payment-gateway:checkout:outlet-not-found`: the outlet (named, key-bound, or your DEFAULT outlet) does not exist for your account. One answer on every surface (was 400 `payment-gateway:validation-error` on transactions).",
"status": 404,
"title": "Not Found",
"type": "urn:radiumone:payment-gateway:checkout:outlet-not-found"
}
{
"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"
}
{
"detail": "`urn:radiumone:payment-gateway:checkout:currency-not-supported` (the currency is not allowed for this outlet) or `urn:radiumone:payment-gateway:checkout:redirect-url-not-allowed` (`success_url` / `cancel_url` is not on your allowed domains). Currency: `urn:radiumone:payment-gateway:currency:unknown-currency` (the currency is well-formed but not an active ISO 4217 currency -- an unknown, fund, N.A. or withdrawn code; `errors[]` names the field, `retry_allowed: false`) or `urn:radiumone:payment-gateway:currency:minor-units-not-supported` (a valid ISO 4217 currency whose minor units are not 2, e.g. JPY or KWD -- only 2-decimal currencies are supported; `retry_allowed: false`).",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:checkout:currency-not-supported"
}
{
"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"
}
{
"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"
}
Authorizations
Authorization
string
header
required
Access token from POST /v1/auth/token, sent as Authorization: Bearer <token>. Treat it as opaque.
Body
application/json
Optional body for creating a checkout session.
Every field is optional. You don't send your merchant ID -- it is taken from your
access token.
amount
integer | null
GROSS order total in smallest currency unit (optional; enables amount-conditioned discovery). This is the order value, not necessarily what the card pays -- see net_payable_amount.
Required range: x >= 0
billing
ThreeDsBillingData · object | null
Cardholder billing data for 3-D Secure, kept server-side (encrypted) for this session and sent to the card scheme during 3DS authentication. Never forwarded to tokenization; erased once the authentication completes. Same fields and limits as the billing sent by the 3DS authentication step your payment page / Elements SDK runs.
Show child attributes
cancel_url
string | null
Payment-cancel redirect URL. Validated against the merchant's allowed_domains (422 on mismatch).
Maximum string length: 2048
channel
enum<string> | null
The channel this checkout belongs to, for 3DS: send PAYMENT_LINK from a payment-link integration so the acquirer's payment-link 3DS rules apply. Omitted means ECOMMERCE. Fixed at create (not PATCHable); the browser never supplies it.
Available options:
ECOMMERCE,
PAYMENT_LINK
currency
string | null
ISO 4217 currency code. When set, response includes supported payment_methods.
Required string length: 3
Pattern: ^[A-Za-z]{3}$
ip_address
string | null
Your customer's IP address, used as a fraud signal (optional).
Maximum string length: 45
net_payable_amount
integer | null
Minor units the CARD will be charged -- the amount 3DS authenticates. Equal to amount for a plain card sale; the post-redemption residual for a voucher/rewards flow. REQUIRED for any session that will run 3DS: the 3DS authentication step your payment page / Elements SDK runs refuses without it rather than authenticating the gross order amount, which would be the wrong figure.
Required range: x >= 0
outlet_id
string | null
Outlet UUID for discovery. Defaults to the merchant's DEFAULT outlet.
redemption_expected
boolean | null
Whether this checkout may apply a loyalty/voucher redemption. When true, the 3DS authentication step your payment page / Elements SDK runs refuses until you have set net_payable_amount with PATCH /v1/sessions/{id}, so the amount the card is actually charged is what gets authenticated. OPTIONAL and inert when 3DS does not run -- a non-3DS checkout is unaffected whether it is absent, present, or stale.
success_url
string | null
Post-payment redirect URL. Validated against the merchant's allowed_domains (422 on mismatch).
Maximum string length: 2048
ttl_minutes
integer | null
How long the session stays valid, in minutes (5–60). Defaults to 30. The card a shopper enters stays usable for about 30 minutes whatever this value is, so in a longer session a shopper who waits too long before paying is asked to enter the card again.
Required range: 5 <= x <= 60
user_agent
string | null
Your customer's browser User-Agent, used as a fraud signal (optional).
Maximum string length: 512
Response
Successful Response
Standard success envelope. Every successful response has this shape, with the operation's own payload under data.
data
SessionCreatedResponse · object | null
The operation's result. Its shape is documented per operation; omitted on responses that carry no payload.
Show child attributes
message
string | null
Optional human-readable note. Omitted from the response when not set, which is the case for every payment operation today. Never parse it.
request_id
string | null
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.
status
string
default:ok
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.