Stripe Billing

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 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 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 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 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 initializes recover for your account 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 webhooks recover serverless services butterpayments com/stripe/ts xxxxx where ts xxxxx is the transaction source (uniquely generated) for the webhook 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 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 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 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 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 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 interested in working with butter to bring more revenue back to your business? reach out to us here contact\@butterpayments com