Skip to main content
A decline means the card issuer or acquirer refused the payment. It is not an error response — RadiumOne returns it as a normal successful result so your code can’t miss it by only checking for HTTP-level errors. A decline is different from 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): 201 with data.status: "DECLINED" and a verbatim data.response_code from the acquirer.
  • Hosted checkout: the checkout session’s status becomes failed; the shopper is returned to your raw cancel_url — see Verify the payment result.
  • Webhooks: authorization.declined, payment.declined, or refund.declined — see Webhook event types.
Any 2xx response is a result you must branch on 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.
Balance inquiry also takes a request_id field, but it isn’t an idempotency key — there’s no dedup or replay store. Every call re-queries the rewards host, even with the same request_id.
Keys are 8–64 characters, [a-zA-Z0-9-] only, unique per merchant account. Generate one key per order attempt and persist it to your database before you send the first request — never mint a new key just to retry the same attempt. See Prevent duplicate payments.
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:
  1. Wait for a webhook (payment.*, authorization.*, refund.* — see Webhook event types).
  2. Poll GET /v1/transactions/{id}/status — it returns the transaction as RadiumOne holds it. Poll every 60 seconds while it reads PENDING or REVERSAL_PENDING, and contact support if it isn’t final 60 minutes after your server sent the original request; INCONSISTENT means stop and contact support; anything else is final. See Check a transaction’s status.
If you don’t have the transaction 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 raw response_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_id hoping 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_id for it.
  • Never treat a timeout, a 5xx, or a PENDING result as a decline. Those aren’t declines at all. Retry with the same request_id (or operation_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 same FAILED back) 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 any loyalty or 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 transaction id.
  • 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.
This is different from 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 on status, 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.
Last modified on September 29, 2026