Integration Guide

📓 Summary

The Recover endpoint enables fully managed payment recovery by allowing you to submit failed transactions directly to sticky.io. Once submitted, sticky.io takes full control of the retry process, automatically scheduling and executing payment retries through your connected gateway profiles based on your configured dunning strategy. This guide provides the technical requirements and step-by-step instructions to help you integrate the Recover API. With no need to build or maintain retry logic, merchants can rely on real-time webhook notifications to monitor recovery attempts and outcomes.

⚙️ 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

Required Parameters

• paymentProfileId
• initiatedBy
  • Tells Sticky the transaction is Merchant Initiated and links to the prior customer authorization (required for network compliance).
• isRecurring
  • Confirms to Sticky that this is part of a recurring billing cycle, so the platform will correctly classify it as a rebill transaction and apply the appropriate dunning (retry) strategy.

🚧

Critical Required Fields for Recurring Transactions

For any rebill, subscription renewal, or recurring payment recovery, you must include the following fields without exception:

✅ initiatedBy: "MIT"
✅ isRecurring: true

• paymentMethod
• originalTransaction
  • id
  • amount (To override, use paymentMethod.amount)
    • e.g., 1000 for $10.00
  • currency (To override, use paymentMethod.currency)
    • e.g, USD for US Dollars.
  • declineReason (see examples below)
    • Do Not Honor
    • Insufficient Funds
    • Issuer Declined
    • 51 - Declined

Not Required but Highly Recommended Parameters

• originalTransaction
  • bin
  • networkAdviceCode
• mitReferenceTransactionId

Gateway Specific Fields

Rocket Gate:

• customer.customerId (Required): Required by the gateway when submitting a payment with the gateway token.
  • Rocket Gate: MERCHANT_CUSTOMER_ID
• paymentMethod.token.id (Required)
  • Rocket Gate: CARD_HASH
• customer.firstName
• customer.lastName
• customer.email
• billingAddress.address1
• billingAddress.city
• billingAddress.zip
• billingAddress.state
• billingAddress.country

🚧

Supported Country Format

⚠️When providing the billing country, supply the country code in ISO 3166-1 alpha-2 format (e.g., "US", "CA", "GB"). RocketGate strictly enforces this format and will reject requests that pass full country names (e.g., "United States", "Canada"). Rocket Gate Documentation

✅ Correct example: "billingAddress.country": "US"

❌ Incorrect example:"billingAddress.country": "United States"

• externalId
  • Rocket Gate: MERCHANT_INVOICE_ID
• mitReferenceTransactionId
  • Rocket Gate: REFERENCE_SCHEME_TRANSACTION_ID
• mitReferenceSettlementDate (Conditionally Required)
  • Rocket Gate: REFERENCE_SCHEME_SETTLEMENT_DATE
  • This field is required when mitReferenceTransactionId is provided, and the transaction involves a MasterCard.

Authorize.Net:

• customer.Id (Required)
  • Authorize.Net: customerProfileId
• paymentMethod.token.id (Required)
  • Authorize.Net: paymentProfile.paymentProfileId
• mitReferenceTransactionId
  • Authorize.Net: subsequentAuthInformation.originalNetworkTransId

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).

📘

Webhook Payloads, Encryption & Decryption

For more technical details, click here.

🔒 Duplicate Prevention Logic

When a failed transaction is submitted to the Recover API, Sticky checks for an existing recovery session using the gatewayTransactionId. Based on what we find, we take the following actions:

Condition Found	Action Taken
A recovery session is active for this gateway transaction ID (originalTransaction.Id)	❌ Reject the request. Active recovery is already in progress.
A recovery session was successful (status = recovered) for this gateway transaction ID (originalTransaction.Id)	❌ Reject the request transaction already recovered.
A recovery session was unsuccessful (status = unrecovered) for this gateway transaction ID (originalTransaction.Id)	✅ Accept the request, allowing a fresh recovery attempt.
No previous session found for this gateway transaction ID (originalTransaction.Id)	✅ Accept the request, create a new recovery session.

This logic ensures we don’t retry the same decline multiple times unless a prior session was closed without success.

Please refer to the duplicate prevention diagram for more details.

🧪 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.

👁️‍🗨️ Transaction Query APIs

Sticky Recovery supports read-only GET APIs for querying transaction data. These endpoints allow merchants to retrieve payment activity for reporting, analytics, operational monitoring, and payment reconciliation. These endpoints are read-only and do not modify any recovery sessions or trigger retries.

Below are the supported GET APIs for retrieving transactions. You can find sample payloads at the following link.

Get Gateway Transaction (API)

• Retrieve the details of a specific gateway-level transaction attempt.
• Useful for support teams reviewing specific declines, approvals, or chargebacks.

Get Transaction History (API)

• Fetch the full history of a Sticky Recovery transaction, including retries, refunds, and final statuses.
• The stickyTransactionId is returned in responses when submitting to the Recover API.

Get List of Transactions (API)

• Retrieve a paginated list of transactions for reporting and analytics.

🕹️ Diagrams

Sequence

Dupe Prevention