Radial → Gr4vy Credit Card Error Code Mapping
This document maps Radial’s credit card response codes and fault codes to their closest equivalents in Gr4vy’s normalized error_code schema. It covers two Radial error surfaces:
- Auth Response Codes — returned in the
<ResponseCode>element ofGetPaymentAuthorizationReply - Fault Response Codes — returned as exception class names in the
<Code>element of a<Fault>XML envelope
Part 1: Auth Response Codes
These are the high-level outcomes Radial returns from a credit card authorization. Gr4vy uses a richer, granular error_code field on the transaction object.
Radial ResponseCode | Radial Meaning | Gr4vy Equivalent error_code | Notes on Difference |
|---|---|---|---|
APPROVED | Authorization approved | (no error_code — transaction status = authorization_succeeded) | Gr4vy uses status rather than a response code for success. No error_code is set on a successful transaction. |
AcceptOrderWithException | Approved but flagged — must go through fraud review before shipment | (no direct equivalent — authorization_succeeded + fraud review flow) | Radial bundles AVS/CSC soft signals into this code. In Gr4vy, soft AVS/CVV mismatches surface as incorrect_billing_address or incorrect_cvv and are handled separately from transaction status. |
DECL | Generic decline (no specific reason) | issuer_decline or other_decline | issuer_decline when the bank explicitly rejects; other_decline for unknown/unspecified reasons. Both are retriable in Gr4vy. |
DECLF | Declined due to insufficient funds/credit | insufficient_funds | Direct 1:1 semantic match. Not marked retriable in Gr4vy (customer needs to resolve). |
DECLR | Declined — card reported lost or stolen | canceled_payment_method | Best match — covers reported-lost/stolen/frozen cards. Gr4vy also has unavailable_payment_method for frozen/blocked cards which may overlap. |
AVS | Billing address could not be validated | incorrect_billing_address | Direct 1:1 match. Gr4vy also has missing_billing_address (address absent entirely) and invalid_billing_address (malformed). |
CSC | Card security code could not be validated | incorrect_cvv | Direct 1:1 match. Gr4vy also has missing_cvv for absent CVV. |
AVSCSC | Both address AND security code failed | incorrect_billing_address + incorrect_cvv | Gr4vy emits one error_code per transaction, so this combined case would surface as whichever check the downstream processor reported first. Merchants should check raw_response_code for full detail. |
PaymentProcessorTimeout | Processor did not respond (timeout) | service_network_error | Direct semantic match. Gr4vy marks this retriable — align with Radial’s retry-before-accept logic. |
Part 2: Fault Response Codes (Pre-Authorization Validation Exceptions)
These are thrown before the transaction even reaches the issuer — they are Radial-layer validation failures. Gr4vy handles the equivalent cases mostly as invalid_request_parameters, connector failure codes, or Embed/API validation errors.
| Radial Fault Code | Radial Meaning | Gr4vy Equivalent error_code | Notes on Difference |
|---|---|---|---|
PanDoesNotPassLuhnCheckException / PanFailsLuhnCheckException | PAN fails Luhn algorithm check | invalid_payment_method or unrecognised_payment_method | Gr4vy’s Secure Fields / Embed validates card number client-side before submission. A Luhn failure typically never reaches the API — it’s caught in the UI. If it does reach the API, invalid_payment_method or invalid_request_parameters is returned. |
UnknownPanBinRangeException | PAN BIN not recognized for the tender type | unrecognised_scheme or unrecognised_payment_method | Gr4vy normalizes BIN-range rejection as an unrecognized scheme or payment method. unsupported_payment_method applies if the BIN is valid but not enabled for the merchant. |
PanTooShortException | PAN is too short | invalid_request_parameters | Structural validation — Gr4vy rejects malformed payloads at the API layer before routing. |
PanTooLongException | PAN is too long | invalid_request_parameters | Same as above. |
NonNumericDataException | PAN contains non-numeric characters | invalid_request_parameters | Same as above — caught at API validation layer. |
PanNotFoundException | PAN/token in request is invalid | unknown_payment_method or invalid_request_parameters | If a stored payment method token is invalid/expired, Gr4vy returns unknown_payment_method. If the raw PAN itself is structurally invalid, invalid_request_parameters. |
TokenNotFoundException | Token not found | unknown_payment_method | Direct match — Gr4vy uses unknown_payment_method when a stored/vaulted payment method ID cannot be located. |
InvalidCreditCardExpirationDateException | Expiration date is invalid | incorrect_expiry_date or invalid_request_parameters | incorrect_expiry_date when the expiry fails at the issuer; invalid_request_parameters when the format is structurally wrong. Gr4vy also has expired_payment_method for cards that have actually expired. |
InvalidCountryCodeException | Country code is incorrect | unrecognised_country or invalid_request_parameters | unrecognised_country for invalid ISO country codes; incorrect_country for issuer-rejected countries; unsupported_country if the service doesn’t support that country. |
InvalidTenderTypeException | Tender type is not CC | invalid_payment_method or invalid_request_parameters | Gr4vy uses payment method type in the request (e.g. card, paypal). Passing the wrong type maps to invalid_payment_method or a 400 bad_request API error. |
TenderGatewayConfigurationException | Store/merchant not configured for this tender type + country | invalid_service_configuration or insufficient_service_permissions | Both relate to misconfigured connector settings in Gr4vy. invalid_service_configuration is the closest for incorrect merchant-side config; insufficient_service_permissions if credentials lack the required scope. |
Part 3: Key Structural Differences to Be Aware Of
| Dimension | Radial | Gr4vy |
|---|---|---|
| Error format | XML <Fault> envelope with exception class name string | JSON error_code enum on the transaction object |
| Success signal | ResponseCode = APPROVED | status = authorization_succeeded (no error_code) |
| Soft declines (AVS/CVV) | Separate response codes (AVS, CSC, AVSCSC) with retry + accept logic | Separate error_code values (incorrect_billing_address, incorrect_cvv) — transaction is authorization_declined, not a soft-accept |
| Combined AVS+CVV | Single AVSCSC code | No combined code — one error_code per transaction; use raw_response_code for full detail |
| Pre-auth validation | Throws XML fault exceptions before hitting issuer | Caught at API layer (400 invalid_request_parameters) or in Secure Fields UI before submission |
| Fraud signals | DECLR (lost/stolen) and AcceptOrderWithException (fraud review) | canceled_payment_method (lost/stolen), suspected_fraud, flow_decline (Flow rules), refused_transaction (sanctions/watchlist) |
| Retryability | Configurable max-attempts per code, handled by webstore logic | Retriable? flag on each error_code in Gr4vy docs — built into the orchestration layer |
| Timeout handling | PaymentProcessorTimeout — retry up to N times, then accept with OMS retry | service_network_error — retriable; for digital wallets, do NOT retry (same as Radial’s Apple Pay guidance) |
| Configuration errors | TenderGatewayConfigurationException — store/country config | invalid_service_configuration, invalid_service_credentials, invalid_service_response — connector-level |
| Raw processor codes | Not surfaced in the fault/response layer | Available in raw_response_code and raw_response_description transaction fields |
Part 4: Gr4vy Codes With No Radial Equivalent
These Gr4vy error_code values represent functionality that Radial either does not expose or handles differently:
Gr4vy error_code | Why it has no Radial equivalent |
|---|---|
flow_decline | Gr4vy-specific — transaction declined by a Flow orchestration rule (fraud, routing logic) |
all_attempts_skipped | Gr4vy-specific — no Flow outcome could route the transaction |
incomplete_buyer_approval | Gr4vy redirect/3DS buyer abandoned the popup; Radial uses Cardinal Commerce externally |
failed_buyer_approval | 3DS authentication failure — Radial delegates this to third-party 3DS provider |
canceled_buyer_approval | Buyer explicitly canceled (e.g. closed Apple Pay sheet) |
duplicate_transaction | Gr4vy deduplication check; Radial does not surface this as a named fault |
refused_transaction | Sanctions / AML / watchlist block — Radial has no direct equivalent at the response-code layer |
service_rate_limit | Connector API rate limiting — not a Radial concept |
expired_authorization | Capture attempted on a stale auth — not surfaced as a named code in Radial |
refund_period_expired | Refund past the allowed window — Radial does not surface this as a named code |