Integration Guide

introduction 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 integration architecture configuration options 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 api reference docid\ oylr8swr hn9dqzoscpcw 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 api reference docid\ oylr8swr hn9dqzoscpcw endpoint will need to be built by the merchant as part of the integration integration steps service integration payment object mapping 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 api reference docid\ oylr8swr hn9dqzoscpcw a complete list of the required fields, as well as all possible fields can be reviewed in the recover payment object properties docid\ j6svye nzgbcop9av0ua 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 provisioning merchant resources 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 eventing service to send payment events to the recover api reference docid\ oylr8swr hn9dqzoscpcw endpoint eventing service to send payment method updates to the recover api reference docid\ oylr8swr hn9dqzoscpcw endpoint merchant endpoints for securing retries and consuming webhooks api reference docid\ oylr8swr hn9dqzoscpcw endpoint api reference docid\ oylr8swr hn9dqzoscpcw webhook consumer (if required) api reference docid\ oylr8swr hn9dqzoscpcw webhook consumer (if required) please review the supported authentication docid\ x cpa5gd9fcb6rydarzov options for these endpoints for complete api documentation, please review the api reference docid\ oylr8swr hn9dqzoscpcw sandbox testing 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 https //api butterpayments com/recover/payments https //api butterpayments com/recover/payments 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 retry status docid\ idcldp2jt0gopaquo xyx endpoint depending on your configuration, these services may need staging urls retry results docid\ aphoqkslqpubkr7vo46x3 & end of dunning docid xpgisw24gh d43ozixvg webhook consumer endpoints 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 pre launch data ingest 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 required pre launch data ingest 7 14 days 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 launching with recover 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 launch window window 1 1 14 days 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 incremental 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 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