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.

Scenarios

Transaction declines occur during authorization when the card, account, or transaction fails validation. Each decline returns a standardized code that identifies the reason and helps determine the appropriate response.

sequenceDiagram
    participant Card as Cardholder
    participant Merchant as Merchant
    participant Network as Card Network
    participant PCE as PCE
    participant App as Your Application

    Card->>Merchant: Swipe/tap card
    Merchant->>Network: Authorization request
    Network->>PCE: Validate transaction
    PCE->>PCE: Check status, funds, limits, security
    alt Approved
        PCE-->>Network: Approved
        Network-->>Merchant: Transaction approved
    else Declined
        PCE-->>Network: Declined (code: DC-XXXX)
        Network-->>Merchant: Transaction declined
        PCE-->>App: Webhook: card.authorization.declined
        App->>App: Map code → user message + resolution
    end

Before you begin (all scenarios)

• Your webhook endpoint is subscribed to card.authorization.declined events.
• You have mapped decline codes to user-facing messages.
• Resolution flows are implemented (fund account, unfreeze, adjust limits).

Scenario 1: Handle Insufficient Funds Decline

Use this scenario when a cardholder's transaction is declined due to insufficient funds.

Business Context: A customer tries to purchase $127.50 at Whole Foods, but their balance is only $98.23.

Decline Code: DC-0051 (Debit) or PC-0051 (Prepaid)

You'll also need: Webhook subscription to receive decline notifications.

Resolution:

• For Debit cards: Fund the linked account via ACH, wire, or internal transfer
• For Prepaid cards: Load more funds onto the card

Example Webhook Payload

{
  "eventType": "card.authorization.declined",
  "payload": {
    "cardId": 55903,
    "merchantName": "WHOLE FOODS MKT #10847",
    "amount": "127.50",
    "declineCode": "DC-0051",
    "declineReason": "Insufficient Funds",
    "availableBalance": "98.23"
  }
}

Show the shortfall amount and provide a one-tap option to add funds.

Scenario 2: Handle Frozen Card Decline

Use this scenario when a transaction is declined because the card is frozen.

Decline Code: DC-0062 (Card Frozen)

You'll also need: Card status from GET /card/{id}.

Resolution:

• Review the freeze reason
• If safe, unfreeze via POST /card/{id}/unfreeze
• If compromised, cancel and replace the card

Scenario 3: Handle Spend Limit Exceeded

Use this scenario when a transaction exceeds the card's daily or per-transaction limit.

Decline Code: DC-0061 (Amount Limit) or DC-0065 (Count Limit)

You'll also need: Current limits and usage from GET /card/{id}/limit.

Resolution:

• Check current limit and usage
• Increase the limit if authorized via POST /card/{id}/limit
• Or wait for the daily reset

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

Debit Card Decline Codes

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

Prepaid Card Decline Codes

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

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