FAILED: a decline (data.status: "DECLINED") is the acquirer’s 00 approval code’s counterpart in a defined set of decline codes. Every other non-00 code — including gateway- or host-level errors — maps to FAILED instead, which carries a different meaning (it isn’t a card decline; on a purchase it still means the host didn’t approve it, so retry with a new request_id — including response_code: "99" when the payment network was too busy to take the request, see Rate limits. The exception is response_code: "**": the request itself was rejected, so fix it before you try again). See Payment lifecycle for the full mapping.
How declines appear
- Payments API (purchase, authorize, standalone refund):
201withdata.status: "DECLINED"and a verbatimdata.response_codefrom the acquirer. - Hosted checkout: the checkout session’s
statusbecomesfailed; the shopper is returned to your rawcancel_url— see Verify the payment result. - Webhooks:
authorization.declined,payment.declined, orrefund.declined— see Webhook event types.
status — never on response_code (that’s the verbatim host/acquirer code; useful for support tickets, not for your app logic).
After a timeout or a
5xx, replay with the same key. For every payment operation — purchase, authorize, capture, void, and both refunds — a replay of the identical request with the same request_id or operation_id is a lookup, not a resend, so it’s safe even after a 5xx that says retry_allowed: false (switch-timeout, database-unavailable). RadiumOne returns the outcome it recorded. If a capture, void, or referenced refund was sent but its outcome wasn’t recorded, RadiumOne asks the card network for the stored outcome instead of sending it again, and sends it only if the network never received it — so nothing is applied twice. A replay can return PENDING or REVERSAL_PENDING until the outcome settles. A request RadiumOne refused before it reached the card network (for example with device-settling or device-busy) is run again on the same transaction instead of returning a stored result — no second transaction is created. A capture that timed out after it may have reached the card network is reversed — the capture, never the authorization under it: while that reversal is open (REVERSAL_PENDING), a same-operation_id retry gets 409 tx:invalid-state-transition; once it clears, the hold is back to AUTHORIZED and the retry is sent as a new capture attempt. A capture that timed out before it left RadiumOne is sent as a new attempt on a same-operation_id retry — nothing was sent the first time. A void that timed out is reversed too: while that reversal is open, a retry gets 409 transaction:void-reversal-pending (retry_allowed: true); once it clears, the sale is back to CAPTURED and the retry is sent as a new attempt. While that earlier capture, void, or refund is unresolved, a follow-up with a different key on the same transaction gets 409 urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt: resend the pending request first. See Handle timeouts and unknown outcomes.PENDING means the outcome isn’t known yet — most often after a processor timeout. Don’t assume success or failure. Recover it one of two ways:
- Wait for a webhook (
payment.*,authorization.*,refund.*— see Webhook event types). - Poll
GET /v1/transactions/{id}/status— it returns the transaction as RadiumOne holds it. Poll every 60 seconds while it readsPENDINGorREVERSAL_PENDING, and contact support if it isn’t final 60 minutes after your server sent the original request;INCONSISTENTmeans stop and contact support; anything else is final. See Check a transaction’s status.
id yet — a client-side timeout before the first response arrived — replay the same purchase, authorize, or refund with the same request_id and body. The replay is a lookup, not a resend: it returns the stored transaction and its id, whatever status it’s reached, including PENDING or REVERSAL_PENDING. A capture or void replayed with the same operation_id works the same way, and for a capture, void, or referenced refund whose outcome wasn’t recorded, RadiumOne checks with the card network before sending anything. Never re-submit with a new idempotency key just because the first attempt is slow — that risks a second charge for the same order.
Branch on status, never response_code
response_code is the verbatim acquirer/host response code. It’s useful to
hand to support when investigating a specific transaction — never use it to
drive your own application logic. RadiumOne doesn’t currently expose a
normalized decline classification, a shopper-safe customer_message, or a
retry_allowed flag on declines . Treat every
DECLINED result the same way in code: it’s final for this attempt.
Shopper messaging
Don’t show the acquirer’s rawresponse_code, or any other RadiumOne-internal
detail, to the shopper. Use a generic message — for example, “Your payment
couldn’t be completed. Try a different card or payment method.” — and let
your own support tooling look up response_code later if you need to
investigate.
Retry guidance
- A decline is final for this attempt. Don’t retry the same
request_idhoping for a different outcome — a replay returns the identical decline. - A genuinely new attempt — the shopper enters a different card, or
changes something and tries again — is a new payment: mint a new
request_idfor it. - Never treat a timeout, a
5xx, or aPENDINGresult as a decline. Those aren’t declines at all. Retry with the samerequest_id(oroperation_id), or poll status, per Timeouts and retries. Minting a new key after a timeout risks a duplicate charge; minting one after a genuine decline is correct.
Response code "**": request rejected before the acquirer
response_code: "**" isn’t an acquirer code — acquirer codes are always two
letters or digits. RadiumOne sets it when its payment network rejected the
request before it reached the acquirer, for example because a field failed
validation there. The transaction is FAILED (webhook payment.failed for a
purchase):
- Nothing was charged, and nothing needs reversing — no acquirer or card issuer saw the request.
- Don’t retry the same request unchanged. It fails the same way every
time, whether you replay the
request_id(you get the sameFAILEDback) or send the same body with a new one. - Fix the request, then send it with a new
request_id. Check the body against the API reference — amounts, currency,order_reference, and anyloyaltyor 3D Secure data. The network’s explanation is recorded on the transaction, but it isn’t in the API response or the webhook: if you can’t find the problem, contact support with the transactionid. - Show the shopper the same generic “couldn’t be completed” message as for a decline. The fix is on your side, so a shopper retry won’t help until then.
response_code: "99" on a FAILED purchase, where
the payment network was too busy to take the request: that one you retry
with a new request_id after a short delay (Rate
limits).
Publishable decline codes
RadiumOne hasn’t finalized which acquirer response codes are safe to publish as a lookup table . Until that’s settled, this page documents behavior and handling guidance only — build your branching logic onstatus, not on a hardcoded response-code table.
Test your integration
Use the decline test cards in Test your integration to exercise this path in sandbox.Next steps
Problem format and retries
HTTP status guide and retry rules for actual errors, plus links to the full URN catalog.
Charge or authorize a payment
See the full decline response shape.
Handle declined payments
The step-by-step scenario walkthrough.