Failed Payment Wall

Supported for Stripe.

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

1. Create a test customer and attach Stripe’s “Decline After Attaching” card to a customer - card number 4000000000000341.
2. Create a new invoice for that customer and add a subscription item.
3. Set to auto-charge the invoice to the customer.
4. Review and finalize the invoice. This will attempt to charge the number that is set to be declined and create a failed payment.
5. 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