Braintree
This guide outlines the steps for integrating your Braintree account with Recover. The integration relies on the following information from Braintree:
- Real-time Failed Transaction Feed: A real-time feed of all failed payments delivered via a Braintree webhook.
- Customer and Payment Methods: Retrieval of limited customer information and active payment methods linked to a subscription.
- Subscription Status: Access to up-to-date information on the state of each Braintree subscription.
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 Braintree API key with assigned permissions. This key enables Recover to interact with your Braintree environment and manage retries on your behalf.
- Log in as admin to your Braintree account and go to Settings > Team > Manage Roles > + New Role.
- Give the role a name like Butter-Recover-API.
- Check the following Permissions:
Type | Permission |
|---|---|
Transactions | Create Sales |
Transactions | Submit Sales for Settlement |
Customer Management | Manage Customers and Payment Methods (Add/Edit/Delete) |
Processing and Security Options | Processing Options (Add/Edit ) |
Recurring Billing | Manage Subscriptions |
Recurring Billing | Download Subscription Records |
Recurring Billing | View Modifications |
Recurring Billing | View Subscription Plans |
Recurring Billing | View Subscriptions |
Recurring Billing | Search Subscriptions |
Read-Only Access | ALL |
Search | ALL |
After the API key has been generated and shared with Butter, the Butter team will configure API access and create a webhook destination for your account.
This webhook destination is designed to forward invoice charge attempts to Recover. The details of the webhook destination will be provided, allowing you to configure the necessary webhook endpoint in Braintree during the next step.
The webhook endpoint URL will have the following syntax:
Where ts_xxxxx is the transaction source (uniquely generated) for the webhook.
- Click on the settings icon in the upper right-hand corner, then > API > Create a webhook endpoint.
- Copy and past the webhook endpoint URL provided by the Butter team as the Desitination URL.
- In Notifications, select to receive Went Past Due events.
- Click Save.
Recover requires your Braintree account to begin forwarding payment data to Recover before going live. During this pre-launch period, no failed payments will be retried.
Required Pre-Launch Data Ingest | 30 Days |
|---|
Integration with Braintree requires an extended pre-launch data integration because of how Braintree handles payment failure notifications:
- Notifications are sent immediately when a payment fails.
- A second notification is only sent at the end of the dunning process (30 days).
To ensure no payments are missed, Recover must wait until all potential failure notifications have been received before completing the cutover.
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.
Disable Braintree Automatic Retries
The launch process requires careful sequencing to prevent duplicate retries from being executed by multiple retry systems. This involves disabling Braintree Automatic 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.
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.
