--- title: Stripe Billing slug: stripe-billing description: Integrate Stripe Billing with Recover for enhanced payment recovery. Set up real-time transaction feeds, manage subscriptions, and configure dunning actions. docTags: createdAt: 2024-11-15T00:01:10.999Z --- # Overview 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. *** ## Configuration Options 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. *** ## Supported Integration :::hint{type="success"} 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. ::: *** # Integration Steps ## Create Stripe API Key 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: 1. Click on "**Create restricted key**" 2. Set the key name to "**Butter**" 3. Assign the following permissions for each resource type listed below: ***Under "All core resources": *** | **Field** | **Permission** | | -------------------------- | -------------- | | Charges | Write | | Customers | Read | | Disputes | Read | | Files | Read | | PaymentIntents | Write | | SetupIntents | Read | | Sources | Read | | Tokens | Read | | Balance transaction source | Read | ****** ***Under "All Billing resources":*** | **Field** | **Permission** | | ------------- | -------------- | | Credit Notes | Read | | Invoices | Write | | Subscriptions | Write | ****** ***Under "All Reporting resources":*** | **Field** | **Permission** | | ---------------------------- | -------------- | | Report Runs and Report Types | Read | ****** ***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. 1. **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. 2. Securely transmit the API key to the Butter Support team via the secure webpage provided to you by the Butter team. ![](https://api.archbee.com/api/optimize/KC9cS61afQF1PMLFYj2ra/UsHPEWGz3JpSMUE8IfL7E_screenshot-2024-01-26-at-33719-pm.png "Butter Restricted API Key Example") *** ## Butter Initializes Recover for your Account :::hint{type="info"} 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: ```none webhooks.recover.serverless.services.butterpayments.com/stripe/ts_xxxxx ``` Where **ts\_xxxxx** is the transaction source (uniquely generated) for the webhook. ![](https://api.archbee.com/api/optimize/KC9cS61afQF1PMLFYj2ra/3KBaiGO0ULFtylZ2YRYD5_screenshot-2024-01-29-at-110407-am.png "Butter Created Webhook Example") *** ## Configure Stripe End-of-Dunning Action 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 ** 1. Go to **Settings -> Billing -> Subscriptions and emails **and scroll down to **Manage failed payments for subscriptions** 2. 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** 1. Go to **Settings -> Billing -> Subscriptions and emails **and scroll down to **Manage failed payments for subscriptions** 2. Set ***Subscription Status*** to `mark the subscription as unpaid` or `leave the subscription past-due` 3. 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. *** ## Pre-Launch Data Ingest 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. *** ## Launch Day with Recover :::hint{type="success"} 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: 1. Go to **Settings -> Billing -> Subscriptions and emails **and scroll down to **Manage failed payments for subscriptions** 2. 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. ![](https://api.archbee.com/api/optimize/KC9cS61afQF1PMLFYj2ra/_LVZnElifH09qz_zSbPpS_screenshot-2024-01-26-at-32948-pm.png "Typical Subscription Failed Payments Settings") **Additional Configurations** There are a few additional configurations that can be added in discussion with you dedicated solutions engineer. 1. Enable Card Rotator: We recommend enabling this by default as it helps improve Recover performance unless the merchant indicates otherwise. 2. Enable one-off invoices**: **If you process non-recurring, one-off invoices, Recover can be configured to retry these as well. ## Post-Launch Monitoring 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. ![](https://api.archbee.com/api/optimize/ulzW_Oabf9OtJM_doZF6z-peeIv9amZLEW5MaVVeFJr-20241210-205545.png) :::hint{type="success"} Interested in working with Butter to bring more revenue back to your business? Reach out to us here: [contact@butterpayments.com](mailto\:contact@butterpayments.com). :::