#!/usr/bin/env bash
# Capture a prior authorization (must equal the authorized amount in v1). Any
# 2xx is a response — branch on data.status. On no response or any 5xx (even
# retry_allowed: false), resend this exact request with the SAME operation_id:
# the replay is a lookup that recovers the outcome, never a second capture.
# A 409 tx:invalid-state-transition on that retry means the capture timed out
# and RadiumOne is reversing that capture: once the hold is AUTHORIZED again,
# retry with the same operation_id.
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}"
: "${RADIUMONE_TRANSACTION_ID:?set RADIUMONE_TRANSACTION_ID to the id of the AUTHORIZED transaction}"
curl -sS -X POST "$API_BASE/v1/transactions/$RADIUMONE_TRANSACTION_ID/capture" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
-d @request.json
#!/usr/bin/env python3
"""Capture a prior authorization (must equal the authorized amount in v1).
Shared result pattern: any 2xx is a response you branch on ``status``.
On no response or any 5xx -- even retry_allowed: false -- replay the SAME
operation_id with the identical body. The replay is a lookup, not a resend:
RadiumOne returns the recorded outcome, or asks the card network for the stored
one, and only sends the capture if the network never received it.
"""
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")
OUTCOME_IN_DOUBT = "urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt"
INVALID_STATE = "urn:radiumone:payment-gateway:tx:invalid-state-transition"
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 capture_authorization(max_attempts: int = 3) -> dict:
body = json.loads((Path(__file__).parent / "request.json").read_text())
transaction_id = os.environ["RADIUMONE_TRANSACTION_ID"]
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/{transaction_id}/capture", json=body, headers=headers, timeout=30
)
except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as exc:
# No response: replay the same operation_id (a lookup, never a second capture).
if attempt == max_attempts:
raise RuntimeError(f"no response after {attempt} attempts -- wait for the webhook") from exc
time.sleep(backoff_seconds(attempt))
continue
if resp.status_code >= 500:
try:
problem = resp.json()
except ValueError:
problem = {}
# Any 5xx -- even retry_allowed: false (switch-timeout, database-unavailable):
# the same-operation_id replay recovers the outcome instead of capturing again.
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
payload = resp.json()
if resp.status_code == 409 and payload.get("type") == OUTCOME_IN_DOUBT:
# An earlier capture or void on this transaction has no recorded outcome.
# Resend that request (its own operation_id and body) first, then this one.
raise RuntimeError(f"resend the pending {payload.get('pending_operation')} {payload.get('pending_operation_id')} first")
if resp.status_code == 409 and payload.get("type") == INVALID_STATE:
# The authorization isn't AUTHORIZED right now. After a capture that timed out
# and may have reached the card network, RadiumOne reverses that capture (never
# the authorization): once the hold is AUTHORIZED again, retry this same operation_id.
raise RuntimeError("authorization not capturable right now -- check its status, retry later with the same operation_id")
if not resp.ok:
# 422 tx:capture-window-expired if the capture window has passed.
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"capture failed: {code} ({resp.status_code})")
return payload # branch on data.status
raise RuntimeError("unreachable")
if __name__ == "__main__":
print(json.dumps(capture_authorization(), indent=2))
{
"status": "ok",
"request_id": "req_ord1002cap1a",
"data": {
"id": "1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081",
"request_id": "ord-1002-auth-1",
"type": "AUTHORIZE",
"status": "CAPTURED",
"amount": 10000,
"currency": "SGD",
"currency_minor_units": 2,
"payment_method_type": "card",
"order_reference": "ORD-1002",
"response_code": "00",
"auth_code": "D4E5F6",
"rrn": "427310000201",
"parent_transaction_id": null,
"switch_request_id": "sw-ord-1002-cap-1",
"created_at": "2026-09-14T10:00:00.000Z",
"updated_at": "2026-09-14T10:05:01.000Z"
}
}{
"detail": "Request payload failed validation.",
"status": 400,
"title": "Validation Error",
"type": "urn:radiumone:payment-gateway:validation-error"
}{
"detail": "Missing or invalid Bearer token.",
"status": 401,
"title": "Authentication Required",
"type": "urn:radiumone:payment-gateway:authentication-required"
}{
"detail": "Insufficient permissions for this operation.",
"status": 403,
"title": "Permission Denied",
"type": "urn:radiumone:payment-gateway:permission-denied"
}{
"detail": "The requested resource does not exist.",
"status": 404,
"title": "Not Found",
"type": "urn:radiumone:payment-gateway:not-found"
}{
"detail": "The transaction's terminal cannot take the operation: `urn:radiumone:payment-gateway:settlement:device-settling` (its batch is settling; `retry_allowed: true`, `resolution: transient`), `urn:radiumone:payment-gateway:settlement:device-batch-rejected` or `urn:radiumone:payment-gateway:settlement:stuck-reversals` (`resolution: operator`), or `urn:radiumone:payment-gateway:routing:operation-disabled` (the operation is switched off on the terminal; `resolution: operator`). Also `urn:radiumone:payment-gateway:tx:invalid-state-transition` (the transaction is not in a state that allows the operation), `urn:radiumone:payment-gateway:tx:duplicate-operation` (`operation_id` was already used for a different operation on this transaction) and `urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt` (an earlier capture or void on this transaction has no recorded outcome -- resend it with its own `operation_id` first; `pending_operation_id` names it). `urn:radiumone:payment-gateway:tx:auth-expired-during-capture`: the authorisation expired while the capture was in flight -- create a new authorisation.",
"status": 409,
"title": "Conflict",
"type": "urn:radiumone:payment-gateway:settlement:device-settling"
}{
"detail": "The payment token has expired or its card data is no longer available.",
"status": 410,
"title": "Gone",
"type": "urn:radiumone:payment-gateway:token:data-purged"
}{
"detail": "`urn:radiumone:payment-gateway:tx:capture-amount-mismatch` (capture is full-amount only), `urn:radiumone:payment-gateway:tx:amount-exceeds-authorized`, `urn:radiumone:payment-gateway:tx:currency-mismatch`, `urn:radiumone:payment-gateway:tx:capture-window-expired`, or `urn:radiumone:payment-gateway:routing:capability-not-supported` (the acquirer does not support capture on this channel). A retry does not help.",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:tx:capture-amount-mismatch"
}{
"detail": "An unexpected error occurred.",
"status": 500,
"title": "Internal Server Error",
"type": "urn:radiumone:payment-gateway:internal-error"
}{
"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. Also `urn:radiumone:payment-gateway:routing:original-acquirer-unavailable`: the acquirer that processed the original transaction is temporarily unavailable; nothing was sent.",
"status": 503,
"title": "Service Unavailable",
"type": "urn:radiumone:payment-gateway:service-unavailable"
}Capture - Payments API
Capture funds from an authorized transaction within its capture window. Retrying with the same operation ID returns the original result.
#!/usr/bin/env bash
# Capture a prior authorization (must equal the authorized amount in v1). Any
# 2xx is a response — branch on data.status. On no response or any 5xx (even
# retry_allowed: false), resend this exact request with the SAME operation_id:
# the replay is a lookup that recovers the outcome, never a second capture.
# A 409 tx:invalid-state-transition on that retry means the capture timed out
# and RadiumOne is reversing that capture: once the hold is AUTHORIZED again,
# retry with the same operation_id.
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}"
: "${RADIUMONE_TRANSACTION_ID:?set RADIUMONE_TRANSACTION_ID to the id of the AUTHORIZED transaction}"
curl -sS -X POST "$API_BASE/v1/transactions/$RADIUMONE_TRANSACTION_ID/capture" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
-d @request.json
#!/usr/bin/env python3
"""Capture a prior authorization (must equal the authorized amount in v1).
Shared result pattern: any 2xx is a response you branch on ``status``.
On no response or any 5xx -- even retry_allowed: false -- replay the SAME
operation_id with the identical body. The replay is a lookup, not a resend:
RadiumOne returns the recorded outcome, or asks the card network for the stored
one, and only sends the capture if the network never received it.
"""
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")
OUTCOME_IN_DOUBT = "urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt"
INVALID_STATE = "urn:radiumone:payment-gateway:tx:invalid-state-transition"
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 capture_authorization(max_attempts: int = 3) -> dict:
body = json.loads((Path(__file__).parent / "request.json").read_text())
transaction_id = os.environ["RADIUMONE_TRANSACTION_ID"]
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/{transaction_id}/capture", json=body, headers=headers, timeout=30
)
except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as exc:
# No response: replay the same operation_id (a lookup, never a second capture).
if attempt == max_attempts:
raise RuntimeError(f"no response after {attempt} attempts -- wait for the webhook") from exc
time.sleep(backoff_seconds(attempt))
continue
if resp.status_code >= 500:
try:
problem = resp.json()
except ValueError:
problem = {}
# Any 5xx -- even retry_allowed: false (switch-timeout, database-unavailable):
# the same-operation_id replay recovers the outcome instead of capturing again.
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
payload = resp.json()
if resp.status_code == 409 and payload.get("type") == OUTCOME_IN_DOUBT:
# An earlier capture or void on this transaction has no recorded outcome.
# Resend that request (its own operation_id and body) first, then this one.
raise RuntimeError(f"resend the pending {payload.get('pending_operation')} {payload.get('pending_operation_id')} first")
if resp.status_code == 409 and payload.get("type") == INVALID_STATE:
# The authorization isn't AUTHORIZED right now. After a capture that timed out
# and may have reached the card network, RadiumOne reverses that capture (never
# the authorization): once the hold is AUTHORIZED again, retry this same operation_id.
raise RuntimeError("authorization not capturable right now -- check its status, retry later with the same operation_id")
if not resp.ok:
# 422 tx:capture-window-expired if the capture window has passed.
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"capture failed: {code} ({resp.status_code})")
return payload # branch on data.status
raise RuntimeError("unreachable")
if __name__ == "__main__":
print(json.dumps(capture_authorization(), indent=2))
{
"status": "ok",
"request_id": "req_ord1002cap1a",
"data": {
"id": "1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081",
"request_id": "ord-1002-auth-1",
"type": "AUTHORIZE",
"status": "CAPTURED",
"amount": 10000,
"currency": "SGD",
"currency_minor_units": 2,
"payment_method_type": "card",
"order_reference": "ORD-1002",
"response_code": "00",
"auth_code": "D4E5F6",
"rrn": "427310000201",
"parent_transaction_id": null,
"switch_request_id": "sw-ord-1002-cap-1",
"created_at": "2026-09-14T10:00:00.000Z",
"updated_at": "2026-09-14T10:05:01.000Z"
}
}{
"detail": "Request payload failed validation.",
"status": 400,
"title": "Validation Error",
"type": "urn:radiumone:payment-gateway:validation-error"
}{
"detail": "Missing or invalid Bearer token.",
"status": 401,
"title": "Authentication Required",
"type": "urn:radiumone:payment-gateway:authentication-required"
}{
"detail": "Insufficient permissions for this operation.",
"status": 403,
"title": "Permission Denied",
"type": "urn:radiumone:payment-gateway:permission-denied"
}{
"detail": "The requested resource does not exist.",
"status": 404,
"title": "Not Found",
"type": "urn:radiumone:payment-gateway:not-found"
}{
"detail": "The transaction's terminal cannot take the operation: `urn:radiumone:payment-gateway:settlement:device-settling` (its batch is settling; `retry_allowed: true`, `resolution: transient`), `urn:radiumone:payment-gateway:settlement:device-batch-rejected` or `urn:radiumone:payment-gateway:settlement:stuck-reversals` (`resolution: operator`), or `urn:radiumone:payment-gateway:routing:operation-disabled` (the operation is switched off on the terminal; `resolution: operator`). Also `urn:radiumone:payment-gateway:tx:invalid-state-transition` (the transaction is not in a state that allows the operation), `urn:radiumone:payment-gateway:tx:duplicate-operation` (`operation_id` was already used for a different operation on this transaction) and `urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt` (an earlier capture or void on this transaction has no recorded outcome -- resend it with its own `operation_id` first; `pending_operation_id` names it). `urn:radiumone:payment-gateway:tx:auth-expired-during-capture`: the authorisation expired while the capture was in flight -- create a new authorisation.",
"status": 409,
"title": "Conflict",
"type": "urn:radiumone:payment-gateway:settlement:device-settling"
}{
"detail": "The payment token has expired or its card data is no longer available.",
"status": 410,
"title": "Gone",
"type": "urn:radiumone:payment-gateway:token:data-purged"
}{
"detail": "`urn:radiumone:payment-gateway:tx:capture-amount-mismatch` (capture is full-amount only), `urn:radiumone:payment-gateway:tx:amount-exceeds-authorized`, `urn:radiumone:payment-gateway:tx:currency-mismatch`, `urn:radiumone:payment-gateway:tx:capture-window-expired`, or `urn:radiumone:payment-gateway:routing:capability-not-supported` (the acquirer does not support capture on this channel). A retry does not help.",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:tx:capture-amount-mismatch"
}{
"detail": "An unexpected error occurred.",
"status": 500,
"title": "Internal Server Error",
"type": "urn:radiumone:payment-gateway:internal-error"
}{
"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. Also `urn:radiumone:payment-gateway:routing:original-acquirer-unavailable`: the acquirer that processed the original transaction is temporarily unavailable; nothing was sent.",
"status": 503,
"title": "Service Unavailable",
"type": "urn:radiumone:payment-gateway:service-unavailable"
}Authorizations
Body
Request body for POST /v1/transactions/{id}/capture.
Full capture only in v1. amount must equal the authorised amount. Idempotent via operation_id scoped to the parent transaction.
Response
Successful Response
Standard success envelope. Every successful response has this shape, with the operation's own payload under data.
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.