Sticky Recovery Integration Guide (Dunning Endpoint)

The guide provides a detailed roadmap for integrating Sticky Recovery solution.

📝 Introduction

Welcome to the Sticky Recovery Solution integration guide! This document is designed to help technical teams seamlessly integrate sticky.io's advanced payment retry technology into your systems. It includes step-by-step instructions, detailed API information, and essential support resources to ensure a smooth integration process. Let's enhance your payment recovery strategy with our Sticky Recovery Solution.

📓 Summary

sticky.io's Sticky Recovery solution is a cutting-edge approach to subscription payment management. It uses a sophisticated machine learning algorithm to optimize the retrying of declined transactions. The integration process is recognized for its simplicity and efficiency, facilitating a seamless transition and integration with minimal disruption to existing systems. However, it's important to note that timelines may vary depending on the platform being integrated.

⚠️ Prerequisites

Before integrating sticky.io's Sticky Recovery solution into your system, it's essential to meet specific prerequisites to ensure a smooth and effective implementation. These prerequisites are designed to prepare your environment and team for the integration process.

API Compatibility

• Your system should be able to handle JSON formatted data, as the Sticky Recovery API communicates using JSON responses.
• Ensure compatibility with RESTful API standards, as the Sticky Recovery solution uses RESTful APIs for communication.

Data Readiness

• Prepare to provide essential transaction data, such as BIN (Bank Identification Number), decline reasons, transaction amounts, and currency.

SessionId Management

• Be prepared to send sticky.io unique sessionId (generated by sticky.io), which is crucial for tracking payment attempts and optimizing the retry process.
• Ensure your system can store and pass these sessionId back to the Sticky Recovery API for subsequent retry attempts, if necessary.

ℹ️ Functional Overview

sticky.io's Sticky Recovery solution is an innovative API-driven service crafted to optimize payment recovery for subscription-based businesses. With advanced machine learning algorithms, it intelligently predicts optimal retry dates for declined transactions, enhancing payment success rates and reducing involuntary churn.

Key Functions and Features

Machine Learning Driven Dunning Optimization:

• Utilizes historical data and real-time transaction insights to predict optimal retry dates and times.
• Adapts to individual customer payment patterns, offering a personalized approach to payment recovery.

API-Driven Integration:

• Easy-to-integrate API endpoints that seamlessly plug into existing payment systems.
• Platform-agnostic design, compatible with a wide range of payment gateways and processors.

Automated Payment Recovery:

• Reduces the need for manual intervention in the payment retry process.
• Offers a fully managed service, alleviating the merchant's burden in managing decline strategies.

Enhanced Revenue Recovery:

• Proven to recover a significant percentage of revenue that would otherwise be lost to payment declines.
• Minimizes the impact of involuntary churn on subscription-based revenues.

Dynamic Risk Management:

• Balances revenue recovery needs with MID (Merchant Identification Number) health management.
• Reduces the frequency of declines and associated fees, improving overall transaction health.

Comprehensive Data Analysis:

• Analyzes a variety of factors including decline codes, BINs (Bank Identification Numbers), payment providers, currency, and consumer behavior.
• Continuously evolves with new data, ensuring the effectiveness of the retry strategies.

Session Management:

• Unique sessionId for tracking and optimizing each payment attempt.
• Retains session data for enhanced analysis and improved retry predictions.

Maximum Retry Attempts and Status:

• Merchants have the flexibility to set the maximum retry attempts threshold anywhere between 1 and 5. This range is carefully chosen based on extensive data analysis and industry best practices. It strikes an optimal balance, maximizing successful recoveries while minimizing customer friction and potential negative impacts on customer experience. This customization allows for a tailored approach to payment recovery that aligns with each merchant's specific business needs and customer relationship strategies.

🚧

For each retry attempt, the system provides a status indicator that will be either 'ACTIVE' or 'HOLD'.

• ACTIVE: Indicates that the retry process is ongoing, and the transaction is currently in the process of being retried according to the predefined schedule.
• HOLD: Signifies that the retry attempts for a particular transaction have been put on hold. This could be due to reaching the maximum number of retries or other predefined criteria set during onboarding.

Operational Flow

For visual representation, please refer to the Flow Diagram section.

• Upon receiving a declined payment response from the gateway, the merchant makes an API call to the sticky.io Sticky Recovery service with the declined transaction details.
• Sticky Recovery processes this information and returns a calculated retry date, retry time, retry status, and sessionId for the first retry attempt.
• The merchant schedules the retry attempt per the provided date/time, maximizing the chances of a successful transaction, and stores the sessionId for subsequent retry attempts.
• Upon receiving an approved payment response from the gateway for the retry attempt, merchants need to report the result (status=APPROVED) back to the Sticky Recovery Service through the complete session API.
• Upon receiving a declined payment response from the gateway for the retry attempt, the merchant makes another API call to the sticky.io Sticky Recovery service with the newly declined transaction details and includes the sessionId from the previous attempt.
• At any point in the retrying process, if the ​​sticky.io Sticky Recovery service responds with a retry status of “HOLD”, it signifies that merchants should not attempt any further retries. In this case, merchants should close the session by reporting the DECLINED status back to the Sticky Recovery Service using the complete session API.

⚡ API Endpoints

The Sticky Recovery Solution consists of two main API endpoints, each designed to handle specific aspects of the payment retry process. Below are the detailed parameters for both endpoints. It's essential to implement both for full integration.

1st API Endpoint: Initiate Retry Session

This endpoint can be accessed via two methods, each with its own documentation:

• GET Method: Sticky Recovery GET Endpoint Documentation
• POST Method: Sticky Recovery POST Endpoint Documentation

2nd API Endpoint: Complete Session

• POST Method: Complete Session POST Endpoint Documentation

This API endpoint enhances our initial payment recovery service. While the first endpoint adeptly provides retry dates for unsuccessful payments, it's designed to focus on scheduling rather than capturing the outcomes. To address this, the "Complete Session" endpoint empowers you to report the results of the dunning cycle, further honing the predictive powers of the Sticky Recovery service. Since the payment isn't processed by sticky.io, it's crucial to implement this endpoint to accurately measure the service's performance.

⚙️ Parameters

1st API Endpoint: Initiate Retry Session

• sessionId (Optional): A unique identifier (generated by sticky.io) specific to the dunning session. Automatically generated if not provided. Do not pass a sessionId for the first API call. This should be submitted in the request to obtain subsequent retry attempts. It informs the system what retry attempt number the dunning session is on. Here is an example of a sessionId value:
  • Eg. 202310232247140434971
• bin (Optional): The first 6 digits of the Payment Account Number or Bank Identification Number linked to the payment method. Here is an example of a BIN value:
  • Eg. 427095
• paymentProvider (Optional): The payment provider or gateway used for the transaction. Here are some examples of paymentProvider values:
  • Eg. NMI
  • Eg. Stripe
  • Eg. Braintree
  • Eg. Authorize.net
• declineCode (Optional): The reason provided by the payment provider for the payment failure.
  The parameter is used to input the decline reason string response from the gateway. Should be populated with the decline reason as a string response. This helps in accurately capturing the reason for payment failure as provided by the payment provider. See string examples below:
  • Do Not Honor
  • Insufficient Funds
  • Issuer Declined
  • 51 - Declined
• amount (Optional): The actual value of the payment being processed. It must be in a valid amount format. Non-numeric values or incorrect formats may result in errors. Here is an example of an amount value:
  • Eg. 199.99
• currency (Optional): The type of currency in which the payment is made. Accepts 3-letter ISO 4217 currency codes only. Incorrect or unsupported codes may lead to errors. Here is an example of a currency value:
  • Eg. USD
  • Eg. CAD
• email (Optional): The email address associated with the payment transaction. Here is an example of an email value:
  • Eg. [email protected]
• phone (Optional): The phone number associated with the payment transaction. Here is an example of a phone value:
  • Eg. 8004559645
  • Eg. [phone]
• paymentProfileId (Optional): This is the unique identifier created by sticky.io when a merchant connects their payment gateway.
  • _Eg. 427
• gatewayTransactionId (Optional): The unique identifier for the failed transaction assigned by the payment gateway.
  • Eg. 123043825154

2nd API Endpoint: Complete Session

• sessionId (Required): Unique identifier (generated by sticky.io) for the client associated with the payment recovery session.
  • Eg. 202310232247140434971
• status (Required): Status of the payment (APPROVED | DECLINED | CANCELED | DEFERRED | RESOLVED).
  • Eg. APPROVED
• bin (Optional): Bank Identification Number, a minimum of 6 digits. This becomes particularly relevant if there's a change in BIN, such as through a credit card update process like CC Updater.
  • Eg. 427095
• paymentProvider (Optional): The payment provider or gateway used. This parameter becomes pertinent if the merchant utilizes payment routing strategies and processes the payment through a different gateway than the one originally used.
  • Eg. Stripe
• amount (Optional): Actual value of the payment being processed. This parameter is particularly relevant if a discount has been applied to facilitate successful payment recovery.
  • Eg. 199.99

🚦 Implementation Steps

Step 1️⃣ Review Documentation

Familiarize with API Specifications: Review the detailed API documentation for both endpoints to understand the parameters, request formats, and expected responses.

• Sticky Recovery GET Endpoint Documentation (1st Endpoint)
• Sticky Recovery POST Endpoint Documentation (1st Endpoint)
• Complete Session POST Endpoint Documentation(2nd Endpoint)

Step 2️⃣ Set Up Authentication

• Obtain API Key: Contact your sticky.io representative to obtain the necessary API key. This key is essential for authenticating and securely accessing the Sticky Recovery API endpoints.
• Configure API Credentials: Ensure your system is set up with the provided API key for secure communication with the endpoints.

Step 3️⃣ Place a Test API call for Dunning Endpoint

• Using the Endpoint URL provided in the API Documentation.
• Add the API-Key to the Header.
• Set the optional parameters
• Send a request and confirm that the service returns date, time, retryStatus, and sessionId.

Step 4️⃣ Implement API Endpoint (Initiate Retry Session)

• Endpoint Integration: Integrate the API endpoint into your system for initiating a retry session following a payment failure.
• Parameter Handling: Handle optional parameters and manage sessionId generation and transmission.
  • Do not pass a sessionId for the first API call.
  • A unique sessionId will be generated and returned by the service when requesting the first retry attempt, so the very first API call for a failed payment must not include sessionId. This sessionId is submitted in subsequent requests for additional retry attempts.
• Response Processing: Code your system to interpret API responses, focusing on retry dates, times, and sessionId.

Step 5️⃣ Schedule Retry Attempts

• Retrieve Retry Information: Upon receiving a retry date/time from the dunning endpoint, extract the retry date/time and sessionId from the dunning endpoint response.
• Save Session ID: Store the sessionId on the subscription or order record to maintain continuity for future payment attempts.
• Schedule Retry Attempts: Utilize automated scheduling mechanisms to initiate payment retries based on the retry date/time provided by the dunning endpoint.
• Retry Payment: On the scheduled retry date/time, trigger (ideally via automated process) the payment attempt using the saved sessionId to ensure recognition by the Sticky Recovery Service.
• Monitor Results: Monitor the outcome of the retry attempt, and if successful call the “Complete Session” endpoint explained in Step 6. If the payment fails again, repeat the retry process as necessary until the dunning endpoint returns HOLD status rather than ACTIVE.

Step 6️⃣ Place a Test API call for the Complete Session Endpoint

• Using the Endpoint URL provided in the API Documentation.
• Add the API-Key to the Header.
• Set the required parameters “status” and ‘’sessionId”
• Set the optional parameters “bin”, “paymentProvider” and “amount”
• Please confirm that the message returned is "Success" and the status is "OK".

Step 7️⃣ Implement Second API Endpoint (Complete Session)

• Develop Endpoint Integration: Create the necessary code to integrate the second API endpoint into the payment processing system, allowing for reporting of payment attempt results at the conclusion of a dunning cycle.
• Define Data Handling Logic: Specify the logic for handling the required parameters, including sessionId and status, along with optional parameters such as BIN, paymentProvider, and amount, ensuring accurate recording and analysis of each payment attempt outcome.
• Understand Statuses: Read FAQ “When should I submit specific statuses such as APPROVED, DECLINED, CANCELED, DEFERRED, or RESOLVED through the "Complete Session" endpoint?”

Final Step 8️⃣ Conduct End-to-End Testing and Review

• Execute End-to-End Test: Implement end-to-end testing procedures to ensure that the integration of both API endpoints follows the documented specifications accurately. This involves simulating payment failure scenarios, triggering retry attempts, and reporting payment attempt results using the complete session endpoint.
• Verify Correct Implementation: Verify that the integration correctly handles parameters and follows the expected workflow for initiating retry sessions and reporting payment attempt results at the end of a dunning cycle.
• Collaborate with sticky.io Team: Coordinate with the sticky.io team to review the integration and validate that it aligns with best practices and platform requirements.

💯 FAQ

Q: Is sticky.io PCI compliant?
A: Yes, sticky.io is PCI compliant. However, it's important to note that for the Sticky Recovery Service, this compliance is not directly impactful since sticky.io does not process payments directly. Our system only requires the Bank Identification Number (BIN) as a parameter, which is not considered sensitive payment card information. Therefore, while we maintain high standards of data security and compliance, the specific operations of the Sticky Recovery Service do not involve handling full payment card details.

Q: How does the Sticky Recovery algorithm determine the optimal retry date and time?
A: The algorithm analyzes historical data, including decline reasons, BINs, currency, payment provider information, and other relevant parameters to predict the best time for a retry, aiming to maximize the probability of successful payment.

Q: Does the Sticky Recovery System process transactions directly?
A: No, sticky.io does not process money directly. Instead, it serves as a recommendation engine for payment recovery. It works in conjunction with your existing payment processing setup to optimize retry attempts for declined transactions.

Q: Do I need to have a specific payment service provider (PSP) to use Sticky Recovery?
A: No, Sticky Recovery is designed to work in tandem with your existing payment processing setup, allowing you to choose any PSP that suits your business needs. Sticky Recovery does not directly integrate with your PSP, providing flexibility to work with any PSP of your choice.

Q: What happens if a payment attempt fails after using the suggested retry date from Sticky Recovery?
A: In the event of a failed payment attempt following the use of a Sticky Recovery suggested retry date, the service returns a 'retryStatus' indicator. If the 'retryStatus' is marked as 'ACTIVE', it implies that the merchant can continue attempting the payment. However, if the 'retryStatus' is set to 'HOLD', it suggests that further attempts should be paused. This status helps merchants make informed decisions about subsequent payment retry attempts based on the guidance provided by the Sticky Recovery system.

Q: Can I override the suggested retry date provided by Sticky Recovery?
A: Yes, while the algorithm provides an optimized date, clients have the discretion to override this suggestion based on their specific needs or insights.

Q: In what time zone is the retry time provided?
A: All retry times are provided in the Eastern Time Zone (ET) which accounts for daylight savings time changes. This means that during daylight savings time, the retry time follows Eastern Daylight Time (EDT, GMT-4), and outside of daylight savings time, it follows Eastern Standard Time (EST, GMT-5). Please ensure to adjust the retry times accordingly if your operations are in a different time zone to align with these changes.

Q: What are the implications of not providing optional parameters like BIN or declineReason?
A: While these parameters are optional, providing them enhances the accuracy of the algorithm. A lack of such data might result in less optimized retry dates.

Q: How does the POST method differ from the GET method in the Sticky Recovery API?
A: Both the GET and POST methods in the Sticky Recovery API serve the same fundamental purpose of retrieving the next retry date for a failed payment. However, the POST method offers enhanced security as the data transmitted is encrypted within the request body, making it a preferable choice for sensitive payment information.

Q: I don't have access to all the parameters listed for the Sticky Recovery service. Will the service still work effectively?
A: All parameters in the Sticky Recovery service are marked as optional to ensure flexibility. However, the more parameters you can provide, the better it is for the accuracy of our predictions. It’s important to note that the BIN and Decline Reason are two critical parameters that greatly influence the effectiveness of the service. Providing these, if possible, can significantly enhance the performance of our algorithm in predicting successful retry times.

Q: What should I do if my subscription management system does not provide BIN and/or Decline Reason data?
A: If your current subscription management system does not readily supply BIN and Decline Reason data, essential for the Sticky Recovery process, there are several steps you can take:

• Engage with Your Payment Gateway: Reach out to your payment gateway or processor. They usually have access to detailed transaction data, including BIN and Decline Reasons, and can provide guidance on how to extract this information.
• Utilize Reporting Tools: Check if there are reporting tools or analytics features within your payment processing system that can be used to gather this data. These tools often have capabilities to customize reports to include specific data points like BIN and Decline Reasons.
• Direct Data Integration: Consider the possibility of directly integrating with your payment systems or databases. This might involve technical development but can be a reliable way to ensure continuous access to necessary data.
• Seek Assistance from sticky.io: If you encounter difficulties in accessing this data, the sticky.io support team is available to assist. They can provide advice on best practices for data retrieval tailored to your system’s capabilities.
  Remember, having accurate BIN and Decline Reason data is crucial for the effective operation of the Sticky Recovery system, so it's important to establish a reliable method to access this information.

Q: What should we do with approved transactions in the Sticky Recovery process?
A: Do not send payment data for approved transactions to the Sticky Recovery system. Currently, the first API endpoint is specifically designed to handle only failed transaction data for retrying. Our team is actively working on a second API endpoint that will be dedicated to gathering approval information. Until this second endpoint is available, sending approved payment data can lead to processing errors and inaccurate dunning activities.

Q: What is a sessionId and why is it important in the Sticky Recovery process?
A: A sessionId is a unique identifier generated by the service and assigned to each payment transaction or session within the Sticky Recovery system. It plays a crucial role in tracking and managing payment retries. By using a sessionId, the system can maintain a continuous record of transaction attempts and outcomes, which is essential for effective payment recovery and analysis. When a sessionId is provided with a transaction, it enables the system to link that transaction to previous attempts, thereby creating a cohesive history that enhances our machine learning algorithm's ability to predict optimal retry dates. If a sessionId is not provided, the system will generate a new one, but this might impact the continuity of data and reduce the effectiveness of the retry strategy.

Q: Is it necessary to provide a sessionId for each transaction? What happens if I don't?
A: Providing a sessionId is optional but highly recommended. Using a sessionId enhances tracking and operational efficiency. If a sessionId is not provided, the system will automatically generate a new one. However, not using a consistent sessionId might limit the continuity and accuracy of data tracking. By effectively managing sessionIds, you can ensure a smoother integration and a more comprehensive understanding of payment transactions over time.

Q: What happens if I pass a sessionId in the API call that was not generated by sticky.io?
A: When a sessionId that was not generated by sticky.io is passed in an API call, the system will not recognize or utilize this external sessionId. Instead, sticky.io will automatically ignore the provided sessionId and generate a new one for the session. This new sessionId will be used for subsequent operations and tracking within the Sticky Recovery process to ensure consistent and reliable management of the transaction retry process.

Q: What happens if the same sessionId is used again on the same day?
A: When a sessionId is reused on the same day, sticky.io's system is designed to return the same result as the initial query without recalculating or counting it as a new decline attempt. This approach is taken to avoid redundant processing and ensure efficient use of system resources. However, it's important to note that this means real-time updates or changes in circumstances within the same day may not be immediately reflected in the system's response. This design decision strikes a balance between processing efficiency and data accuracy within a given day.

Q: What is the purpose of the "Complete Session" API endpoint in the Sticky Recovery system?
A: The "Complete Session" endpoint is designed to report the outcomes of payment attempts at the end of a dunning cycle. This feedback is vital for refining our machine-learning models, making the predictions from the first endpoint more accurate over time.

Q: How does reporting successful payments via the "Complete Session" endpoint benefit my business?
A: By reporting successful payment attempts, you contribute to a feedback loop that enhances the algorithm's precision in predicting optimal retry dates. This leads to a more effective dunning strategy, potentially increasing your overall payment recovery rates.

Q: How does the "Complete Session" endpoint improve the machine learning model of Sticky Recovery?
A: By receiving data on successful payment attempts, the machine-learning model can better understand patterns and factors leading to successful transactions, thereby continuously improving the accuracy of future retry predictions.

Q: Can I use the "Complete Session" endpoint to report declined transactions as well?
A: The primary intent of the "Complete Session" endpoint is to report the final outcome of the dunning cycle. This includes informing us when a transaction is successfully recovered or when the retry process is concluded based on a 'HOLD' status from the first API endpoint, or if you decide to cease recovery attempts for any reason. The endpoint helps us understand the end results of the dunning process, whether successful or not.

Q: When should I submit specific statuses such as APPROVED, DECLINED, CANCELED, DEFERRED, or RESOLVED through the "Complete Session" endpoint?
A: Accurately reporting the status of each payment attempt is vital for the efficacy of the dunning process. In general, you should submit session IDs to the 2nd API endpoint whenever you're not engaging the 1st endpoint for a new retry date. This practice ensures that every stage of the dunning cycle is accurately captured and analyzed. Here are specific scenarios for status submissions:

• APPROVED: Mark a session as APPROVED when:
  • A previously declined payment is successfully processed, indicating the dunning cycle's successful conclusion due to the recovery of the owed amount.
• DECLINED: Use DECLINED if:
  • The 1st API endpoint may return a 'HOLD' status. A payment has undergone the maximum attempt number (defined during onboarding) as our retry cap dictates. Further attempts are discouraged to protect MID health.
  • The Gateway might issue a "No Retry Advised" message, like "Do Not Retry," indicating that no additional automatic retry attempts should be made by the system.
• CANCELED: Submit a session as CANCELED when:
  • Either the merchant or the customer decides to terminate the membership or service, signaling that no further payment attempts should be pursued, regardless of the dunning cycle's stage.
• DEFERRED: Submit a session as DEFERRED when:
  • Subscription has been temporarily paused, or when a subscriber chooses to skip a payment cycle.
  • This status indicates that the subscription remains active, but the dunning cycle has been suspended without a transaction occurring. No payment is processed during this period, but the subscription is maintained to be reactivated or continued at a later stage, according to the subscriber's or merchant's decision. The transaction has not occurred.
• RESOLVED: Submit a session as RESOLVED when:
  • Previously outstanding payment issue have been successfully addressed and rectified through alternative means or manual intervention external to the standard dunning process.
  • This could involve the merchant securing payment via updated card information or other recovery methods outside of the Sticky Recovery. The transaction has been successfully completed, ensuring the continuity of the subscription or service. The Transaction has occurred

🕹️Sequence Diagram

Dunning Cycle Completed - Revenue Recovered

Dunning Cycle Completed - Revenue Loss (Churn)

📞 Contact and Support

For further assistance, please email us at [email protected] or call 800-455-9645 ext 1.

📊 Release History

Version	Date	Changes
v1	9-27-2023	Initial Release with GET method. Primary focus on using BIN (Bank Identification Number) for Sticky Recovery predictions.
v2	11-1-2023	NEW MODEL: Enhanced algorithm to incorporate both BIN and Decline Reason for more accurate dunning predictions.
v2.1	11-1-2023	Introduction of the POST method, allowing for more robust data submission and processing.
v2.2	12-18-2023	Introduction of the Complete Session Endpoint. It allows for more comprehensive tracking and reporting of the final outcomes in the payment recovery cycle, further optimizing our dunning process.
v2.3	3-13-2024	Bug Fix: Fixed maximum retry attempts threshold issue.
v3	4-3-2024	NEW MODEL: Improving the categorization of reasons for payment failures to enhance the accuracy of dunning predictions.
v3.1	4-23-2024	Complete Session Enhancements. New values were added for the Status field (DEFERRED & RESOLVED).
v4	10-15-2024	Introduction of Dunning Profiles. Dunning profiles enable merchants to implement various dunning strategies and allocate portions of their declined traffic to different profiles. This functionality will also facilitate A/B testing.