Team
Launch LogCancel Flows
Quick Start GuideFurther ConfigurationCustom StylingMulti-Language SupportEmail-Verified Cancel FlowA/B TestingCancel Flow TestingPause WallFailed Payment Recovery
Payment RecoveryCampaign CustomizationFailed Payment WallReactivations
ReactivationsCampaign Customization GuideCustomer Health
Customer HealthData Integrations
Data APIWebhooksEvent TrackingBilling Providers
Payment Provider OverviewSlackStripeChargebeePaddle ClassicPaddle BillingBraintreeZuoraSupport
FAQsFailed Payment Wall
Churnkey can automatically block access to your web app for customers whose most recent payment failed. This is done by calling a function listed under window.churnkey
following the same patterns as initializing the cancel flow. Note that this must be called after the Churnkey script is loaded i.e. Step 1.
window.churnkey.check('failed-payment', {
subscriptionId: 'SUBSCRIPTION_ID' // optional
customerId: 'CUSTOMER_ID', // required
authHash: 'HMAC_HASH', // required
appId: 'YOUR_APP_ID', // required
mode: 'live', // set to 'test' to hit test billing provider environment
provider: 'stripe',
softWall: false, // set to true to allow exiting wall
forceCheck: false, // recommended to leave this to false to avoid redundant checks
gracePeriodDays: 0, // allow a grace period in which failed payment wall is shown but can be exited (soft wall)
ignoreInvoicesWithoutAttempt: false, // set to true to ignore invoices without a failed charge
handleLogout() {
// optional, if defined, a "Logout" button will show
},
handleSupportRequest() {
// optional, if defined, a "Contact Support" button will show
},
handleCancel(customer) {
// optional, if defined, a "Cancel Subscription" button will show
},
onUpdatePaymentInformation(customer) {
// optional, called after customer updates payment information and overdue invoice is charged
},
onFailedPaymentWallActivated(){
// optional, called when wall is activated
},
onFailedPaymentWallClose() { }, // optional
onCancel(customer) { }, // optional
onError(error, type) {
// types below
}
})
This will trigger an asynchronous check to see if the customer has an outstanding failed payment. If their is a failed payment, a blocking wall will be displayed on top of your application with a streamlined UI to allow customers to update their payment information. In addition to charging the outstanding invoice, Churnkey will automatically add this card to the customer’s Stripe account and set the new payment method as the default for future invoices.
Criteria for Showing the Failed Payment Wall
Specifically, the failed payment wall is shown if any recent invoices have a status of open
and have a due date in the last 60 days, and if the most recent invoice is not paid
.
If you would like to allow customers to exit the failed payment wall, set softWall
to true
.
If you would like to only show the failed payment wall to customers whose payment method has been attempted and failed, set ignoreInvoicesWithoutAttempt
to true
. By setting this to true, it will not be triggered if the failed invoices do not have a payment method attached. This is typically the case with invoices that are set to be manually sent instead of charged automatically.
Testing the Failed Payment Wall
Stripe
- Create a test customer and attach Stripe’s “Decline After Attaching” card to a customer - card number
4000000000000341
. - Create a new invoice for that customer and add a subscription item.
- Set to auto-charge the invoice to the customer.
- Review and finalize the invoice. This will attempt to charge the number that is set to be declined and create a failed payment.
- After the failed payment, trigger the failed payment wall for this test customer as shown above.
Error Types
The following errors can be sent to your onError(error, type)
function while using the Failed Payment Wall:
FAILED_PAYMENT_WALL_INITIALIZATION_ERROR
FAILED_PAYMENT_WALL_UPDATE_CARD_ERROR
FAILED_PAYMENT_WALL_CANCEL_ERROR