📝 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 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 : Includes basic customer identifiers such as customer ID, name, email, and phone number to support optimized retries and satisfy gateway requirements.
Billing Address: 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, BIN, decline response data, and related processing information.

Gateway Specific Fields

Rocket Gate:
- customer.customerId (Required): Required by the gateway when submitting a payment with the gateway token.
- mitReferenceTransactionId (Recommended): This optional but highly recommended identifier links the current transaction to a previous successful charge. It helps improve authorization rates for merchant-initiated transactions.

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)

Webhooks let you receive real-time updates on the progress and outcome of Sticky Recovery sessions. This enables immediate downstream actions, such as internal logging, customer notifications, or dashboard updates, without needing to poll the API.

Configuring Webhook Endpoints

To start receiving webhooks:

1️⃣ Go to Developer > Webhooks in the Sticky Recovery UI.

2️⃣ Add the URL(s) where you want events to be sent.

3️⃣ Select one or more of the following supported event types.

Supported Webhook Events

Webhook Event	Description
`recovery_started`	Triggered when a recovery session is created.
`recovery_attempt_failed`	Fired when a retry attempt fails.
`recovery_successful`	Fired when a retry attempt results in a successful payment.
`recovery_unsuccessful`	Sent when the recovery session ends without success (max retries or cancel).

Decrypted JSON Encoded Payload

recovery_started

{
  "clientAppKey": "7bebb0d5-ea45-44aa-9122-fb522eb12314",
  "type": "recovery.started",
  "time": "2025-05-23T19:48:17.097Z",
  "data": {
    "stickyTransactionId": "249fa7da9125b036011e97d24719586f7442d97405125801f9",
    "gatewayProfileId": "1568",
    "dunningProfileId": "297",
    "dunningSessionId": "2025060518423881610"
  }
}

recovery_attempt_failed

{
  "clientAppKey": "7bebb0d5-ea45-44aa-9122-fb522eb12314",
  "type": "recovery.attempt_failed",
  "time": "2025-05-23T19:48:17.097Z",
  "data": {
    "stickyTransactionId": "054440bf260fd6a205f20b83dea7e16401d440f70d844d9399",
    "gatewayTransactionId": "100019740BA5CBB", 
    "amount": 50000,
    "currency": "USD",
    "gatewayProfileName": "RocketGate",
    "gatewayProfile": "RocketGate",
    "gatewayProfileId": "12345",
    "dunningProfileId": "297",
    "dunningSessionId": "2025060518423881610",
    "attemptNumber": 1,
    "gatewayResponse": {
     //GATEWAY RESPONSE HERE
    }
  }
}

recovery_successful

{
  "clientAppKey": "7bebb0d5-ea45-44aa-9122-fb522eb12314",
  "type": "recovery.successful",
  "time": "2025-05-23T19:48:17.097Z",
  "data": {
    "stickyTransactionId": "054440bf260fd6a205f20b83dea7e16401d440f70d844d9399",
    "gatewayTransactionId": "100019740BA5CBB",
    "dunningSessionId": "2025060518423881610",
    "dunningProfileId": "297",
    "amount": 50000,
    "currency": "USD",
    "gatewayProfileName": "RocketGate",
    "gatewayProfile": "RocketGate",
    "gatewayProfileId": "12345",
    "gatewayResponse": { 
		    //GATEWAY RESPONSE HERE
    }
  }
}

recovery_unsuccessful

{
  "clientAppKey": "7bebb0d5-ea45-44aa-9122-fb522eb12314",
  "type": "recovery.unsuccessful",
  "time": "2025-05-23T19:48:17.097Z",
   "data": {
    "stickyTransactionId": "054440bf260fd6a205f20b83dea7e16401d440f70d844d9399",
    "dunningSessionId": "2025060518423881610",
  }
}

Webhook Retries

Sticky automatically retries webhook delivery if your endpoint:

Times out
Returns an HTTP status between 500 and 503
- 500 - Internal Server Error: A generic error from the server when no specific message is available. Usually indicates an unexpected failure.
- 501 - Not Implemented: The server doesn't support the functionality required to fulfill the request. Rare in webhook contexts.
- 502 - Bad Gateway: The server (often a reverse proxy or gateway) received an invalid response from an upstream server.
- 503 - Service Unavailable: The server is temporarily unable to handle the request. Often due to overload or maintenance.

Retry Policy:

5 attempts total per failed delivery.
Interval: Every 6 hours, controlled via cron (runs 4 times daily).

🧪 Testing

To validate your Sticky Recovery integration end-to-end:

Connect a Gateway Profile

Ensure at least one payment gateway is configured and active under your Sticky account.

Submit a Simulated Declined Transaction

Call the recover endpoint using test data that mimics a failed transaction.

Verify API Response

Confirm the response includes a valid stickyTransactionId, which indicates a recovery session was successfully created.

Confirm Recovery Activity

Use the Recovery Activity UI to validate that the session appears and that retry attempts are being scheduled.

Monitor Webhook Events (Optional)

If webhooks are configured, validate that your endpoint is receiving event notifications like recovery_started and recovery_successful.

Cancel the Recovery Session

Use the Cancel Recovery endpoint to terminate the recovery session:

Call the endpoint using the stickyTransactionId from the previous step.
Confirm that the session status updates to "Unrecovered" in the Recovery Activity dashboard.
(If applicable) Check that the recovery_unsuccessful webhook fires as expected.

Sticky Recovery (Recover Endpoint)