Skip to main content
This page is the deep dive on what happens after a subscription deduction fails, and on the payment methods bound to a subscription. For the shape of the subscription APIs and which notifications to subscribe to, start at the Subscription FAQ; for deferred starts and amount updates see Subscription lifecycle.

​
A subscription deduction failed. Will Waffo retry it automatically?

Yes. You never have to trigger a subscription retry yourself, and you should not create a replacement order for the same period.
  • The period’s order moves into a needs retry state and Waffo re-attempts it on a schedule derived from your contract’s retry strategy.
  • Every attempt — including the failure reason and the attempt count — is pushed on the subscription payment order notification, so you can follow the sequence without polling.
  • The subscription itself keeps running while retries are in flight. Its status does not change because a period failed.

​
How is the retry schedule decided?

By a retry strategy on your acquiring agreement, and the strategy is selected per billing cycle rather than one global setting. Waffo resolves the strategy from the subscription’s periodType and periodInterval into one of six buckets. The mapping is by the length of the cycle, and the bucket boundaries are not where the names suggest: Two consequences that surprise people: a quarterly subscription (MONTHLY + 3) uses the MONTHLY bucket, not QUARTERLY; and a half-yearly one (MONTHLY + 6) is the one that lands in QUARTERLY. DEFAULT is also used when your agreement has no strategy configured for the resolved bucket. Each bucket carries three knobs: the retry interval, the interval unit (days), and the maximum number of attempts for that period. The values are commercial terms rather than platform constants — ask your Waffo contact for the policy configured on your account, and do not hardcode an assumed schedule in your reconciliation logic.

​
Is there an overall cap on retries, on top of the per-period maximum?

Yes. Independently of your contract’s per-period maximum, card retries are capped by a rolling window across the account, so that Waffo stays within card scheme rules on retry frequency.
  • The window is rolling, not calendar-based: it always looks at the trailing period, not at a calendar month.
  • When an attempt would breach the window, it is not failed — it is deferred to the first date on which it fits.
  • Waffo does not publish the numeric ceiling, because it tracks card scheme requirements rather than a Waffo product decision. Treat the window as a reason a retry may land later than your contract’s interval predicts.
Attempts made on a backup payment method are deliberately excluded from this window (see below), so an immediate backup attempt never consumes the allowance for the default method.

​
When does Waffo stop retrying, and what happens to the subscription?

Retries end when any of the following holds: The important part, and the most common source of confusion: When retries are exhausted, only that billing period’s order is closed. The subscription’s own status is left untouched — it does not move to a cancelled or suspended state, and the next period will be attempted on schedule. So a closed period order is not a signal to revoke the customer’s access permanently. If you want dunning behavior — suspend the entitlement after N failed periods, cancel after M — you must implement that on your side from the period-level notifications, and call the cancel API yourself when your policy says so.

​
Can I tell from the API response whether a particular failure is retryable?

Not from a dedicated flag. There is no merchant-facing “retryable” field on the subscription failure response, the async notification, or the inquiry response on the current release. Determine where you stand from:
  • the period order’s status (still retrying vs. closed), and
  • the failure code returned for the attempt, and
  • the attempt count on the notification against the strategy for your contract.
Do not build logic against a retryPayment or retryAble field — they are not part of the merchant contract and are not populated for you.

​
I cancelled a subscription while a retry was pending. Do those retries stop?

It depends on one setting in your agreement, and the scope is narrower than “everything stops”:
  • Orders waiting for their next retry are closed on cancellation — but only if the close-retries-on-cancellation setting is enabled on your agreement. It is off by default, so confirm it with your Waffo contact if your requirement is that no further attempt is ever made after a cancellation.
  • Orders already submitted to a payment method are never force-closed by cancellation. Waffo keeps listening for their result and reports the real outcome, because the money may already be moving. Expect that a cancelled subscription can still produce one final success or failure notification.
  • Orders that were already in a final state are unaffected.
Practical consequence: after you call cancel, keep your webhook handler able to accept one more payment result for that subscription.

​
Can one subscription have more than one payment method?

Yes. A subscription carries an ordered list: one default method plus any number of backups in priority order. Users manage the list themselves on the hosted subscription management page; the subscription detail response returns canChangePaymentMethod and the bound list so you can render your own view. Each bound method has its own status:

​
Why does adding a payment method create a zero-amount order?

Because the method has to be proven chargeable before Waffo will bill it. When a user adds a method:
  1. Waffo creates a zero-amount authorization order dedicated to verifying the method.
  2. The response returns a checkout link for the user to complete the authorization. The link is cached, so retrying the add for the same method returns the same link rather than opening a second attempt.
  3. The method is stored as IN_PROGRESS and not as the default.
  4. On successful authorization it flips to ACTIVE. If the credential cannot be resolved afterwards, it goes to CLOSED instead — it never silently stays pending.
The verification order is short-lived, so send the user to the link promptly rather than storing it for later.

​
What happens when the default payment method fails to charge?

If backups are bound, Waffo tries them immediately, in priority order, without waiting for the retry interval. That is the whole point of a backup: it converts a multi-day retry cycle into a same-moment second attempt.
  • The next retry time for the backup attempt is set to now.
  • Backup attempts are not added to the rolling window, so they do not consume the default method’s allowance.
  • Backup attempts do not trigger the retry-exhausted email to the user.
  • Once every backup has been tried and failed, the default method is restored and the normal interval-based strategy resumes.

​
Which payment-method changes are blocked?

​
The user’s card is about to expire. Will Waffo warn them, or refresh the card?

Neither is safe to assume, and this is worth reading carefully because it is the most common wrong expectation:
  • Waffo does not refresh stored cards from issuer-side card updates. There is no automatic account-updater integration. When a bank reissues a card with a new number or expiry date, the stored credential does not silently follow — plan for re-binding.
  • Waffo does surface an expiring-soon flag on the subscription detail response for methods approaching their expiry date, so you can prompt the user in your own product. Treat that flag, not an email, as the signal to act on.
  • Once the expiry date passes, a daily check moves the method to EXPIRED and it stops being chargeable.
  • Wallet-type saved methods are different: where the wallet itself notifies Waffo that a credential was updated or unlinked, that update is applied. This does not extend to plain stored cards.
The durable safeguard is to keep at least one backup method bound on every subscription, and to prompt the user as soon as the expiring-soon flag appears.

​
The shopper’s card was rejected at checkout before any charge. Why?

Because some card products are not suitable for recurring billing, and your agreement can carry a list of blocked card sub-types for subscriptions. During checkout Waffo looks up the card’s BIN, and if its sub-type is on that list the card-based methods are removed from the options. If nothing is left, the shopper sees a message along the lines of:
Sorry, we do not accept this type of card for subscriptions. Please try a different card (e.g., standard Credit or Debit card).
Notes for handling this:
  • The list is configured per agreement. There is no fixed platform-wide blocklist, so ask your Waffo contact what is configured for your account.
  • The check happens at checkout, on the card the shopper actually enters — not when you create the subscription. So a subscription create can succeed and the shopper still be turned away on the checkout page.
  • Your recovery path is the same as any decline: ask the shopper for a different card. Retrying the same card will not change the outcome.

​
I did not pass numberOfPeriod. When does the subscription end?

An omitted numberOfPeriod does not mean “forever in practice” — your agreement carries a maximum duration in years for a subscription, and Waffo resolves the total period count from it:
  • With numberOfPeriod omitted, the total period count and the end time are derived from the start time plus the agreement’s maximum duration. The create request is accepted; nothing is rejected. The derived values are written when the first period succeeds, so read them back from the subscription rather than computing them yourself.
  • With numberOfPeriod supplied but long enough that the last deduction would fall beyond that maximum duration, the create is rejected rather than truncated. The same check applies to numberOfTrialPeriod. You get a no-available-payment-method error, which in this case means “no agreement can carry a subscription this long”, not “this card is unsupported”.
Card expiry is not an input to either calculation. A card expiring next year does not shorten the subscription; it just means the method will move to EXPIRED and you will need a new one bound.