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": "[email protected]",
        "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.

<td style={"overflowWrap":"anywhere","wordBreak":"break-word"}>Failure reason code for the charge, such as EXPIRED_CARD. See Reason codes for the full list and suggested actions.

<td style={"overflowWrap":"anywhere","wordBreak":"break-word"}>Secondary street address lineaccount.address.citystringCity of the account addressaccount.address.countrystringTwo-letter ISO country code for the addressaccount.address.postal codestringPostal or ZIP code of the addressaccount.address.regionstringRegion or state of the addressaccount.address.region customstringCustom region when not standardaccount.address.companystringCompany associated with the addressaccount.languagestringTwo-letter ISO code for the customer’s preferred languageaccount.countrystringTwo-letter ISO country code for the customeraccount.lookup.globalstringGlobally unique public ID used to look up the account in customer-facing portalsaccount.urlstringCustomer-facing account management URL

subscription.currencystringThree-letter ISO currency code for the subscriptionsubscription.declineReasonstringReason for payment decline when applicablesubscription.accountstringAccount ID associated with the subscriptionsubscription.productstringProduct ID associated with the subscriptionsubscription.skustringSKU of the subscription productsubscription.displaystringCustomer-facing display name of the subscriptionsubscription.quantityintegerQuantity of the subscription productsubscription.adhocbooleanWhether the subscription is manually billed outside standard flowssubscription.autoRenewbooleanWhether the subscription automatically renews

subscription.discountInPayoutCurrencynumberDiscount amount in payout currencysubscription.discountInPayoutCurrencyDisplaystringFormatted display of `discountInPayoutCurrency`subscription.subtotalnumberSubtotal amount before taxessubscription.subtotalDisplaystringFormatted display of `subtotal`subscription.subtotalInPayoutCurrencynumberSubtotal amount in payout currencysubscription.subtotalInPayoutCurrencyDisplaystringFormatted display of `subtotalInPayoutCurrency`

subscription.endintegerTimestamp in milliseconds when the subscription ends, if scheduledsubscription.endValueintegerDuplicate of `end` for backward compatibilitysubscription.endInSecondsintegerTimestamp in seconds when the subscription ends, if scheduledsubscription.endDisplaystringFormatted display of the subscription end datesubscription.endDisplayISO8601stringSubscription end date in ISO 8601 format

subscription.deactivationDateintegerTimestamp in milliseconds when the subscription deactivates, if applicablesubscription.deactivationDateValueintegerDuplicate of `deactivationDate` for backward compatibilitysubscription.deactivationDateInSecondsintegerTimestamp in seconds when the subscription deactivatessubscription.deactivationDateDisplaystringFormatted display of `deactivationDate`subscription.deactivationDateDisplayISO8601stringDeactivation date in ISO 8601 format

subscription.beginDisplayEmailEnhancementsstringUser-friendly subscription start date for email displaysubscription.beginDisplayEmailEnhancementsWithTimestringUser-friendly subscription start date and time for email displaynextDisplayEmailEnhancementsstringUser-friendly next charge date for email displaynextDisplayEmailEnhancementsWithTimestringUser-friendly next charge date and time for email displaysubscription.intervalUnitstringUnit of time between billing periods such as `month`subscription.intervalUnitAbbreviationstringAbbreviated unit of time between billing periods such as `mo`subscription.intervalLengthintegerNumber of `intervalUnit`s between chargessubscription.intervalLengthGtOnebooleanWhether `intervalLength` is greater than one

nextChargePreTaxDisplaystringFormatted display of `nextChargePreTax`nextChargePreTaxInPayoutCurrencynumberPre-tax charge amount in payout currencynextChargePreTaxInPayoutCurrencyDisplaystringFormatted display of `nextChargePreTaxInPayoutCurrency`nextChargeTotalnumberTotal charge amount including tax when applicablenextChargeTotalDisplaystringFormatted display of `nextChargeTotal`nextChargeTotalInPayoutCurrencynumberTotal charge amount in payout currencynextChargeTotalInPayoutCurrencyDisplaystringFormatted display of `nextChargeTotalInPayoutCurrency`

<td style={"overflowWrap":"anywhere","wordBreak":"break-word"}>Time unit used with intervalLength to determine when cancellation occurscancellationSetting.intervalLengthintegerNumber of `intervalUnit`s to wait before cancellation

fulfillments.instructionsstringHTML content with delivery instructions such as download links or license keys

instructions.discountTotalDisplaystringFormatted display of `discountTotal`instructions.discountTotalInPayoutCurrencynumberTotal discount in payout currencyinstructions.discountTotalInPayoutCurrencyDisplaystringFormatted display of `discountTotalInPayoutCurrency`instructions.totalnumberTotal amount due for the period in transaction currencyinstructions.totalDisplaystringFormatted display of `total`instructions.totalInPayoutCurrencynumberTotal amount in payout currencyinstructions.totalInPayoutCurrencyDisplaystringFormatted display of `totalInPayoutCurrency`instructions.totalWithTaxesnumberTotal charge amount including taxes in transaction currencyinstructions.totalWithTaxesDisplaystringFormatted display of `totalWithTaxes`instructions.totalWithTaxesInPayoutCurrencynumberTotal including taxes in payout currencyinstructions.totalWithTaxesInPayoutCurrencyDisplaystringFormatted display of `totalWithTaxesInPayoutCurrency`instructions.pricenumberList price before discounts in transaction currencyinstructions.priceDisplaystringFormatted display of `price`instructions.priceInPayoutCurrencynumberList price in payout currencyinstructions.priceInPayoutCurrencyDisplaystringFormatted display of `priceInPayoutCurrency`instructions.priceTotalnumberTotal list price before discounts in transaction currencyinstructions.priceTotalDisplaystringFormatted display of `priceTotal`instructions.priceTotalInPayoutCurrencynumberTotal list price before discounts in payout currencyinstructions.priceTotalInPayoutCurrencyDisplaystringFormatted display of `priceTotalInPayoutCurrency`instructions.unitPricenumberUnit price after discounts in transaction currencyinstructions.unitPriceDisplaystringFormatted display of `unitPrice`instructions.unitPriceInPayoutCurrencynumberUnit price after discounts in payout currencyinstructions.unitPriceInPayoutCurrencyDisplaystringFormatted display of `unitPriceInPayoutCurrency`subscription.initialOrderIdstringInitial order ID that created the subscriptionsubscription.initialOrderReferencestringInitial order reference identifier for the subscription

Name	Type	Description
Event Metadata
reason	string
Account Object
accountobject	Customer account object containing ID, contact information, language, country, and account lookup values
account.idstring	FastSpring-generated customer account ID
account.accountstring	Duplicate of `account.id` for backward compatibility
account.contact.firststring	First name of the customer
account.contact.laststring	Last name of the customer
account.contact.emailstring	Email address of the customer
account.contact.companystring	Company name of the customer when provided
account.contact.phonestring	Phone number of the customer when provided
account.contact.subscribedboolean	Whether the account contact is subscribed to updates
account.address.address line 1string	Primary street address line
account.address.address line 2	string
Subscription Object
subscription.idstring	Unique identifier for the subscription
subscription.quotestring	Associated quote ID if created from a quote
subscription.subscriptionstring	Duplicate of `subscription.id` for backward compatibility
subscription.activeboolean	Whether the subscription is currently active
subscription.statestring	Current state such as `trial`, `active`, `overdue`, `deactivated`, or `canceled`
subscription.isSubscriptionEligibleForPauseByBuyerboolean	Whether the buyer can pause the subscription from their account
subscription.isPauseScheduledboolean	Whether a pause has been scheduled to take effect on the next rebill
paymentMethodActionstring	Whether the payment method changed, such as `updated` or `none`
subscription.liveboolean	Whether the subscription was created in live mode
Pricing
subscription.pricenumber	Amount charged per billing period in transaction currency
subscription.priceDisplaystring	Formatted display of `price`
subscription.priceInPayoutCurrencynumber	Subscription price in payout currency
subscription.priceInPayoutCurrencyDisplaystring	Formatted display of `priceInPayoutCurrency`
subscription.discountnumber	Total discount applied to the subscription in transaction currency
subscription.discountDisplaystring	Formatted display of `discount`
Rebill and Expiration
subscription.nextinteger	Timestamp in milliseconds for the next scheduled billing
subscription.nextValueinteger	Duplicate of `next` for backward compatibility
subscription.nextInSecondsinteger	Timestamp in seconds for the next scheduled billing
subscription.nextDisplaystring	Formatted display of the next scheduled billing date
subscription.nextDisplayISO8601string	Next scheduled billing date in ISO 8601 format
Cancellation and Deactivation
subscription.canceledDateinteger	Timestamp in milliseconds when the subscription was canceled, if applicable
subscription.canceledDateValueinteger	Duplicate of `canceledDate` for backward compatibility
subscription.canceledDateInSecondsinteger	Timestamp in seconds when the subscription was canceled
subscription.canceledDateDisplaystring	Formatted display of `canceledDate`
subscription.canceledDateDisplayISO8601string	Cancellation date in ISO 8601 format
Billing Schedule
subscription.sequenceinteger	Sequence number of the current billing period
subscription.periodsinteger	Total number of billing periods for the subscription
subscription.remainingPeriodsinteger	Number of billing periods remaining
subscription.begininteger	Timestamp in milliseconds when the subscription began
subscription.beginValueinteger	Duplicate of `begin` for backward compatibility
subscription.beginInSecondsinteger	Timestamp in seconds when the subscription began
subscription.beginDisplaystring	Formatted display of the subscription start date
subscription.beginDisplayISO8601string	Start date in ISO 8601 format
Next Charge Details
nextChargeCurrencystring	Three-letter ISO currency code for the next scheduled charge
nextChargeDateinteger	Timestamp in milliseconds of the next scheduled charge
nextChargeDateValueinteger	Duplicate of `nextChargeDate` for backward compatibility
nextChargeDateInSecondsinteger	Timestamp in seconds of the next scheduled charge
nextChargeDateDisplaystring	Formatted display of the next scheduled charge date
nextChargeDateDisplayISO8601string	Next scheduled charge date in ISO 8601 format
nextChargePreTaxnumber	Pre-tax amount for the next charge in transaction currency
Cancellation Settings
cancellationSetting.cancellationstring	Cancellation trigger such as `AFTER_PAYMENT_FAILURE` or `AFTER_LAST_NOTIFICATION`
cancellationSetting.intervalUnit	string
Fulfillment Object
fulfillmentsobject	Container for fulfillment data associated with the subscription
Instructions Array
instructionsarray	Array of billing instruction objects for each subscription period
instructions.productstring	Product ID for the billing instruction period (only present on regular instructions)
instructions.typestring	Type of billing instruction such as `trial` or `regular`
instructions.trialTypestring	Trial type such as `PAID`, `FREE_WITH_PAYMENT`, or `FREE_WITHOUT_PAYMENT`; present only on trial instructions
instructions.isNotTrialboolean	Whether the instruction is not part of a trial period
instructions.periodStartDateinteger	Timestamp in milliseconds for the start of the billing period
instructions.periodStartDateValueinteger	Duplicate of `periodStartDate` for backward compatibility
instructions.periodStartDateInSecondsinteger	Timestamp in seconds for the start of the billing period
instructions.periodStartDateDisplaystring	Formatted display of `periodStartDate`
instructions.periodStartDateDisplayISO8601string	Start date in ISO 8601 format
instructions.periodEndDateinteger	Timestamp in milliseconds for the end of the billing period, if known
instructions.periodEndDateValueinteger	Duplicate of `periodEndDate` for backward compatibility
instructions.periodEndDateInSecondsinteger	Timestamp in seconds for the end of the billing period, if known
instructions.periodEndDateDisplaystring	Formatted display of `periodEndDate`
instructions.periodEndDateDisplayISO8601string	End date in ISO 8601 format
instructions.discountDurationUnitstring	Unit of time over which the discount applies, present only on trial instructions
instructions.discountDurationLengthinteger	Length of the discount duration in `discountDurationUnit`s, present only on trial instructions
instructions.discountPercentinteger	Percentage discount applied during the period
instructions.discountPercentValueinteger	Duplicate of `discountPercent` for backward compatibility
instructions.discountPercentDisplaystring	Formatted display of `discountPercent`
instructions.unitDiscountnumber	Per-unit discount amount in transaction currency
instructions.unitDiscountDisplaystring	Formatted display of `unitDiscount`
instructions.unitDiscountInPayoutCurrencynumber	Per-unit discount amount in payout currency
instructions.unitDiscountInPayoutCurrencyDisplaystring	Formatted display of `unitDiscountInPayoutCurrency`
instructions.discountTotalnumber	Total discount applied during the period in transaction currency

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.

Overview of the subscription.charge.failed webhook

Webhook payload example (expansion enabled)

Navigate this webhook

Payload properties

Reason codes

Overview of the `subscription.charge.failed` webhook