Exirom Payment API Documentation

This guide provides a list of common decline and error codes encountered on the Exirom platform. These codes help technical users and developers understand why a transaction was declined or an error occurred. Each code has a brief description in simple terms. The codes are grouped into key categories for easier reference.

#Quick Reference: What To Do

Action	Codes	What You Should Do
Retry the transaction	1, 9, 12, 13, 61, 63, 70, 72, 73	Transient errors. Retry with same `requestId`, exponential backoff (2s, 4s, 8s). Max 3 retries.
Fix merchant-side issue	8, 14, 17, 24, 25, 26, 27, 30, 31, 65	Check your request payload. Fix the data and resubmit with a new `requestId`. Do not auto-retry.
Customer action needed	3, 4, 5, 6, 10, 19, 20, 21, 22, 23	Show a user-friendly message. Do not auto-retry — let the customer try again.
Contact Exirom support	7, 28, 29, 62, 64, 66, 67, 68, 69, 78, 400–404, 3006–3013	Include `transactionId` and `traceId` in your support ticket. Do not retry.

#Customer-Facing Messages by Code

Use these messages (or similar) to guide customers when their payment fails:

Code	Customer Message
3, 10, 19–23	"3D Secure verification failed. Please try again and complete the verification step."
4, 9	"Your session expired. Please try again."
5	"Insufficient funds. Please use a different card or top up your account."
6	"Your bank declined this transaction due to spending limits. Contact your bank or use another card."
2, 11, 75, 76, 82	"Your card was declined. Please try a different card or contact your bank."
79	"Your card has expired. Please use a different card."
1, 12, 13, 70, 72, 73	"Something went wrong. Please try again in a moment."

For a complete guide on retry logic and error recovery patterns, see the Error Recovery Patterns guide.

#Upstream Decline Codes

Upstream decline codes indicate issues reported by the issuing bank or payment gateway during processing. Common upstream codes include those for insufficient funds, fraud detection, 3-D Secure (3DS) errors, and technical failures.

Code	Code Name	Description
1	`UNEXPECTED_ERROR`	A generic or unknown error occurred.
2	`REJECTED_BY_ISSUER_BANK_ERROR`	The issuer bank rejected the transaction.
3	`THREE_DS_AUTHENTICATION_ERROR`	An error occurred during 3‑D Secure authentication.
4	`FORM_TIMEOUT_ERROR`	The payment form session timed out or expired.
5	`INSUFFICIENT_FUNDS_ERROR`	The account or card has insufficient funds.
6	`LIMITED_BY_ISSUER_BANK_ERROR`	The issuer bank’s limit prevented the transaction.
7	`ANTI_FRAUD_ERROR`	Flagged as fraudulent by the anti-fraud system.
8	`DATA_VALIDATION_ERROR`	Provided payment/card data failed validation checks.
9	`PREPAY_TIMEOUT_ERROR`	A timeout occurred during the pre-payment process.
10	`THREE_DS_PAGE_ERROR`	The 3‑D Secure page encountered an error and halted.
11	`PROCESSOR_DENIED`	The payment processor denied the transaction.
12	`GENERIC_PROCESSING_ERROR`	A generic error occurred during processing.
13	`TECHNICAL_GATEWAY_ERROR`	A technical error occurred at the payment gateway.
14	`DUPLICATED_ORDER_ID_ERROR`	The provided order ID is already in use (duplicate order).
15	`CURRENCY_EXCHANGE_NOT_ALLOWED_ERROR`	Currency conversion is not permitted for this transaction.
16	`GATE_NOT_FOUND_ERROR`	The specified payment gateway or channel was not found.
17	`ORDER_BILLING_ERROR`	There was an error in the order’s billing details.
18	`CARD_TIME_LIMIT_ERROR`	The allowable time window for the card transaction was exceeded.
19	`THREE_DS_TIMEOUT_ERROR`	The 3‑D Secure process timed out.
20	`THREE_DS_CANCEL_ERROR`	The 3‑D Secure process was canceled by the user or system.
21	`THREE_DS_REDIRECT_TIMEOUT`	The 3‑D Secure redirect process timed out.
22	`THREE_DS_REDIRECT_ERROR`	An error occurred during the 3‑D Secure redirect.
23	`THREE_DS_ABANDONED`	The 3‑D Secure process was abandoned before completion.
24	`CARD_INFORMATION_INVALID`	The card details provided are invalid.
25	`INVALID_CUSTOMER_REDIRECT_URL`	The customer redirect URL provided is invalid.
26	`INVALID_CALLBACK_URL`	The callback URL provided is invalid.
27	`CURRENCY_NOT_SUPPORTED`	The selected currency is not supported for this transaction.
28	`FRAUDULENT_TRANSACTION`	The transaction was flagged as fraudulent and rejected.
29	`MERCHANT_NOT_ACTIVE`	The merchant account is inactive or disabled.
30	`INVALID_CARD_HOLDER_DETAILS`	Cardholder details are incorrect or missing.
31	`INVALID_ORDER_AMOUNT`	The order amount is invalid or not allowed.
61	`INTERNAL_UNEXPECTED_ERROR`	An unknown error occurred in the internal system.
62	`INTERNAL_VALIDATION_ERROR`	The internal system failed a validation check.
63	`GATEWAY_UNEXPECTED_ERROR`	An unknown error occurred at the gateway.
64	`GATEWAY_ANTI_FRAUD_ERROR`	Flagged as fraudulent by the gateway’s anti-fraud system.
65	`GATEWAY_VALIDATION_ERROR`	Data failed validation checks at the gateway.
66	`GATEWAY_FX_CONVERSION_ERROR`	An error occurred during currency conversion at the gateway.
67	`GATEWAY_NO_DOWNSTREAM_GATEWAY_ERROR`	No downstream gateway was available to route the request.
68	`GATEWAY_DOWNSTREAM_GATEWAY_ERROR`	The downstream payment provider returned an error.
69	`GATEWAY_TRANSACTION_LIMIT_ERROR`	A gateway-imposed transaction limit blocked the request.
70	`GATEWAY_PROCESSING_ERROR`	A generic error occurred during gateway processing.
71	`GATEWAY_AUTHENTICATION_ERROR`	An authentication error occurred at the gateway.
72	`GATEWAY_TECHNICAL_ERROR`	A technical issue occurred at the gateway.
73	`GATEWAY_TIMEOUT_ERROR`	The gateway timed out while processing the transaction.
74	`GATEWAY_INSUFFICIENT_FUNDS`	The gateway reported insufficient funds.
75	`GATEWAY_CARD_DECLINED`	The gateway declined the card transaction.
76	`GATEWAY_ISSUER_DECLINED`	The card issuer (via gateway) declined the transaction.
77	`GATEWAY_DUPLICATE_REQUEST`	A duplicate transaction request was detected by the gateway.
78	`GATEWAY_POLICY_VIOLATION`	The transaction violated a gateway policy.
79	`GATEWAY_CARD_EXPIRED`	The card has expired.
80	`GATEWAY_REDIRECT_ERROR`	An error occurred during a gateway redirect.
81	`GATEWAY_LIMIT_EXCEEDED`	A gateway limit (threshold) was exceeded.
82	`GATEWAY_GENERAL_DECLINE`	The transaction was declined by the gateway for an unspecified reason.

#General Decline Codes

General decline codes are system-level errors or conditions not tied to a specific bank/gateway. These often indicate configuration issues or the absence of a valid processing route.

Code	Description
3001	Downstream service timeout (an external service did not respond in time).
3006	Merchant has no supported card networks (no enabled card types for this merchant).
3007	Configuration not found (required configuration is missing).
3010	No processors available (no payment processor was available to handle the request).
3011	BIN risk check result blocked (failed a BIN/risk rule).
3012	Payment transaction not found for refund (invalid or unknown transaction ID).
3013	The payment transaction has a non-success status (the transaction isn’t in a refundable state).

#Activable Decline Codes

Activable decline codes relate to account or configuration activation status. These errors occur if a required account or route is inactive or not properly set up.

Code	Description
400	The merchant account is inactive (the merchant’s account is not active/enabled).
401	Account is inactive (the specific account or sub-account is not active).
402	External MID is inactive (the external merchant ID/account is not active).
403	Entity activation status undefined (the activation state of a required entity is not set).
404	Could not route transaction to upstream (no active route to any upstream processor).

ℹ️ The above list covers the most commonly encountered decline codes on Exirom. For further inquiries or detailed cases regarding decline codes, please contact the Exirom support team.