#!/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. Even after a
# 5xx with retry_allowed: false, a same-request_id replay is a lookup, not a
# resend -- it never charges the card again.
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, any 5xx, or status 'PENDING'/'REVERSAL_PENDING', replay the
SAME request_id -- never mint a new one for the same attempt. A same-request_id
replay is a lookup: RadiumOne returns the recorded attempt and never sends the
payment again, so it's safe even after a 5xx that says ``retry_allowed: false``
(e.g. switch-timeout). Until the outcome settles it can keep returning PENDING
or REVERSAL_PENDING -- then wait for the webhook.
"""
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 _problem(resp: requests.Response) -> dict:
try:
return resp.json()
except ValueError:
return {}
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, requests.exceptions.ConnectionError):
if attempt == max_attempts:
raise
time.sleep(backoff_seconds(attempt))
continue # no response (timeout or connection reset): retry with the same body/request_id
if resp.status_code >= 500:
problem = _problem(resp)
# Any 5xx -- even retry_allowed: false (switch-timeout, database-unavailable):
# replaying the SAME request_id is a lookup, not a resend, so it never
# charges the card again. Out of attempts? Wait for the webhook.
if attempt == max_attempts:
raise RuntimeError(f"{problem.get('type') or 'server error'} ({resp.status_code}) after {attempt} attempts -- wait for the webhook")
time.sleep(backoff_seconds(attempt))
continue # replay the same request_id (a lookup, never a second charge)
payload = resp.json()
if not resp.ok:
# 4xx: not retryable by re-sending — fix the request, or handle
# urn:radiumone:payment-gateway:transaction:duplicate-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"] in ("PENDING", "REVERSAL_PENDING"):
if attempt == max_attempts:
return payload # not final yet: wait for the webhook
time.sleep(backoff_seconds(attempt))
continue # retry the same request_id
# Branch on data.status: CAPTURED (success) | DECLINED (final, no retry) |
# FAILED (host didn't approve; retry with a new request_id, but fix the
# request first if response_code is "**") | PENDING/REVERSAL_PENDING (wait).
return payload
raise RuntimeError("unreachable")
if __name__ == "__main__":
print(json.dumps(create_purchase(), indent=2))
Charge a card in one step by authorizing and capturing the payment together. A duplicate request ID returns the original response.
POST
/
v1
/
transactions
/
purchase
cURL
#!/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. Even after a
# 5xx with retry_allowed: false, a same-request_id replay is a lookup, not a
# resend -- it never charges the card again.
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, any 5xx, or status 'PENDING'/'REVERSAL_PENDING', replay the
SAME request_id -- never mint a new one for the same attempt. A same-request_id
replay is a lookup: RadiumOne returns the recorded attempt and never sends the
payment again, so it's safe even after a 5xx that says ``retry_allowed: false``
(e.g. switch-timeout). Until the outcome settles it can keep returning PENDING
or REVERSAL_PENDING -- then wait for the webhook.
"""
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 _problem(resp: requests.Response) -> dict:
try:
return resp.json()
except ValueError:
return {}
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, requests.exceptions.ConnectionError):
if attempt == max_attempts:
raise
time.sleep(backoff_seconds(attempt))
continue # no response (timeout or connection reset): retry with the same body/request_id
if resp.status_code >= 500:
problem = _problem(resp)
# Any 5xx -- even retry_allowed: false (switch-timeout, database-unavailable):
# replaying the SAME request_id is a lookup, not a resend, so it never
# charges the card again. Out of attempts? Wait for the webhook.
if attempt == max_attempts:
raise RuntimeError(f"{problem.get('type') or 'server error'} ({resp.status_code}) after {attempt} attempts -- wait for the webhook")
time.sleep(backoff_seconds(attempt))
continue # replay the same request_id (a lookup, never a second charge)
payload = resp.json()
if not resp.ok:
# 4xx: not retryable by re-sending — fix the request, or handle
# urn:radiumone:payment-gateway:transaction:duplicate-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"] in ("PENDING", "REVERSAL_PENDING"):
if attempt == max_attempts:
return payload # not final yet: wait for the webhook
time.sleep(backoff_seconds(attempt))
continue # retry the same request_id
# Branch on data.status: CAPTURED (success) | DECLINED (final, no retry) |
# FAILED (host didn't approve; retry with a new request_id, but fix the
# request first if response_code is "**") | PENDING/REVERSAL_PENDING (wait).
return payload
raise RuntimeError("unreachable")
if __name__ == "__main__":
print(json.dumps(create_purchase(), indent=2))
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).
Available options:
CARD_PRESENT,
ECOMMERCE,
MOTO,
PAYMENT_LINK,
IN_APP,
RECURRING
request_id
string
required
Merchant-supplied idempotency key; replays return the original response.
Required string length: 8 - 64
authorization_options
AuthorizationOptions · object | null
Forced Capture: complete a sale already approved outside this API (voice or referral authorization) by sending the approval code you were given. Requires the forced-capture permission. Cannot be combined with three_ds or loyalty.
Show child attributes
auto_capture
boolean
default:true
Purchase always auto-captures. Must be true (v1).
emv
stringEmv · object
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.
loyalty
LoyaltyRedemptionRequest · object
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
metadata
Metadata · object | null
Optional merchant-supplied metadata (max 10 KB, max 5 depth levels).
order_reference
string | null
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.
Maximum string length: 128
outlet_id
string<uuid> | null
Outlet to transact on. Omit it to use the outlet your API key is bound to, or your DEFAULT outlet when the key is not bound. Sending the outlet your checkout session was created for makes the sale route exactly as that session's payment methods were discovered. A key bound to a different outlet is refused with 403 urn:radiumone:payment-gateway:auth:outlet-binding-violation. Part of the idempotency key only when sent: a retry of the same request_id naming a different outlet is refused with 409.
selected_payment_method
string | null
Recommended -- it will become required. The payment method your shopper chose: one of the payment_methods[].type values returned for the checkout session (card for an ordinary card sale, including instalments; uob_irr for a sale that redeems loyalty rewards). Once it is required, omitting it returns 422 urn:radiumone:payment-gateway:checkout:payment-method-required, except on an idempotent replay of a request originally accepted without it. When sent, a method not offered here returns 422 urn:radiumone:payment-gateway:checkout:payment-method-not-offered (reason: not_offered or unknown). Part of the idempotency key only when sent. Not echoed on the response.
Maximum string length: 32
three_ds
ThreeDsPurchaseInput · object | null
3DS result (one of {ref} | {mode:unauthenticated} | {cavv,...}); absent == unauthenticated.
Show child attributes
Response
Successful Response
Standard success envelope. Every successful response has this shape, with the operation's own payload under data.
data
TransactionResponse · 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.