📝 Introduction

Welcome to the integration guide for the Recover API Endpoint, part of sticky.io’s payment recovery suite. This endpoint allows you to fully automate the process of retrying failed transactions. Built on the same machine learning engine behind the Smart Dunning service, the Recover endpoint is a fully managed solution: you submit the failed payment, and we take care of the rest.

📓 Summary

The Recover endpoint simplifies payment recovery by automatically resubmitting declined transactions to your connected gateway profiles. This guide provides the technical requirements and step-by-step instructions to help you integrate the Recover API, ensuring seamless recovery of failed payments with no need to build retry logic on your end. You’ll also learn how to configure webhook notifications to stay informed of recovery attempts and outcomes in real time.

⚙️ How It Works

You submit a failed transaction via the Recover API.
sticky.io manages the retry attempts based on the dunning profile.
All retry attempts are executed using your connected payment gateway.
You receive webhook updates for every failed retry and final outcome.
No scheduling or logic required — it's set-it-and-forget-it.

✅ Prerequisites

Before integrating the Recover endpoint, ensure the following:

Obtain an API Key: Your API key will be provided by sticky.io during onboarding. This key is required to authenticate all requests to the Recover API. The key can also be found under the developer section.
Gateway Profile Connected: At least one payment gateway must be connected through the Sticky.io platform.
Failed Transaction Data: You must submit relevant data from the original failed transaction (e.g., amount, currency, decline reason, gateway transaction ID).
- (Optional but recommended) Include the Decline Reason and BIN to improve the recovery strategy.
Webhook URLs Configured (Optional but Recommended): To receive updates throughout the recovery lifecycle, configure webhook endpoints via Developer > Webhooks in the UI.

📬 Submitting a Recovery Request

📘 API Reference: Recover Endpoint

When calling the Recover API, you’ll submit key data grouped into five main sections. Individual field details will be available in the full API documentation — this guide focuses on summarizing the payload structure at a high level:

Transaction Metadata: Includes essential details about the recovery attempt, such as the payment profile, initiation type (CIT/MIT), recurring status, source, dunning profile, and a merchant-defined external identifier (externalId).
Customer Information (Conditionally Required, e.g., RocketGate): Includes basic customer identifiers such as customer ID, name, email, and phone number to support optimized retries and satisfy gateway requirements.
Billing Address (Optional): Provides billing location details such as address, city, state, country, and postal code, which can help improve recovery approval rates during retry attempts.
Payment Method: Supports two flows: submitting full card details (card number, expiration, CVV) or submitting a tokenized payment method (token ID and type). You may also optionally override the transaction amount and currency for the recovery attempt.
Original Transaction Details: Links the recovery session to the original failed transaction, including gateway transaction ID, timestamps, amount, currency, decline response data, and related processing information.

🔄 When Should You Call the Recover Endpoint?

Merchants should call the Recover API as soon as a payment is declined to maximize the chances of recovery. The goal is to get failed transactions into the recovery system promptly so retries can begin without delay.

This can be triggered in a variety of ways, depending on your tech stack and data flow — for example:

When receiving a decline webhook from your payment gateway
When a recurring billing engine flags a failed renewal attempt
From within your internal payment orchestration logic
Any time a failed transaction is detected in real time

💡 Best Practice:
The faster you trigger the Recover API after a decline, the higher the probability of a successful retry. Submitting failed payments promptly enables the recovery engine to take over without requiring manual scheduling or delay.

❌ Canceling a Recovery Session

📘 API Reference: Cancel Recovery Endpoint

In some cases, merchants may want to halt an active recovery session — for example, if a customer updates their payment method externally or cancels their subscription.
The Cancel Recovery endpoint allows merchants to immediately stop a recovery cycle.

Key Requirements:

Submit the stickyTransactionId associated with the active recovery session.
Choose the appropriate cancellation reason.
- CANCELED: The merchant or customer ends the service, stopping all future payment attempts, regardless of the dunning stage.
- DEFERRED: Subscription has been temporarily paused, or when a subscriber chooses to skip a payment cycle.
- RESOLVED: Previously outstanding payment issue have been successfully addressed and rectified through alternative means or manual intervention external to the standard dunning process.
Once canceled, no further retry attempts will be scheduled.

📡 Webhooks (Optional)

Subscribe to webhook events to monitor the recovery process. These can be configured via the **Developer > Webhooks screen in the Sticky Recovery dashboard.

Webhook Event	Triggered when
recovery_started	The recovery session is created after the API submission.
recovery_attempt_failed	A retry attempt fails.
recovery_successful	A retry attempt succeeds, and payment is recovered.
recovery_unsuccessful	Session ends without recovery (declines or cancellations).

🧪 Testing

To test the integration:

Connect a gateway profile.
Submit a failed transaction to the recover endpoint.
Confirm that stikcyTransactionID is returned.
Validate that a recovery session is created via the Recovery Activity.

Sticky Recovery (Recover Endpoint)