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, 702, 1010, 1023, 3001, 3021	Transient errors. Retry with same `requestId`, exponential backoff (2s, 4s, 8s). Max 3 retries.
Fix merchant-side issue	8, 14, 17, 24–27, 30, 31, 65, 103, 105, 201–205, 502, 908, 909, 1011–1018, 3016, 3017, 3020, 3022, 4002, 4005, 4022, 4023, 4028, 20954	Check your request payload. Fix the data and resubmit with a new `requestId`. Do not auto-retry.
Customer action needed	3–6, 10, 19–23, 33, 34, 100, 104, 300–317, 500, 501, 700, 900–907, 910–915, 1001–1006, 1019–1022, 1024, 1025, 4034, 4036	Show a user-friendly message. Do not auto-retry — let the customer try again.
Wait for the verification decision	4035	The customer's identity verification is under manual review. Do not ask for the documents again and do not create a new transaction — every attempt returns 4035 until the review ends. Tell the customer to come back later.
Contact Exirom support	7, 28, 29, 32, 62, 64, 66–69, 78, 101, 102, 400–404, 600–603, 701, 800, 801, 1000, 1007, 1008, 3008–3012, 3014, 3015, 4001, 4009–4012, 4015, 4016, 4024, 4025, 4032, 4033, 7777, 19991	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, 33, 34	"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, 32, 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.
32	`PSP_GENERAL_DECLINE`	The PSP declined the transaction for an unspecified reason.
33	`ACCOUNT_EMPTY_BALANCE`	The payout account has zero balance.
34	`ACCOUNT_INSUFFICIENT_BALANCE`	The payout account has insufficient balance for this transaction.
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.

#Country Declines

Country-based declines occur when the customer's country fails the merchant's country routing rules (allowlist, blocklist, or origin-type constraints).

Code	Code Name	Description
100	`COUNTRY_CODE_IS_BLOCKED`	The customer's country is on the merchant's blocklist.
101	`COUNTRY_ORIGIN_TYPE_NOT_SUPPORTED`	The country origin type (billing, IP, etc.) is not supported by the routing configuration.
102	`COUNTRY_RESTRICTION_MODE_NOT_SUPPORTED`	The country restriction mode is not supported.
103	`COUNTRY_CODE_IS_MISSING_WHEN_NOT_OPEN_ALL`	Country code is required but missing from the request.
104	`COUNTRY_CODE_IS_NOT_ALLOW`	The customer's country is not in the merchant's allowed list.
105	`MULTIPLE_COUNTRIES_DETECTED`	Conflicting countries detected across billing / IP / card BIN.

#Domain & Redirect Declines

These errors relate to HTTP Referer validation and redirect URL constraints configured on the merchant account.

Code	Code Name	Description
201	`DOMAIN_NOT_ALLOWED`	The request domain constraint blocked the transaction.
202	`DOMAIN_REFERER_MISSING_OR_EMPTY`	The HTTP Referer header is missing or empty while a domain constraint is active.
203	`DOMAIN_REFERER_INVALID_FORMAT`	The HTTP Referer header has an invalid format.
204	`DOMAIN_REFERER_NOT_IN_ALLOWED_LIST`	The HTTP Referer is not in the merchant's allowed domains list.
205	`REDIRECT_URL_DECLINED`	The provided redirect URL failed validation.

#Risk Declines

Risk declines are raised by the Exirom risk engine based on configured rules. They evaluate signals such as AVS, CVV, device, email, shipping/billing, IP location, etc.

Code	Code Name	Description
300	`RISK_OVERALL_DECLINED`	Declined by the overall risk score / rule.
301	`RISK_AVS_DECLINED`	Declined by AVS (Address Verification System) check.
302	`RISK_BILLING_ADDRESS_DECLINED`	Billing address failed risk check.
303	`RISK_BROWSER_DECLINED`	Browser fingerprint failed risk check.
304	`RISK_CHARGEBACK_DECLINED`	Declined due to prior chargeback history.
305	`RISK_COUNTRY_DECLINED`	Country failed risk-rule check.
306	`RISK_COUNTRY_MISMATCH_DECLINED`	Country mismatch detected (e.g., billing vs. IP).
307	`RISK_CVV_DECLINED`	CVV check failed.
308	`RISK_DEVICE_DECLINED`	Device failed risk check.
309	`RISK_EMAIL_ADDRESS_DECLINED`	Email address failed risk check.
310	`RISK_EMAIL_DOMAIN_DECLINED`	Email domain failed risk check.
311	`RISK_EMAIL_LOCAL_PART_DECLINED`	Email local part failed risk check.
312	`RISK_ISSUER_ID_NUMBER_DECLINED`	Card issuer ID number (BIN) failed risk check.
313	`RISK_ORDER_AMOUNT_DECLINED`	Order amount failed risk check.
314	`RISK_PHONE_NUMBER_DECLINED`	Phone number failed risk check.
315	`RISK_SHIPPING_ADDRESS_DECLINED`	Shipping address failed risk check.
316	`RISK_SHIPPING_ADDRESS_DISTANCE_TO_IP_LOCATION_DECLINED`	Shipping address is too far from the IP geolocation.
317	`RISK_TIME_OF_DAY_DECLINED`	Transaction blocked by a time-of-day risk rule.

#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).

#First-Time Deposit (FTD) Declines

FTD declines are raised by first-time-deposit rules — typically requiring an existing successful transaction history or specific data for the customer's first deposit.

Code	Code Name	Description
500	`FTD_CONSTRAINT_DECLINED`	The first-time-deposit constraint blocked the transaction.
501	`FTD_NOT_ENOUGH_SUCCESS_TRANSACTIONS`	The customer does not have enough successful transactions to bypass the FTD rule.
502	`FTD_VALIDATION_FAILED_MISSING_DATA`	FTD validation failed — required data was missing in the request.

#FX Conversion Declines

FX declines are raised when currency conversion fails or is not allowed by the merchant account configuration.

Code	Code Name	Description
600	`FX_CONVERSION_RATE_MISSING`	No FX rate available for the requested currency pair.
601	`FX_CONVERSION_MERCHANT_ACCOUNT_NOT_SUPPORTED`	FX conversion is not supported on the selected merchant account.
602	`FX_CONVERSION_ERROR`	An error occurred during FX conversion.
603	`FX_PAYOUT_CONVERSION_MERCHANT_ACCOUNT_NOT_ALLOWED`	FX conversion on payouts is not allowed for this merchant account.

#Blacklist Declines

Blacklist declines are raised when the transaction or any of its attributes match an entry on the merchant's (or platform's) blacklist.

Code	Code Name	Description
700	`BLACKLIST_VALIDATION_DECLINED`	Blacklist check matched — transaction blocked.
701	`BLACKLIST_VALIDATION_FAILED`	Blacklist validation failed (technical error).
702	`BLACKLIST_CHECK_TIMEOUT`	Blacklist check timed out.

#Card Network Declines

Card network declines occur when the card brand (Visa/MC/Amex/etc.) is not enabled on the merchant or routing target.

Code	Code Name	Description
800	`NON_SUPPORTED_CARD_NETWORK`	The card network/brand is not supported for this transaction.
801	`MERCHANT_ACCOUNT_HAS_NO_SUPPORTED_CARD_NETWORKS_COUNT`	The merchant account has no enabled card networks.

#Limit / Counter Declines

Limit declines are raised when a transaction would exceed a configured daily/monthly limit (count or volume) on the merchant, account, card, or customer level.

Code	Code Name	Description
900	`DAILY_MAX_TRX_COUNT_DECLINED`	Daily maximum transaction count reached on the merchant/account.
901	`DAILY_MAX_VOLUME_DECLINED`	Daily maximum transaction volume reached.
902	`MONTHLY_MAX_TRX_COUNT_DECLINED`	Monthly maximum transaction count reached.
903	`MONTHLY_MAX_VOLUME_DECLINED`	Monthly maximum transaction volume reached.
904	`DAILY_MAX_CARD_TRX_COUNT_DECLINED`	Daily maximum count of transactions for this card reached.
905	`DAILY_MAX_CARD_VOLUME_DECLINED`	Daily maximum volume for this card reached.
906	`MONTHLY_MAX_CARD_TRX_COUNT_DECLINED`	Monthly maximum count of transactions for this card reached.
907	`MONTHLY_MAX_CARD_VOLUME_DECLINED`	Monthly maximum volume for this card reached.
908	`TRANSACTION_MIN_AMOUNT_DECLINED`	Transaction is below the minimum allowed amount.
909	`TRANSACTION_MAX_AMOUNT_DECLINED`	Transaction is above the maximum allowed amount.
910	`CUSTOMER_DAILY_MAX_TRX_COUNT_DECLINED`	Daily maximum transaction count for the customer reached.
911	`CUSTOMER_MONTHLY_MAX_TRX_COUNT_DECLINED`	Monthly maximum transaction count for the customer reached.
912	`CUSTOMER_DAILY_MAX_VOLUME_DECLINED`	Daily maximum transaction volume for the customer reached.
913	`CUSTOMER_MONTHLY_MAX_VOLUME_DECLINED`	Monthly maximum transaction volume for the customer reached.
914	`DAILY_MAX_CARD_FAILED_TRX_COUNT_DECLINED`	Daily maximum count of failed transactions for this card reached.
915	`DAILY_MAX_CUSTOMER_FAILED_TRX_COUNT_DECLINED`	Daily maximum count of failed transactions for the customer reached.

#3DS Authentication Declines

These codes are raised by the Exirom orchestration layer when 3-D Secure authentication fails. They are more granular than the upstream codes (3, 10, 19–23).

Code	Code Name	Description
1001	`AUTHENTICATION_FAILED`	3DS authentication failed.
1002	`AUTHENTICATION_FAILED_TIMEOUT`	3DS authentication timed out.
1003	`AUTHENTICATION_FAILED_INVALID_RESPONSE`	3DS authentication returned an invalid response.
1004	`AUTHENTICATION_FAILED_ABORTED_BY_USER`	3DS authentication was aborted by the user.
1005	`AUTHENTICATION_FAILED_ABORTED_BY_ISSUER`	3DS authentication was aborted by the issuer.
1006	`AUTHENTICATION_FAILED_ABANDONED_BY_USER`	3DS authentication was abandoned by the user.
1007	`THREE_DS_REDIRECT_ERROR`	Error during 3DS redirect flow.
1008	`THREE_DS_REDIRECT_TIMEOUT`	3DS redirect flow timed out.

#Failed Sub-Reasons

Failed sub-reasons give a more specific reason for a downstream decline. They surface in addition to the broader upstream code so you can apply finer-grained retry / customer-message logic.

Code	Code Name	Description
1010	`DOWNSTREAM_TIMEOUT`	Downstream PSP did not respond in time.
1011	`DECLINED_INVALID_CVV`	Declined — invalid CVV.
1012	`DECLINED_INVALID_EXPIRY_DATE`	Declined — invalid card expiry date.
1013	`DECLINED_INVALID_CARD_NUMBER`	Declined — invalid card number.
1014	`DECLINED_INVALID_AMOUNT`	Declined — invalid amount.
1015	`DECLINED_INVALID_CURRENCY`	Declined — invalid or unsupported currency.
1016	`DECLINED_INVALID_MERCHANT`	Declined — invalid merchant.
1017	`DECLINED_INVALID_TRANSACTION`	Declined — invalid transaction.
1018	`DECLINED_UNSUPPORTED_BRAND`	Declined — unsupported card brand.
1019	`DECLINED_LIMIT_EXCEEDED`	Declined — limit exceeded at the issuer/processor.
1020	`DECLINED_SUSPECTED_FRAUD`	Declined — suspected fraud.
1021	`DECLINED_DO_NOT_HONOR`	Declined — generic "do not honor" from the issuer.
1022	`DECLINED_BY_BIN`	Declined — blocked by BIN rule.
1023	`DECLINED_BY_COMMUNICATION_ERROR`	Declined — communication error with the processor.
1024	`DECLINED_BY_BIN_CHECK_FAILED`	Declined — BIN check failed.
1025	`ABANDONED_TX_RISK_CHECK_DECLINED`	Abandoned-transaction risk check declined the request.

#Business / Orchestration Errors

These errors indicate system-level issues with the request (missing transaction, invalid state, duplicate request, configuration not found, etc.). Most are transient and may resolve on retry, but several indicate a misconfigured or invalid request and require a fix on your side.

Code	Code Name	Description
1000	`NO_PROCESSOR_AVAILABLE`	No payment processor was available to handle the request.
3001	Downstream service timeout	An external service did not respond in time.
3008	`PSP_ID_NOT_FOUND_ON_ROUTING_STAGE`	The PSP could not be resolved at the routing stage.
3009	`EXTERNAL_MID_NOT_FOUND_ON_ROUTING_STAGE`	External MID could not be resolved at the routing stage.
3010	`PROCESSORS_NOT_AVAILABLE`	No payment processors were available to handle the request.
3011	`BIN_CHECK_RESULT_NOT_FOUND`	BIN check result was not found.
3012	`PAYMENT_TX_NOT_FOUND_FOR_REFUND`	The payment transaction referenced for the refund does not exist.
3014	`MERCHANT_REDIRECT_ALLOWED_HOST_ERROR`	The merchant's redirect host validation failed.
3015	`APM_SERVICE_NOT_FOUND`	No APM service was found for this transaction.
3016	`INVALID_USER_TOKEN`	The user token in the request is invalid or expired.
3017	`SUCCEEDED_REFUND_ALREADY_EXISTS`	A successful refund already exists for this payment.
3020	`INVALID_INTENT_STATUS`	The payment intent is in an invalid status for this operation.
3021	`DECLINED_TIMEOUT_NO_PSP_RESPONSE`	Declined — no response was received from the PSP within the timeout window.
3022	`INVALID_APPLE_PAY_SESSION_REQUEST`	The Apple Pay session request is invalid.

#Routing Declines

Routing declines occur when Exirom cannot resolve a route to an upstream processor — typically because no routing condition matched, no route was assigned, or routing configuration is missing. Related routing codes also appear as 404 and 3008–3010. These indicate a configuration issue — do not retry; contact Exirom support.

Code	Code Name	Description
4009	`NO_PENDING_CASCADING_STEP_FOUND`	No further cascading step was available to route the transaction.
4010	`NO_ROOT_NODE_FOUND`	The routing configuration has no root node defined.
4011	`NO_MATCH_ROUTE_CONDITION_NOR_DEFAULT_NODE`	No routing condition matched and no default route is configured.
4012	`NO_ROUTING_CONFIG_FOUND`	No routing configuration was found for this transaction.
4015	`PSP_WAS_NOT_ASSIGNED`	No PSP was assigned to the transaction during routing.
4016	`EXTERNAL_MID_WAS_NOT_ASSIGNED`	No external MID was assigned to the transaction during routing.
4032	`EXPECTED_ROUTING_NO_MATCH`	The transaction did not match any configured routing rule.
4033	`ROUTING_NO_MATCH`	No configured routing rule matched this transaction.

#Identity Verification Declines

Identity verification declines end a payment or payout that asked the customer for identity data. Show customerInstructionsByLanguage from the response; the declined transaction cannot be resumed. See Identity Verification.

Code	Code Name	Description
4034	`KYC_REQUIRED`	The provider accepted the submitted identity data, but still requires verification for this transaction, so the transaction is declined. A transaction that needs verification in the first place returns action `KYC_REQUIRED` instead of this decline. A new transaction opens the form again; the same data leads to 4034 again, because the provider already holds it and its answer does not change. The customer needs a different document, or support.
4035	`KYC_IN_PROGRESS`	The customer's verification is under manual review, after a submission or already when a new transaction is created. Do not request the documents again. Every new transaction returns 4035 until the review ends, and there is no callback for the end of the review, so tell the customer to come back later rather than to retry now.
4036	`KYC_REJECTED`	The submitted verification was rejected. A new transaction opens the verification form again for corrected data.

#Request Validation Declines

Request validation declines are raised when a required field is missing or cannot be resolved from the request. Fix the indicated field and resubmit with a new requestId.

Code	Code Name	Description
4001	`CREATED_DATE_MISSING`	The transaction's created date was missing.
4002	`EMAIL_MISSING`	A required email value was missing from the request.
4005	`CARD_BRAND_MISSING`	The card brand could not be determined from the request.
4022	`DEVICE_IP_MISSING`	The device IP address was missing from the request.
4023	`EMAIL_FIELD_MISSING`	The email field was missing from the request.
4024	`PAYMENT_TX_DETAIL_MUST_PRESENT_FOR_REFUND`	The original payment details required for the refund were missing.
4025	`REDIRECTION_METADATA_MISSING`	Redirection metadata required to continue the flow was missing.
4028	`APM_PAYLOAD_METADATA_IS_ABSENT`	The `apmPayload` metadata required for this APM was missing.

#Special Codes

Reserved codes for specific business conditions.

Code	Code Name	Description
7777	`PAYMENT_WAS_DONE_BY_ANOTHER_MERCHANT`	The payment referenced for a refund belongs to a different merchant.
19991	`MERCHANT_NOT_ENOUGH_FUNDS`	The merchant has insufficient funds for the requested payout/refund.
20954	`REFUND_AMOUNT_MUST_BE_AT_MOST_PAYMENT_AMOUNT`	The refund amount exceeds the original payment amount.

ℹ️ 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.