Overview of the subscription.charge.failed webhook
subscription.charge.failed webhookWhen 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.failedwebhook - 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.
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
reasonvalue as a soft decline — FastSpring will continue dunning per your configuration. New codes may be added without breaking changes.