Upcoming Charge Funding Alert

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.

iPhone lock screen showing a push notification: Upcoming charge for Netflix — Add money to cover your upcoming Netflix subscription charge for $22.99 on Mar 14

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.

If 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`	`RECURRING_MONTHLY`, `RECURRING_ANNUALLY`, 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

Configuration decisions for your team:

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.

General

SDK

CardSwitcher

SubscriptionManager

TransactionLink

Detect

Vaulting

Shopping

Merchant Account Linking

Upcoming Charge Funding Alert

Problem

Solution

Flow

Implementation

Receive the CARD_UPDATED webhook

Fetch subscription or bill details

Evaluate the funding condition

Send the notification

Expansion Path

​Problem

​Solution

​Flow

​Implementation

Receive the CARD_UPDATED webhook

Fetch subscription or bill details

Evaluate the funding condition

Send the notification

​Expansion Path

Problem

Solution

Flow

Implementation

Expansion Path