Manage Card-on-File Declines

Applies to: Cards API | Webhooks

Use Square features and guidance to help manage or reduce declines for card-on-file payments and increase customer retention.

To proactively manage potential declines due to expired card data or closed accounts, subscribe to receive card.automatically_updated event notifications when Square automatically updates cards on file. You can subscribe manually in the Developer Console or programmatically using the Webhook Subscriptions API.

When you receive a card.automatically_updated notification, inspect the card object in the notification payload and take appropriate action:

• Expiration updates - When allowed by the issuing bank, Square automatically updates the expiration date and last 4 digits of expiring cards on file. By listening for these updates, you can help ensure that card information remains current if the expiration date or card number changes.

  To use this feature:

  1. In the notification payload, check the exp_month, exp_year, and last_4 fields.
  2. If you store this card information, update your records.

• Issuer alerts about closed accounts (Beta, select Mastercard cards only) - For some Mastercard cards on file, the issuing bank alerts Square when the underlying account is closed. Square then marks the card as ISSUER_ALERT_CARD_CLOSED.

  Issuer alerts aren't guaranteed to be accurate, but they're a strong signal that future charges to the card are likely to fail. In testing, 80% of cards with issuer alerts were declined at the time of payment. By proactively contacting customers to set up a new payment method on file, you can reduce the likelihood that recurring subscriptions become delinquent.

  Note

  To access issuer alerts, Square API version 2024-12-18 or later is required for your webhook subscription or when calling the Cards API.

  To use this feature:

  1. In the notification payload, check whether the issuer_alert field is present. If present and set to ISSUER_ALERT_CARD_CLOSED, check the issuer_alert_at field to determine whether this is a new alert.
  2. If the account is newly marked as closed, request a new payment method from the customer.
  Link to section

  More details

  If notified by the issuing bank that the underlying account for the card on file is closed, Square sets the issuer_alert field to ISSUER_ALERT_CARD_CLOSED, updates the issuer_alert_at timestamp, and invokes a card.automatically_updated event.

  The issuer_alert and issuer_alert_at fields are present only when the card has an active issuer alert. If notified by the issuing bank that the account is reopened, Square clears both fields and invokes a card.automatically_updated event.

  The following example payload contains the issuer_alert and issuer_alert_at fields, which indicates that there's an active issuer alert:

  {
    "merchant_id": "6SSW7HV8K2ST5",
    "type": "card.automatically_updated",
    "event_id": "d214f854-adb1-4f56-b078-4b8697a3187a",
    "created_at": "2025-02-15T04:38:13Z",
    "data": {
      "type": "card",
      "id": "ccof:uIbfJXhXETSP197M3GB",
      "object": {
        "card": {
          "id": "ccof:uIbfJXhXETSP197M3GB",
          "billing_address": {
            "address_line_1": "500 Electric Ave",
            "address_line_2": "Suite 600",
            "locality": "New York",
            "administrative_district_level_1": "NY",
            "postal_code": "10003",
            "country": "US"
          },
          "fingerprint": "ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q",
          "bin": "411111",
          "card_brand": "VISA",
          "card_type": "CREDIT",
          "cardholder_name": "Amelia Earhart",
          "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8",
          "enabled": true,
          "exp_month": 11,
          "exp_year": 2027,
          "last_4": "1111",
          "issuer_alert": "ISSUER_ALERT_CARD_CLOSED",
          "issuer_alert_at": "2025-02-16T04:38:13Z",
          "merchant_id": "6SSW7HV8K2ST5",
          "prepaid_type": "NOT_PREPAID",
          "reference_id": "user-id-2",
          "version": 2
        }
      }
    }
  }

Square also supports card.created, card.updated, card.disabled, and card.forgotten webhook events for the Cards API.

Strong Customer Authentication (SCA) provides an additional layer of fraud protection in regions where SCA is required or for sellers that subscribe to Square Risk Manager to enforce 3-D Secure (3DS). SCA applies both when saving cards on file and making card-on-file payments.

To help reduce the likelihood of declines for card-on-file payments, provide as much buyer information as possible to the Web Payments SDK or In-App Payments SDK. For more information, see Charge a Card on File for Web Payments SDK integrations or Verify a Buyer for In-App Payments SDK integrations.

Square uses the Bank Identification Number (BIN) to determine whether a card on file is for a Health Savings Account (HSA) or a Flexible Spending Account (FSA), which can be used for authorized medical expenses. For these cards, Square sets the Card.hsa_fsa field to true.

You can use the hsa_fsa field to identify HSA and FSA cards, which tend to have higher decline rates as the year progresses because they might run out of funds. Sellers accepting card-on-file payments should ask customers to provide a secondary payment method on file when saving an HSA or FSA card on file.

A prepaid card is a type of payment card that can hold a certain amount of value. For these cards, Square sets the Card.prepaid_type field to PREPAID.

You can use the prepaid_type field to identify prepaid cards, which tend to have higher decline rates because they run out of funds. Sellers accepting card-on-file payments should ask customers to also provide a secondary payment method on file when saving a prepaid card on file.

Keep detailed logs of transaction attempts and declined payments to identify and address recurring issues. Conduct regular audits of transaction flows to ensure compliance with regulations and identify any potential issues.

Consider the following factors when designing your retry strategy:

• Check the decline reason to determine the appropriate action:
  • INSUFFICIENT_FUNDS - Retrying after a few days might be effective.
  • GENERIC_DECLINE error - Don't retry. Instead, inform the buyer that the specific reason for the decline isn't available and advise them to contact their issuer for further details and assistance. Sometimes the specific reason for a card decline is unavailable because of limitations in the information provided by the issuing bank.
• Wait at least 24 hours before retrying. Immediate retries can trigger fraud alerts or cause additional declines.
• Limit retries to 2 to 3 attempts over several days to avoid triggering fraud alerts. Excessive retries can be flagged as suspicious activity.

When possible, inform buyers when a decline occurs and suggest they contact their issuing bank for further details and assistance, especially when the exact reason for the decline isn't available.

If a charge continues to fail, request a new payment method from the customer.

• Cards API
• Manage Customer Cards on File
• Create a Card on File from a Payment ID
• Create a Card on File and a Payment
• Create a Shared Card on File and Make a Payment