Stripe Billing
This guide outlines the steps for integrating your Stripe Billing account with Recover. The integration utilizes the following information from Stripe:
- Real-Time Transaction Feed: A live feed of all failed and successful transactions via Stripe webhooks.
- Invoice and Customer Entities: Access to real-time information about the status of Invoices and limited Customer data to support transaction retries.
- Subscription Status: Access to real-time information about the status of Stripe subscriptions.
These integrations enable secure and efficient payment recovery while ensuring duplicate transactions are avoided, even when a subscription has been canceled.
Recover has a few configuration options that the Merchant can select from, these include:
- Dunning Length: Required by Recover, this is the length of time determined by the business in which a failed payment will be attempted to be recovered. A common length many merchants settle on is 30 days.
- End of Dunning Actions: If configured, Recover will cancel subscriptions on the Merchant's behalf when an invoice is unable to be recovered by the close of the dunning cycle.
- Card Rotator: If enabled, this will help improve payment recovery performance by intelligently using alternative cards on file.
- One-off Payment Recovery: If enabled, Recover will attempt to recover one-off invoices on your behalf, in addition to recurring invoices.
Butter offers direct support for integrating your system with Recover by assigning a dedicated Butter Solutions Engineer. This engineer will serve as your hands-on resource, guiding you through the configuration process and ensuring a smooth integration with Recover.
Recover requires a dedicated Stripe API key with the appropriate permissions. This key allows the Recover service to access your Stripe environment and perform retry operations.
To create an API key go to Developers > API Key within the Stripe portal and follow these steps:
- Click on "Create restricted key"
- Set the key name to "Butter"
- Assign the following permissions for each resource type listed below:
Under "All core resources":
Field | Permission |
|---|---|
Charges | Write |
Customers | Read |
Disputes | Read |
PaymentIntents | Write |
SetupIntents | Read |
Sources | Read |
Tokens | Read |
Under "All Billing resources":
Field | Permission |
|---|---|
Credit Notes | Read |
Invoices | Write |
Subscriptions | Write |
Under "All webhook resources":
Field | Permission |
|---|---|
Webhook Endpoints | Write |
Click on "Create key" at the bottom of the page to save the changes and create the key.
- Immediately copy the newly created API key as this will be the only opportunity you will have to copy the key. After this step the key will no longer be visible.
- Securely transmit the API key to the Butter Support team via the secure webpage provided to you by the Butter team.
Butter initiates this automated step once we receive a Stripe API key from your account with all the necessary permissions.
Once the API key has been generated and provided to Butter, our system will programmatically configure API integration and a webhook for your Stripe account.
This webhook is used to forward invoice charge attempts to Recover. This step needs to be completed at least 1 week prior to your launch date to ensure seamless integration and functionality.
After the webhook is created, it will be visible in the "Webhooks" section within the "Developers" area of the Stripe portal under "Hosted endpoints".
The webhook endpoint URL will have the following syntax:
Where ts_xxxxx is the transaction source (uniquely generated) for the webhook.
Recover can be configured to either have the subscription canceled at the end of dunning, if an invoice has not been recovered, or leave the subscription uncanceled, allowing the merchant to cancel the subscription if and when they prefer.
Option 1: Recover manages end-of-dunning subscription cancellation
- Go to Settings -> Billing -> Subscriptions and emails and scroll down to Manage failed payments for subscriptions
- Set Subscription Status to leave the subscription past-due
At the end of the dunning cycle, Butter will cancel the subscription, triggering the customer.subscription.deleted webhook in Stripe. Note that if a subscription is canceled, a new subscription is needed if the customer reactivates.
Option 2: Merchant handles end-of-dunning actions
- Go to Settings -> Billing -> Subscriptions and emails and scroll down to Manage failed payments for subscriptions
- Set Subscription Status to mark the subscription as unpaid or leave the subscription past-due
- Set Invoice Status to mark the invoice as uncollectible or leave the invoice past-due
At the end of dunning on a failed invoice, Recover updates the subscription in Stripe by adding the metadata attribute metadata.butter_dunning_complete with the current Unix timestamp in seconds as the value.
Example: ”metadata”: { "butter_dunning_complete": "1695153123" }
Once the subscription is updated by Recover, Stripe will trigger the customer.subscription.updated webhook containing the above metadata attribute.
Recover requires your Stripe account to begin forwarding payment data before going live. During this pre-launch period, no failed payments will be retried.
Required Pre-Launch Data Ingest | 7 Days |
|---|
The purpose of this data ingestion phase is to ensure that all failed payments are fully captured by Recover before the system goes live.
This phase starts only after all prior setup steps have been successfully completed.
On launch day, your Butter Solutions Engineer will work closely with your team to make sure all configurations are setup correctly and done in the required order.
Disabling Stripe Smart Retries
The launch process requires careful sequencing to prevent duplicate retries from being executed by multiple retry systems. This involves disabling Stripe Smart Retries and any third-party decline salvage services.
Once this step is complete, Butter will configure Recover to take full responsibility for managing all retry attempts on failed invoices moving forward.
To disable Stripe Smart Retries:
- Go to Settings -> Billing -> Subscriptions and emails and scroll down to Manage failed payments for subscriptions
- Select Use a custom retry policy for subscription.
The following screen capture depicts the typical settings but note that this can vary based on your specific requirements.
Additional Configurations
There are a few additional configurations that can be added in discussion with you dedicated solutions engineer.
- Enable Card Rotator: We recommend enabling this by default as it helps improve Recover performance unless the merchant indicates otherwise.
- Enable one-off invoices: If you process non-recurring, one-off invoices, Recover can be configured to retry these as well.
Once you are live with Recover, the Butter team will be closely tracking performance of failed payments as they are ingested and then optimally scheduled for Retry.
ButterBoard
As part of your launch with Recover, you will receive email invitation to your Butter Account and access to your company's ButterBoard. The ButterBoard provides realtime performance of revenue recovered, your recovery rate, and feed of most recent recovered transactions.
