Click “Copy Page” to copy this use case as markdown.
Problem
When a user adds their debit or prepaid card to an online merchant account that has an active subscription or recurring bill, there’s a risk that the next charge will fail if the account doesn’t have sufficient funds. Unlike credit cards, debit and prepaid cards draw directly from the account balance. A declined charge can result in a missed payment, service interruption from the merchant, overdraft fees from the issuing bank, and a poor user experience for the new cardholder.
Today, users have no visibility into upcoming charges for bills or subscriptions where they’ve just provisioned their card through Knot. They switch their card, move on, and find out days later when a charge fails.
Solution
Immediately after a card is switched, check whether the merchant account has an upcoming subscription charge that exceeds the user’s available balance. If it does, proactively notify the user to fund their account before the charge hits.
This turns a potential failed payment into a proactive funding moment, reducing declines, improving the user experience in your app, and reinforcing trust.
Flow
Implementation
Receive the CARD_UPDATED webhook
When a user successfully switches their card at a merchant, Knot emits the CARD_UPDATED event to your webhook. With SubscriptionManager enabled, the payload includes subscription IDs for the subscription(s) or bill(s) on the user’s merchant account.Key fields| Field | Purpose |
|---|
external_user_id | Used to identify the user in your system. |
merchant.name | Merchant display name for the notification. |
data.subscriptions[].id | Subscription IDs used to fetch full subscription details from Get Subscription By ID. |
data.subscriptions is empty, the merchant account does not have a subscription or bill and no further action is needed. Fetch subscription or bill details
For each subscription ID in the webhook payload, call Get Subscription By ID to get the subscription or bill details, including the name, status, next billing date, price, etc. The full subscription object is documented here.Key fields| Field | Purpose |
|---|
name | Subscription display name (e.g., “Netflix Standard”). |
status | Only act on ACTIVE subscriptions. |
next_billing_date | When the next charge will occur. |
price.total | The amount that will be charged (e.g.22.99). |
price.currency | Currency code (e.g.USD). |
billing_cycle | MONTHLY, YEARLY, etc. Useful for messaging. |
Evaluate the funding condition
Once you have the subscription details and the user’s account balance, apply two checks:upcoming_charge = parseFloat(subscription.price.total)
days_until_charge = subscription.next_billing_date - today
IF subscription.status == "ACTIVE"
AND days_until_charge <= THRESHOLD_DAYS
AND upcoming_charge > user.account_balance
THEN
trigger funding alert
| Parameter | Suggested Default | Considerations |
|---|
THRESHOLD_DAYS | 7 days | Too short and the user may not have time to fund. Too long and the alert feels premature. 5-10 days is a reasonable range. |
| Minimum charge amount | $0 (no minimum) | You may want to skip alerts for very small charges (e.g. certain Apple subscriptions <$1) to avoid notification fatigue. |
Send the notification
If the conditions are met, send a push notification (and in-app message) to the user:
Upcoming $22.99 charge for Netflix.
Deposit money to cover your upcoming Netflix subscription charge for $22.99 on Mar 14th.
Deeplink the user to a screen where they can fund their account to cover the upcoming charge. Expansion Path
When the user’s balance is short, offer access to a short-term earned-wage advance to cover the upcoming charge. Instead of just telling the user to add funds, the notification can include an option to access wages they’ve already earned but haven’t yet been paid. This turns a potential declined payment into a seamless funding moment. The user taps to advance just enough to cover the charge, the subscription pays on time, and the advance is repaid on their next payday.
