Decline codes - Payments API

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, and isn’t a guarantee that no funds moved). 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).

Status	Meaning	What to do
`AUTHORIZED`	Funds reserved (authorize only)	Capture within the capture window, or void to release
`CAPTURED`	Funds captured (purchase, capture, or refund)	Fulfil the order (or process the refund)
`VOIDED`	Authorization released	No funds moved
`DECLINED`	Issuer or acquirer declined	Final for this attempt — don’t retry the same card without a new attempt from the shopper
`FAILED`	The transaction didn’t complete — the acquirer returned a non-decline error code, or the gateway couldn’t place the request. Not a guarantee that no funds moved — `VOIDED` and `REVERSED` are the only statuses that positively assert that.	Confirm via `GET /v1/transactions/{id}/status` before retrying, then retry (a genuinely new attempt, not a replay of the same `request_id`) with a new `request_id`
`PENDING`	Outcome not yet known (async)	Wait for a webhook, or poll `GET /v1/transactions/{id}/status`
`AUTH_EXPIRED`	Authorization lapsed before capture	Create a new authorization
`REVERSAL_PENDING` / `REVERSED`	Automatic compensating reversal after an upstream timeout left the outcome genuinely unknown (never left `FAILED` in this case)	No merchant action; webhook confirms the final state

Key	Used by	On replay
`request_id`	Purchase, authorize, standalone and referenced refunds	Same body, same operation type → the original transaction, whatever its status — including `PENDING`, `DECLINED`, or `FAILED`. Changed body, or the same key reused for a different operation type → `transaction:idempotency-body-mismatch`. Purchase/authorize/standalone-refund compare `amount`, `currency`, `payment_method_type`, `channel`, the card’s `pan_prefix` (first 8 digits — not the full token), `metadata`, and `order_reference`; a referenced refund compares only the original transaction and `amount` (`reason` isn’t compared) and its replay check runs before the refund gates, so it always replays, even a `DECLINED`/`FAILED` one — mint a new `request_id` to retry after a decline. None of these compare `three_ds` or `loyalty`, so changing either on a retry replays the original silently instead of failing.
`operation_id`	Capture, void	Same operation type on the same transaction → the original result (body is never compared, so a changed amount is silently ignored). A different operation type reusing the key → `tx:duplicate-operation`.

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:

Wait for a webhook (payment.*, authorization.*, refund.* — see Webhook event types).
Call GET /v1/transactions/{id}/status for a live inquiry against the acquirer.

If you don’t have the transaction id yet — a client-side timeout before the first response arrived — replay the same request with the same request_id and body. The replay returns the stored transaction and its id, whatever status it’s reached. 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.

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.

Introduction

Guides

Payment methods

3D Secure

Handle failures

Webhooks

Errors

Reference

Decline codes - Payments API

How declines appear

Branch on `status`, never `response_code`

Shopper messaging

Retry guidance

Publishable decline codes

Test your integration

Next steps

Problem format and retries

Charge or authorize a payment

Handle declined payments

​How declines appear

​Branch on status, never response_code

​Shopper messaging

​Retry guidance

​Publishable decline codes

​Test your integration

​Next steps

Problem format and retries

Charge or authorize a payment

Handle declined payments

How declines appear

Branch on `status`, never `response_code`

Shopper messaging

Retry guidance

Publishable decline codes

Test your integration

Next steps