Choose the Documentation MX Merchant MX Connect
MX-Merchant-Documentation
🟢 MX Merchant MX Connect
Home Release Notes Documentation API Guide API Tryout
MX-Connect-Documentation
MX Merchant 🟢 MX Connect
Home Release Notes Documentation API Guide API Tryout
Documentation
Start typing to search…
  1. TREASURY SOLUTIONS
  2. Card Issuance

Handle Transaction Declines

Understand why transactions fail and take the right action using standardized decline codes.

Transactions may be declined during authorization due to:

  • Card status (inactive, frozen, expired)
  • Account conditions (insufficient funds, limits exceeded)
  • Security checks (invalid PIN, CVV, suspected fraud)
  • Network or issuer-level validations

Each declined transaction returns a decline code, which helps you identify the reason and determine the appropriate response.

How to Use Decline Codes

  • Use decline codes to diagnose failures quickly
  • Map codes to user-facing messages or retry logic
  • Combine with:
    • Card status
    • Spend limits
    • Transaction context

The same decline scenarios may apply across both Debit and Prepaid cards, with different code prefixes.

Common Decline Categories

CategoryDescriptionExamples
Card StatusCard is not usableLost, Stolen, Inactive, Frozen
Funds & LimitsBalance or limits exceededInsufficient Funds, Amount Limit
Security & ValidationVerification failuresInvalid PIN, CVV
Transaction ControlsRestricted usageMerchant not permitted
System / NetworkProcessing failuresTimeout, System Error

Debit Card Decline Codes

The following decline codes may be returned for Debit card transactions:

Decline CodeDescription
DC-0001Issuer System Error.
DC-0003Transaction Not Permitted at this merchant.
DC-0004Suspected Fraud.
DC-0005Do Not Honor.
DC-0010Partial Approval. The full amount was not authorized.
DC-0013Transaction Exceeds Maximum Limit.
DC-0014Invalid Card Details.
DC-0019System Error.
DC-0039Account linked to Card not found.
DC-0041Card Lost.
DC-0042Card Stolen.
DC-0046Card Inactive or Cancelled.
DC-0046Card Inactive or Cancelled.
DC-0051Insufficient Funds.
DC-0054Expired Card or Invalid Expiration Date.
DC-0055Invalid PIN.
DC-0057Transaction Not Permitted.
DC-0061Transaction Exceeds Allowed Amount Limit.
DC-0062Card Restricted.
DC-0062Card Frozen.
DC-0063Security Violation.
DC-0065Transaction Exceeds Allowed Count Limit.
DC-0065Card Inactive.
DC-0075Maximum PIN Attempts Exceeded.
DC-0082Card Verification failed - Invalid CVV.
DC-0086Card Verification failed - Invalid PIN.
DC-0092Transaction Timeout.
DC-0093Cash Service Not Available.
DC-0094Card Verification failed - Invalid CVV2.

Prepaid Card Decline Codes

The following decline codes may be returned for Prepaid card transactions:

Decline CodeDescription
PC-0001Issuer System Error.
PC-0003Transaction Not Permitted at this merchant.
PC-0004Suspected Fraud.
PC-0005Do Not Honor.
PC-0010Partial Approval. The full amount was not authorized.
PC-0013Transaction Exceeds Maximum Limit.
PC-0014Invalid Card Details.
PC-0019System Error.
PC-0039Account linked to Card not found.
PC-0041Card Lost.
PC-0042Card Stolen.
PC-0046Card Inactive or Cancelled.
PC-0046Card Inactive or Cancelled.
PC-0051Insufficient Funds.
PC-0054Expired Card or Invalid Expiration Date.
PC-0055Invalid PIN.
PC-0057Transaction Not Permitted.
PC-0061Transaction Exceeds Allowed Amount Limit.
PC-0062Card Restricted.
DC-0062Card Frozen.
PC-0063Security Violation.
PC-0065Transaction Exceeds Allowed Count Limit.
PC-0065Card Inactive.
PC-0075Maximum PIN Attempts Exceeded.
PC-0082Card Verification failed - Invalid CVV.
PC-0086Card Verification failed - Invalid PIN.
PC-0092Transaction Timeout.
PC-0093Cash Service Not Available.
PC-0094Card Verification failed - Invalid CVV2.

Dispute Management

In cases where a cardholder identifies an unauthorized or incorrect transaction, disputes are handled through a third-party provider.

Cardholders can initiate a dispute by contacting the support number on the back of their card. Once submitted, the third-party provider manages the dispute lifecycle, including investigation, resolution, and communication with the card networks.

Any financial impact resulting from the dispute—such as provisional credits or reversals—is reflected as adjustments in the customer’s ledger.

Dispute handling is managed externally. No direct API integration is required for initiating or managing disputes


Updated 3 days ago