Overview of the `subscription.charge.failed` webhook

When a subscription.charge.failed event is triggered, FastSpring sends a webhook payload with details about the rebill failure. The payload contains the failure reason, which is most commonly due to an expired or declined payment method.

If webhook expansion is enabled, the payload includes full account and product objects. Otherwise, the payload includes only the corresponding IDs.

This page includes:

A full sample payload showing a populated subscription.charge.failed webhook
A detailed table listing every payload property, including name, type, and description
Notes on when each field is included, omitted, or dependent on specific update types

Browse the table sections below or use the quick links to jump to a specific group of fields.

Tip: Not all fields are always included. Refer to the Payload properties table to understand when a field appears.

Webhook payload example (expansion enabled)

When a subscription.charge.failed event is triggered, the webhook sends the following JSON payload:

{
    "reason": "EXPIRED_CARD",
    "account": {
      "id": "abCdE1FGH2Hij3KLMnOpqR",
      "account": "abCdE1FGH2Hij3KLMnOpqR",
      "contact": {
        "first": "Jane",
        "last": "Doe",
        "email": "jane.doe@company.com",
        "company": "Company Inc.",
        "phone": "5555555",
        "subscribed": true
      },
      "address": {
        "address line 1": "123 Business Rd",
        "address line 2": "Floor 4",
        "city": "Metropolis",
        "country": "US",
        "postal code": "12345",
        "region": "US-NY",
        "region custom": null,
        "company": "Company Inc."
      },
      "language": "en",
      "country": "US",
      "lookup": {
        "global": "lookup-001"
      },
      "url": "https://company.onfastspring.com/account"
    },
    "subscription": {
      "id": "1abc2DE_FGhIjKLm3NoPQR",
      "quote": null,
      "subscription": "1abc2DE_FGhIjKLm3NoPQR",
      "active": true,
      "state": "trial",
      "isSubscriptionEligibleForPauseByBuyer": false,
      "isPauseScheduled": false,
      "changed": 1749236508799,
      "changedValue": 1749236508799,
      "changedInSeconds": 1749236508,
      "changedDisplay": "6/6/25",
      "changedDisplayISO8601": "2025-06-06",
      "changedDisplayEmailEnhancements": "Jun 06, 2025",
      "changedDisplayEmailEnhancementsWithTime": "Jun 06, 2025 07:01:48 PM",
      "paymentMethodAction": "none",
      "live": false,
      "currency": "USD",
      "declineReason": null,
      "account": "abCdE1FGH2Hij3KLMnOpqR",
      "product": "furious-falcon",
      "sku": "SKU-FF-102",
      "display": "Furious Falcon",
      "quantity": 1,
      "adhoc": false,
      "autoRenew": true,
      "price": 14.95,
      "priceDisplay": "$14.95",
      "priceInPayoutCurrency": 14.95,
      "priceInPayoutCurrencyDisplay": "$14.95",
      "discount": 0,
      "discountDisplay": "$0.00",
      "discountInPayoutCurrency": 0,
      "discountInPayoutCurrencyDisplay": "$0.00",
      "subtotal": 14.95,
      "subtotalDisplay": "$14.95",
      "subtotalInPayoutCurrency": 14.95,
      "subtotalInPayoutCurrencyDisplay": "$14.95",
      "next": 1749340800000,
      "nextValue": 1749340800000,
      "nextInSeconds": 1749340800,
      "nextDisplay": "6/8/25",
      "nextDisplayISO8601": "2025-06-08",
      "end": null,
      "endValue": null,
      "endInSeconds": null,
      "endDisplay": null,
      "endDisplayISO8601": null,
      "canceledDate": null,
      "canceledDateValue": null,
      "canceledDateInSeconds": null,
      "canceledDateDisplay": null,
      "canceledDateDisplayISO8601": null,
      "deactivationDate": 1749945600000,
      "deactivationDateValue": 1749945600000,
      "deactivationDateInSeconds": 1749945600,
      "deactivationDateDisplay": "6/15/25",
      "deactivationDateDisplayISO8601": "2025-06-15",
      "sequence": 1,
      "periods": null,
      "remainingPeriods": null,
      "begin": 1749236450805,
      "beginValue": 1749236450805,
      "beginInSeconds": 1749236450,
      "beginDisplay": "6/6/25",
      "beginDisplayISO8601": "2025-06-06",
      "beginDisplayEmailEnhancements": "Jun 06, 2025",
      "beginDisplayEmailEnhancementsWithTime": "Jun 06, 2025 07:00:50 PM",
      "nextDisplayEmailEnhancements": "Jun 08, 2025",
      "nextDisplayEmailEnhancementsWithTime": "Jun 08, 2025 12:00:00 AM",
      "intervalUnit": "month",
      "intervalUnitAbbreviation": "mo",
      "intervalLength": 1,
      "intervalLengthGtOne": false,
      "nextChargeCurrency": "USD",
      "nextChargeDate": 1749340800000,
      "nextChargeDateValue": 1749340800000,
      "nextChargeDateInSeconds": 1749340800,
      "nextChargeDateDisplay": "6/8/25",
      "nextChargeDateDisplayISO8601": "2025-06-08",
      "nextChargePreTax": 13.84,
      "nextChargePreTaxDisplay": "$13.84",
      "nextChargePreTaxInPayoutCurrency": 13.84,
      "nextChargePreTaxInPayoutCurrencyDisplay": "$13.84",
      "nextChargeTotal": 14.95,
      "nextChargeTotalDisplay": "$14.95",
      "nextChargeTotalInPayoutCurrency": 14.95,
      "nextChargeTotalInPayoutCurrencyDisplay": "$14.95",
      "cancellationSetting": {
        "cancellation": "AFTER_PAYMENT_FAILURE",
        "intervalUnit": "week",
        "intervalLength": 1
      },
      "fulfillments": {
        "instructions": "<p>Thank you for subscribing to Example Subscription Monthly. Please download the installer file using the button or link found on this page. Your license key is also displayed here.</p>"
      },
      "instructions": [
        {
          "type": "trial",
          "trialType": "PAID",
          "isNotTrial": false,
          "periodStartDate": 1749340800000,
          "periodStartDateValue": 1749340800000,
          "periodStartDateInSeconds": 1749340800,
          "periodStartDateDisplay": "6/8/25",
          "periodStartDateDisplayISO8601": "2025-06-08",
          "periodEndDate": 1749254400000,
          "periodEndDateValue": 1749254400000,
          "periodEndDateInSeconds": 1749254400,
          "periodEndDateDisplay": "6/7/25",
          "periodEndDateDisplayISO8601": "2025-06-07",
          "discountDurationUnit": "day",
          "discountDurationLength": 1,
          "discountPercent": 100,
          "discountPercentValue": 100,
          "discountPercentDisplay": "100%",
          "unitDiscount": 14.95,
          "unitDiscountDisplay": "$14.95",
          "unitDiscountInPayoutCurrency": 14.95,
          "unitDiscountInPayoutCurrencyDisplay": "$14.95",
          "discountTotal": 14.95,
          "discountTotalDisplay": "$14.95",
          "discountTotalInPayoutCurrency": 14.95,
          "discountTotalInPayoutCurrencyDisplay": "$14.95",
          "total": 0,
          "totalDisplay": "$0.00",
          "totalInPayoutCurrency": 0,
          "totalInPayoutCurrencyDisplay": "$0.00",
          "totalWithTaxes": 14.95,
          "totalWithTaxesDisplay": "$14.95",
          "totalWithTaxesInPayoutCurrency": 14.95,
          "totalWithTaxesInPayoutCurrencyDisplay": "$14.95",
          "price": 14.95,
          "priceDisplay": "$14.95",
          "priceInPayoutCurrency": 14.95,
          "priceInPayoutCurrencyDisplay": "$14.95",
          "priceTotal": 14.95,
          "priceTotalDisplay": "$14.95",
          "priceTotalInPayoutCurrency": 14.95,
          "priceTotalInPayoutCurrencyDisplay": "$14.95",
          "unitPrice": 0,
          "unitPriceDisplay": "$0.00",
          "unitPriceInPayoutCurrency": 0,
          "unitPriceInPayoutCurrencyDisplay": "$0.00"
        },
        {
          "product": "furious-falcon",
          "type": "regular",
          "isNotTrial": true,
          "periodStartDate": 1749340800000,
          "periodStartDateValue": 1749340800000,
          "periodStartDateInSeconds": 1749340800,
          "periodStartDateDisplay": "6/8/25",
          "periodStartDateDisplayISO8601": "2025-06-08",
          "periodEndDate": null,
          "periodEndDateValue": null,
          "periodEndDateInSeconds": null,
          "periodEndDateDisplay": null,
          "periodEndDateDisplayISO8601": null,
          "intervalUnit": "month",
          "intervalLength": 1,
          "discountPercent": 0,
          "discountPercentValue": 0,
          "discountPercentDisplay": "0%",
          "discountTotal": 0,
          "discountTotalDisplay": "$0.00",
          "discountTotalInPayoutCurrency": 0,
          "discountTotalInPayoutCurrencyDisplay": "$0.00",
          "unitDiscount": 0,
          "unitDiscountDisplay": "$0.00",
          "unitDiscountInPayoutCurrency": 0,
          "unitDiscountInPayoutCurrencyDisplay": "$0.00",
          "price": 14.95,
          "priceDisplay": "$14.95",
          "priceInPayoutCurrency": 14.95,
          "priceInPayoutCurrencyDisplay": "$14.95",
          "priceTotal": 14.95,
          "priceTotalDisplay": "$14.95",
          "priceTotalInPayoutCurrency": 14.95,
          "priceTotalInPayoutCurrencyDisplay": "$14.95",
          "unitPrice": 14.95,
          "unitPriceDisplay": "$14.95",
          "unitPriceInPayoutCurrency": 14.95,
          "unitPriceInPayoutCurrencyDisplay": "$14.95",
          "total": 14.95,
          "totalDisplay": "$14.95",
          "totalInPayoutCurrency": 14.95,
          "totalInPayoutCurrencyDisplay": "$14.95",
          "totalWithTaxes": 14.95,
          "totalWithTaxesDisplay": "$14.95",
          "totalWithTaxesInPayoutCurrency": 14.95,
          "totalWithTaxesInPayoutCurrencyDisplay": "$14.95"
        }
      ],
      "initialOrderId": "S6XqptRvRJmzS1qceZKcNA",
      "initialOrderReference": "ABC1234567-8910-11121"
    }
  }

Navigate this webhook

The subscription.charge.failed webhook payload includes dozens of fields. Use the cards below to jump to a specific section of the property reference.

Rebill and Expiration

Cancellation and Deactivation

Billing Schedule

Next Charge Details

Cancellation Settings

Fulfillment Object

Instructions Array

Payload properties

All fields below are included in the subscription.charge.failed webhook payload. Fields are grouped into categories for easier navigation.

Name	Type	Description
Event Metadata
reason	string	Failure reason code for the charge, such as `EXPIRED_CARD`. See Reason codes for the full list and suggested actions.
Account Object
account	object	Customer account object containing ID, contact information, language, country, and account lookup values
account.id	string	FastSpring-generated customer account ID
account.account	string	Duplicate of `account.id` for backward compatibility
account.contact.first	string	First name of the customer
account.contact.last	string	Last name of the customer
account.contact.email	string	Email address of the customer
account.contact.company	string	Company name of the customer when provided
account.contact.phone	string	Phone number of the customer when provided
account.contact.subscribed	boolean	Whether the account contact is subscribed to updates
account.address.address line 1	string	Primary street address line
account.address.address line 2	string	Secondary street address line
account.address.city	string	City of the account address
account.address.country	string	Two-letter ISO country code for the address
account.address.postal code	string	Postal or ZIP code of the address
account.address.region	string	Region or state of the address
account.address.region custom	string	Custom region when not standard
account.address.company	string	Company associated with the address
account.language	string	Two-letter ISO code for the customer’s preferred language
account.country	string	Two-letter ISO country code for the customer
account.lookup.global	string	Globally unique public ID used to look up the account in customer-facing portals
account.url	string	Customer-facing account management URL
Subscription Object
subscription.id	string	Unique identifier for the subscription
subscription.quote	string	Associated quote ID if created from a quote
subscription.subscription	string	Duplicate of `subscription.id` for backward compatibility
subscription.active	boolean	Whether the subscription is currently active
subscription.state	string	Current state such as `trial`, `active`, `overdue`, `deactivated`, or `canceled`
subscription.isSubscriptionEligibleForPauseByBuyer	boolean	Whether the buyer can pause the subscription from their account
subscription.isPauseScheduled	boolean	Whether a pause has been scheduled to take effect on the next rebill
paymentMethodAction	string	Whether the payment method changed, such as `updated` or `none`
subscription.live	boolean	Whether the subscription was created in live mode
subscription.currency	string	Three-letter ISO currency code for the subscription
subscription.declineReason	string	Reason for payment decline when applicable
subscription.account	string	Account ID associated with the subscription
subscription.product	string	Product ID associated with the subscription
subscription.sku	string	SKU of the subscription product
subscription.display	string	Customer-facing display name of the subscription
subscription.quantity	integer	Quantity of the subscription product
subscription.adhoc	boolean	Whether the subscription is manually billed outside standard flows
subscription.autoRenew	boolean	Whether the subscription automatically renews
Pricing
subscription.price	number	Amount charged per billing period in transaction currency
subscription.priceDisplay	string	Formatted display of `price`
subscription.priceInPayoutCurrency	number	Subscription price in payout currency
subscription.priceInPayoutCurrencyDisplay	string	Formatted display of `priceInPayoutCurrency`
subscription.discount	number	Total discount applied to the subscription in transaction currency
subscription.discountDisplay	string	Formatted display of `discount`
subscription.discountInPayoutCurrency	number	Discount amount in payout currency
subscription.discountInPayoutCurrencyDisplay	string	Formatted display of `discountInPayoutCurrency`
subscription.subtotal	number	Subtotal amount before taxes
subscription.subtotalDisplay	string	Formatted display of `subtotal`
subscription.subtotalInPayoutCurrency	number	Subtotal amount in payout currency
subscription.subtotalInPayoutCurrencyDisplay	string	Formatted display of `subtotalInPayoutCurrency`
Rebill and Expiration
subscription.next	integer	Timestamp in milliseconds for the next scheduled billing
subscription.nextValue	integer	Duplicate of `next` for backward compatibility
subscription.nextInSeconds	integer	Timestamp in seconds for the next scheduled billing
subscription.nextDisplay	string	Formatted display of the next scheduled billing date
subscription.nextDisplayISO8601	string	Next scheduled billing date in ISO 8601 format
subscription.end	integer	Timestamp in milliseconds when the subscription ends, if scheduled
subscription.endValue	integer	Duplicate of `end` for backward compatibility
subscription.endInSeconds	integer	Timestamp in seconds when the subscription ends, if scheduled
subscription.endDisplay	string	Formatted display of the subscription end date
subscription.endDisplayISO8601	string	Subscription end date in ISO 8601 format
Cancellation and Deactivation
subscription.canceledDate	integer	Timestamp in milliseconds when the subscription was canceled, if applicable
subscription.canceledDateValue	integer	Duplicate of `canceledDate` for backward compatibility
subscription.canceledDateInSeconds	integer	Timestamp in seconds when the subscription was canceled
subscription.canceledDateDisplay	string	Formatted display of `canceledDate`
subscription.canceledDateDisplayISO8601	string	Cancellation date in ISO 8601 format
subscription.deactivationDate	integer	Timestamp in milliseconds when the subscription deactivates, if applicable
subscription.deactivationDateValue	integer	Duplicate of `deactivationDate` for backward compatibility
subscription.deactivationDateInSeconds	integer	Timestamp in seconds when the subscription deactivates
subscription.deactivationDateDisplay	string	Formatted display of `deactivationDate`
subscription.deactivationDateDisplayISO8601	string	Deactivation date in ISO 8601 format
Billing Schedule
subscription.sequence	integer	Sequence number of the current billing period
subscription.periods	integer	Total number of billing periods for the subscription
subscription.remainingPeriods	integer	Number of billing periods remaining
subscription.begin	integer	Timestamp in milliseconds when the subscription began
subscription.beginValue	integer	Duplicate of `begin` for backward compatibility
subscription.beginInSeconds	integer	Timestamp in seconds when the subscription began
subscription.beginDisplay	string	Formatted display of the subscription start date
subscription.beginDisplayISO8601	string	Start date in ISO 8601 format
subscription.beginDisplayEmailEnhancements	string	User-friendly subscription start date for email display
subscription.beginDisplayEmailEnhancementsWithTime	string	User-friendly subscription start date and time for email display
nextDisplayEmailEnhancements	string	User-friendly next charge date for email display
nextDisplayEmailEnhancementsWithTime	string	User-friendly next charge date and time for email display
subscription.intervalUnit	string	Unit of time between billing periods such as `month`
subscription.intervalUnitAbbreviation	string	Abbreviated unit of time between billing periods such as `mo`
subscription.intervalLength	integer	Number of `intervalUnit`s between charges
subscription.intervalLengthGtOne	boolean	Whether `intervalLength` is greater than one
Next Charge Details
nextChargeCurrency	string	Three-letter ISO currency code for the next scheduled charge
nextChargeDate	integer	Timestamp in milliseconds of the next scheduled charge
nextChargeDateValue	integer	Duplicate of `nextChargeDate` for backward compatibility
nextChargeDateInSeconds	integer	Timestamp in seconds of the next scheduled charge
nextChargeDateDisplay	string	Formatted display of the next scheduled charge date
nextChargeDateDisplayISO8601	string	Next scheduled charge date in ISO 8601 format
nextChargePreTax	number	Pre-tax amount for the next charge in transaction currency
nextChargePreTaxDisplay	string	Formatted display of `nextChargePreTax`
nextChargePreTaxInPayoutCurrency	number	Pre-tax charge amount in payout currency
nextChargePreTaxInPayoutCurrencyDisplay	string	Formatted display of `nextChargePreTaxInPayoutCurrency`
nextChargeTotal	number	Total charge amount including tax when applicable
nextChargeTotalDisplay	string	Formatted display of `nextChargeTotal`
nextChargeTotalInPayoutCurrency	number	Total charge amount in payout currency
nextChargeTotalInPayoutCurrencyDisplay	string	Formatted display of `nextChargeTotalInPayoutCurrency`
Cancellation Settings
cancellationSetting.cancellation	string	Cancellation trigger such as `AFTER_PAYMENT_FAILURE` or `AFTER_LAST_NOTIFICATION`
cancellationSetting.intervalUnit	string	Time unit used with `intervalLength` to determine when cancellation occurs
cancellationSetting.intervalLength	integer	Number of `intervalUnit`s to wait before cancellation
Fulfillment Object
fulfillments	object	Container for fulfillment data associated with the subscription
fulfillments.instructions	string	HTML content with delivery instructions such as download links or license keys
Instructions Array
instructions	array	Array of billing instruction objects for each subscription period
instructions.product	string	Product ID for the billing instruction period (only present on regular instructions)
instructions.type	string	Type of billing instruction such as `trial` or `regular`
instructions.trialType	string	Trial type such as `PAID`, `FREE_WITH_PAYMENT`, or `FREE_WITHOUT_PAYMENT`; present only on trial instructions
instructions.isNotTrial	boolean	Whether the instruction is not part of a trial period
instructions.periodStartDate	integer	Timestamp in milliseconds for the start of the billing period
instructions.periodStartDateValue	integer	Duplicate of `periodStartDate` for backward compatibility
instructions.periodStartDateInSeconds	integer	Timestamp in seconds for the start of the billing period
instructions.periodStartDateDisplay	string	Formatted display of `periodStartDate`
instructions.periodStartDateDisplayISO8601	string	Start date in ISO 8601 format
instructions.periodEndDate	integer	Timestamp in milliseconds for the end of the billing period, if known
instructions.periodEndDateValue	integer	Duplicate of `periodEndDate` for backward compatibility
instructions.periodEndDateInSeconds	integer	Timestamp in seconds for the end of the billing period, if known
instructions.periodEndDateDisplay	string	Formatted display of `periodEndDate`
instructions.periodEndDateDisplayISO8601	string	End date in ISO 8601 format
instructions.discountDurationUnit	string	Unit of time over which the discount applies, present only on trial instructions
instructions.discountDurationLength	integer	Length of the discount duration in `discountDurationUnit`s, present only on trial instructions
instructions.discountPercent	integer	Percentage discount applied during the period
instructions.discountPercentValue	integer	Duplicate of `discountPercent` for backward compatibility
instructions.discountPercentDisplay	string	Formatted display of `discountPercent`
instructions.unitDiscount	number	Per-unit discount amount in transaction currency
instructions.unitDiscountDisplay	string	Formatted display of `unitDiscount`
instructions.unitDiscountInPayoutCurrency	number	Per-unit discount amount in payout currency
instructions.unitDiscountInPayoutCurrencyDisplay	string	Formatted display of `unitDiscountInPayoutCurrency`
instructions.discountTotal	number	Total discount applied during the period in transaction currency
instructions.discountTotalDisplay	string	Formatted display of `discountTotal`
instructions.discountTotalInPayoutCurrency	number	Total discount in payout currency
instructions.discountTotalInPayoutCurrencyDisplay	string	Formatted display of `discountTotalInPayoutCurrency`
instructions.total	number	Total amount due for the period in transaction currency
instructions.totalDisplay	string	Formatted display of `total`
instructions.totalInPayoutCurrency	number	Total amount in payout currency
instructions.totalInPayoutCurrencyDisplay	string	Formatted display of `totalInPayoutCurrency`
instructions.totalWithTaxes	number	Total charge amount including taxes in transaction currency
instructions.totalWithTaxesDisplay	string	Formatted display of `totalWithTaxes`
instructions.totalWithTaxesInPayoutCurrency	number	Total including taxes in payout currency
instructions.totalWithTaxesInPayoutCurrencyDisplay	string	Formatted display of `totalWithTaxesInPayoutCurrency`
instructions.price	number	List price before discounts in transaction currency
instructions.priceDisplay	string	Formatted display of `price`
instructions.priceInPayoutCurrency	number	List price in payout currency
instructions.priceInPayoutCurrencyDisplay	string	Formatted display of `priceInPayoutCurrency`
instructions.priceTotal	number	Total list price before discounts in transaction currency
instructions.priceTotalDisplay	string	Formatted display of `priceTotal`
instructions.priceTotalInPayoutCurrency	number	Total list price before discounts in payout currency
instructions.priceTotalInPayoutCurrencyDisplay	string	Formatted display of `priceTotalInPayoutCurrency`
instructions.unitPrice	number	Unit price after discounts in transaction currency
instructions.unitPriceDisplay	string	Formatted display of `unitPrice`
instructions.unitPriceInPayoutCurrency	number	Unit price after discounts in payout currency
instructions.unitPriceInPayoutCurrencyDisplay	string	Formatted display of `unitPriceInPayoutCurrency`
subscription.initialOrderId	string	Initial order ID that created the subscription
subscription.initialOrderReference	string	Initial order reference identifier for the subscription

Reason codes

The reason field in a subscription.charge.failed webhook reports why the charge failed. Codes are grouped below by category — open a section for the full list, suggested action, and whether FastSpring will retry automatically.

Soft declines (4 codes)

FastSpring retries these automatically per your dunning configuration. The buyer may also need to update their payment method.

Code	Meaning	Suggested Action
`DECLINED_SOFT`	General soft decline from the issuer.	FastSpring retries automatically. Prompt the buyer to update their payment method if retries fail.
`INCOMPLETE_PAYMENT`	Payment process was not completed.	FastSpring retries automatically. No buyer action required.
`INSUFFICIENT_FUNDS`	Not enough funds in the account.	FastSpring retries automatically. Prompt the buyer to update their payment method.
`VOICE_AUTH`	Issuer requires voice authorization to proceed.	Ask the buyer to contact their bank.

Hard declines (6 codes)

These will not resolve on retry. Prompt the buyer to update their payment method or contact their bank.

Code	Meaning	Suggested Action
`DECEASED`	Account holder is deceased.	No automated action.
`DECLINED`	Hard decline from the issuer.	Ask the buyer to use a different payment method or contact their bank.
`DISPUTED`	Payment is in active dispute.	No automated action. Contact FastSpring support if needed.
`EXPIRED_CARD`	Card has expired.	Ask the buyer to update their card.
`RESTRICTED`	Card or account is restricted.	Ask the buyer to contact their bank.
`UNSUPPORTED_COUNTRY`	Country is not supported for this payment method.	Contact FastSpring support.

Payment method issues (4 codes)

Something specific is wrong with the payment details. Prompt the buyer to re-enter or verify their information. These will not resolve on retry.

Code	Meaning	Suggested Action
`API_INVALID_IBAN`	IBAN is invalid.	Ask the buyer to verify their IBAN.
`CC_ADDRESS_VERIFICATION`	Billing address verification (AVS) failed.	Ask the buyer to verify their billing address.
`CC_CVV`	CVV / security code mismatch.	Ask the buyer to re-enter their card details.
`INVALID_TOKEN`	Payment token is invalid or expired.	Ask the buyer to re-enter their payment details.

Bank / ACH errors (2 codes)

These apply to ACH and bank account payment methods only. They will not resolve on retry.

Code	Meaning	Suggested Action
`ACH_INVALID_ACCOUNT_NUMBER`	Invalid ACH account number.	Ask the buyer to verify their account number.
`ACH_INVALID_ROUTING_NUMBER`	Invalid ACH routing number.	Ask the buyer to verify their routing number.

Technical / temporary errors (9 codes)

System or communication issues. Most are retried automatically; API_INVALID_REQUEST_DATA and API_REFUND_FAILED indicate problems that require FastSpring support.

Code	Meaning	Suggested Action
`API_BANK_ACCOUNT_LOGIN_ERROR`	Bank account login failed (open-banking flows).	FastSpring retries automatically. Ask the buyer to re-authenticate with their bank if retries fail.
`API_GENERIC_ERROR`	Generic API error from the payment provider.	FastSpring retries automatically. No buyer action required.
`API_INVALID_REQUEST_DATA`	Invalid data in the payment request.	Contact FastSpring support. Usually indicates an integration issue.
`API_REFUND_FAILED`	Refund attempt failed.	Contact FastSpring support.
`API_TRANSACTION_DECLINED`	Transaction declined via the payment API.	FastSpring retries automatically. If retries fail, ask the buyer to use a different payment method.
`CONNECTION`	Communication error with the payment processor.	FastSpring retries automatically. No buyer action required.
`INTERNAL_ERROR`	Internal processing error.	FastSpring retries automatically. No buyer action required.
`TIMEOUT`	Payment request timed out.	FastSpring retries automatically. No buyer action required.
`UNKNOWN`	Decline reason could not be determined.	FastSpring retries automatically. Treat as a soft decline.

Risk & security (2 codes)

Transaction was blocked by FastSpring or processor risk controls. These will not resolve on retry.

Code	Meaning	Suggested Action
`PROC_RISK`	Blocked by the payment processor's risk controls.	Ask the buyer to use a different payment method, or contact FastSpring support.
`RISK`	Blocked by FastSpring's risk controls.	Ask the buyer to use a different payment method, or contact FastSpring support.

Forward compatibility: Treat any unrecognized reason value as a soft decline — FastSpring will continue dunning per your configuration. New codes may be added without breaking changes.