#!/usr/bin/env bash
# Purchase (authorise + capture in one call). 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/purchase" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
-d @request.json#!/usr/bin/env python3
"""Purchase (authorise + capture in one call). Python 3.10+, requests.
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 (or poll GET /v1/transactions/{id}/status) — never mint a new
request_id for the same order 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_purchase(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/purchase", json=body, headers=headers, timeout=30)
except requests.exceptions.Timeout:
if attempt == max_attempts:
raise
time.sleep(backoff_seconds(attempt))
continue # network timeout: retry with the same body/request_id
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 # retry with the same request_id
payload = resp.json()
if not resp.ok:
# 4xx: not retryable by re-sending — fix the request, or handle
# urn:radiumone:transaction:idempotency-body-mismatch if you changed it.
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"purchase failed: {code} ({resp.status_code})")
if payload["data"]["status"] == "PENDING":
if attempt == max_attempts:
return payload # caller should poll GET status / wait for webhook
time.sleep(backoff_seconds(attempt))
continue # retry the same request_id
# Branch on data.status: CAPTURED (success) | DECLINED (final, no retry) | FAILED.
return payload
raise RuntimeError("unreachable")
if __name__ == "__main__":
print(json.dumps(create_purchase(), indent=2))
{
"status": "ok",
"request_id": "req_7a8b9c0d1e2f",
"data": {
"id": "8f1c2e10-4b3a-4c5d-9e6f-7a8b9c0d1e2f",
"request_id": "ord-1001-pay-1",
"type": "PURCHASE",
"status": "CAPTURED",
"amount": 5000,
"currency": "SGD",
"payment_method_type": "card",
"order_reference": "ORD-1001",
"response_code": "00",
"parent_transaction_id": null,
"switch_request_id": "sw-8f1c2e10",
"created_at": "2026-09-14T10:00:00.000Z",
"updated_at": "2026-09-14T10:00:01.000Z"
}
}Purchase - Payments API
Charge a card in one step by authorizing and capturing the payment together. A duplicate request ID returns the original response.
#!/usr/bin/env bash
# Purchase (authorise + capture in one call). 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/purchase" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
-d @request.json#!/usr/bin/env python3
"""Purchase (authorise + capture in one call). Python 3.10+, requests.
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 (or poll GET /v1/transactions/{id}/status) — never mint a new
request_id for the same order 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_purchase(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/purchase", json=body, headers=headers, timeout=30)
except requests.exceptions.Timeout:
if attempt == max_attempts:
raise
time.sleep(backoff_seconds(attempt))
continue # network timeout: retry with the same body/request_id
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 # retry with the same request_id
payload = resp.json()
if not resp.ok:
# 4xx: not retryable by re-sending — fix the request, or handle
# urn:radiumone:transaction:idempotency-body-mismatch if you changed it.
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"purchase failed: {code} ({resp.status_code})")
if payload["data"]["status"] == "PENDING":
if attempt == max_attempts:
return payload # caller should poll GET status / wait for webhook
time.sleep(backoff_seconds(attempt))
continue # retry the same request_id
# Branch on data.status: CAPTURED (success) | DECLINED (final, no retry) | FAILED.
return payload
raise RuntimeError("unreachable")
if __name__ == "__main__":
print(json.dumps(create_purchase(), indent=2))
{
"status": "ok",
"request_id": "req_7a8b9c0d1e2f",
"data": {
"id": "8f1c2e10-4b3a-4c5d-9e6f-7a8b9c0d1e2f",
"request_id": "ord-1001-pay-1",
"type": "PURCHASE",
"status": "CAPTURED",
"amount": 5000,
"currency": "SGD",
"payment_method_type": "card",
"order_reference": "ORD-1001",
"response_code": "00",
"parent_transaction_id": null,
"switch_request_id": "sw-8f1c2e10",
"created_at": "2026-09-14T10:00:00.000Z",
"updated_at": "2026-09-14T10:00:01.000Z"
}
}Authorizations
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.
Body
Request body for POST /v1/transactions/purchase.
Atomic sale: authorise then immediately capture in a single API call. Idempotent via request_id scoped to the authenticated merchant.
Amount to charge for this sale, as a {currency, value} money object.
Show child attributes
Show child attributes
Card group carrying the network token (no raw PAN).
Show child attributes
Show child attributes
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).
CARD_PRESENT, ECOMMERCE, MOTO, PAYMENT_LINK, IN_APP, RECURRING Merchant-supplied idempotency key; replays return the original response.
8 - 64Purchase always auto-captures. Must be true (v1).
EMV chip data read from the card, for card-present sales. 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.
Redeem loyalty points as part of a purchase.
Include this on a purchase to pay for part (or all) of the sale with loyalty points, optionally naming the pools to draw from and any vouchers to apply. It is accepted on purchase only -- not on authorization or capture -- and the sale must be routed to an acquirer that has a loyalty programme linked, otherwise the request is rejected before any payment is attempted.
- LoyaltyRedemptionRequest
- LoyaltyRedemptionVoucherRequest
- LoyaltyRedemptionCouponRequest
Show child attributes
Show child attributes
Optional merchant-supplied metadata (max 10 KB, max 5 depth levels).
Merchant's order/cart reference for this payment (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.
1283DS result (one of {ref} | {mode:non_payer_auth} | {cavv,...}); absent == non-payer-auth.
Show child attributes
Show child attributes
Response
Successful Response
Standard success envelope. Every successful response has this shape, with the operation's own payload under data.
The operation's result. Its shape is documented per operation; omitted on responses that carry no payload.
Show child attributes
Show child attributes
Optional human-readable note. Omitted from the response when not set, which is the case for every payment operation today. Never parse it.
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.
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.