Integration Guide
This guide provides comprehensive steps for integrating your enterprise subscription management system and payment service provider(s) with Recover. A standard integration with Recover includes the following key components:
- Transaction Feed: A real-time feed of all successful and failed transactions sent to the Recover Payments API.
- Payment Method Updates: Real-time feed of changes to customer payment methods sent to the Recover Payment Methods Update API.
- Subscription & Invoice Status: Real-time access to the current status of subscriptions and Invoices within the merchant’s system.
- Merchant Webhooks: Configured webhook destinations for receiving retry outcomes and end-of-dunning updates.
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.
The integration architecture is tailored to the Merchant's desired functionalities with Recover, as well as any unique characteristics of their Subscription and Payment systems.
The integration process is guided by the following configuration options:
- Dunning window length: 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.
- Retry Status Endpoint: This endpoint is used by Recover to validate whether a payment retry should be attempted before submission.
- Retry Results: Recover webhook that notifies the Merchant of the outcome of each retry attempt, whether successful or failed. These notifications assist Merchants in reconciling payments within their Subscription Management System.
- Optional: Supports payment reconciliation & subscriptions management.
- If required by the Merchant, a webhook consumer RetryResults endpoint will need to be built by the Merchant as part of the integration.
- End-of-dunning Actions: Recover webhook notifies the Merchant when the dunning process is complete for an invoice, indicating that no further payment retries will be attempted. This notification helps determine the appropriate end-of-dunning actions for a subscription.
- Optional: Supports subscription management actions if invoices are not recovered in dunning.
- If required by the Merchant, a webhook consumer End of Dunning endpoint will need to be built by the Merchant as part of the integration.
The first step in integrating your subscription platform with Recover is mapping your system's payment data to align with the request body schema of the Payments API.
A complete list of the required fields, as well as all possible fields can be reviewed in the Recover Payment Object Properties resource.
- Accurately identifying the source and correctly mapping properties & values is essential to ensure that the events sent to Recover contain all the necessary information for successful payment retries.
- Any errors in mapping can directly lead to failures in payment recovery.
Although the required properties of a Recover Payment Event represent only a small subset of the available fields, providing more data enhances the overall performance of the service.
The merchant is required to provision several resources to integrate with Recover, depending on the Merchant technical configuration, not all of these may be required. While these can be implemented using any technology, they must adhere to the following patterns:
- Merchant endpoints for securing retries and consuming webhooks:
Please review the supported Authentication options for these endpoints. For complete API documentation, please review the Recover API Reference.
Recover Sandbox Endpoint
For testing the merchant eventing service, test transactions can be sent to Recover using the production payments api url. Both test-failures and test-successes should be sent to this endpoint:
Your dedicated solutions engineer will provision a dedicated sandbox API key to call this endpoint.
Merchant Sandbox Endpoints
Sandbox versions of any required merchant endpoints must be available to facilitate integration testing of all necessary handshakes required by Recover. The Butter team will require sandbox credentials to call these endpoints.
Required sandbox url:
Depending on your configuration, these services may need staging URLs :
Your dedicated Solutions Engineer will collaborate with you to validate sandbox test cases and ensure the end-to-end functionality of the API integrations. This will involve executing payment retries using the integrated sandbox services.
In this pre-launch data phase, payment events start flowing to Recover at least 7 days before going live. No failed payments will be retried during this period.
Required Pre-Launch Data Ingest | 7-14 Days |
|---|
This phase is used for a few things:
- Final data quality checks that live data has all the necessary information
- Ensures that any failed payment is fully captured by Recover prior to the system going live.
This phase starts only after all prior setup steps have been successfully completed.
Once all services are fully tested and the data is confirmed to be ready for production, its time to switch your retry strategy to Recover.
Launch Window | 1-14 Days |
|---|
Merchants generally go live with Recover in one of two ways:
- Full Cutover: On launch day, 100% of failed payments are sent to Recover and the old Merchant retry strategy is turned off.
- Used when configurations do not allow for incremetal load to be sent to Recover
- Used when old retry strategy had low recovery rates.
- Incremental Cutover: On launch day, only a portion of failed payments is sent to Recover, with the load gradually increasing to full capacity over 1–2 weeks.
- Incremental load enables additional QA of the production data & retry strategy while minimizing the impact on the Merchant.
- Supports A/B testing against old retry strategy and Recover.
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.
