Bulk Recovery

📓 Summary

This page provides an end-to-end guide for integrating with Sticky.io's Bulk Recovery APIs. Bulk endpoints allow merchants to submit multiple transactions in a single API request, optimizing throughput and reducing integration complexity.

🔍Overview

Sticky.io’s Bulk Recovery APIs extend the functionality of the standard single-transaction endpoints by enabling bulk operations. These endpoints support up to 1000 transactions per request, ensuring high efficiency for platforms that process large volumes of declines.

📦 Available Bulk Endpoints

Name	Endpoint	Method	Description
Bulk Recovery		POST	Submits multiple failed transactions for recovery.
Bulk Cancel		POST	Cancels multiple recovery sessions.
Bulk Refund		POST	Issues refunds for multiple recovered transactions.

✅ 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.
• Dunning Profile Configured: At least one dunning profile must be set up to define a retry strategy for failed payments.
• Webhook URLs Configured (Optional but Recommended): To receive updates throughout the recovery lifecycle, configure webhook endpoints via Developer > Webhooks in the UI.

🚦Bulk Recovery API

Request Field Description

Element	Type	Required	Description
id	String	Yes	Gateway transaction ID of the original declined transaction used for payment recovery.
externalId	String		An optional merchant-defined reference ID used to identify the transaction externally.
initiatedBy	String	Yes	Indicates who initiated the transaction. Use CIT for customer-initiated and MIT for merchant-initiated transactions.
isRecurring	Boolean	Yes	Boolean indicating whether the transaction is part of a recurring billing cycle.
dunningProfileId	String		Identifier for the dunning (retry) strategy applied during payment recovery.
recoveryTransactionAmount	Integer		Overrides the original failed transaction amount, in the smallest currency unit (e.g., 1000 for $10.00).
recoveryTransactionCurrency	String		Overrides the currency of the original failed transaction. Must use ISO 4217 format (e.g., USD).
amount	Integer	Yes	Declined transaction amount in the smallest currency unit (e.g., 1000 for $10.00).
currency	String	Yes	Currency of the declined transaction, represented in ISO 4217 format (e.g., USD).
declineReason	String	Yes	Code or reason provided by the payment provider indicating the failure (e.g., "Do Not Honor", "Insufficient Funds").
bin	String		Bank Identification Number (BIN) linked to the payment method; minimum 6 digits.
responseCode	String		Gateway response code explaining the decline reason.
avsResultCode	String		Address Verification System (AVS) result for the declined transaction.
cvvResultCode	String		Card Verification Value (CVV) result for the declined transaction.
cavvResultCode	String		Cardholder Authentication Verification Value (CAVV) result for 3DS-secured transactions.
processorName	String		Name of the payment processor that handled the declined transaction (e.g., NMI, Stripe).
processorDeclineCode	String		Numeric ISO 8583 decline code returned by the payment processor (e.g., 51 = Insufficient Funds, 05 = Do Not Honor).
networkAdviceCode	String		Issuer-provided code advising whether a declined transaction should be retried, delayed, or avoided (used by Mastercard).
timeStampUTC	String		Timestamp of the original declined transaction in UTC.
mitReferenceTransactionId	String		Identifier linking the recovery attempt to a prior successful charge (used for MIT authorization improvements).
mitReferenceSettlementDate	String		Settlement date of the referenced transaction, required if mitReferenceTransactionId is provided.
lastSuccessfulBillingDate	String		Date of the last successful recurring transaction for this customer.
previousBillingCount	Integer		Number of previous successful billings for this subscription or customer.
billingFrequency	String		Frequency of recurring billing (e.g., Weekly, Monthly, Annually).
customer.customerId	String		Unique identifier for the customer in the merchant or gateway system.
customer.firstName	String		Customer’s first name.
customer.lastName	String		Customer’s last name.
customer.email	String		Customer’s email address.
customer.phone	String		Customer’s phone number.
gateway.paymentProfileId	String		Required. Identifier for the payment gateway profile to be used for recovery attempts.
gateway.isDefault	Boolean		Indicates if this gateway profile is set as the default.
paymentMethod.isDefault	Boolean		Marks this payment method as the customer’s default option in the vault.
paymentMethod.billingAddress1	String		Primary address line, including street and building number.
paymentMethod.billingAddress2	String		Additional address details, such as apartment or suite number.
paymentMethod.billingCity	String		City for the billing address.
paymentMethod.billingState	String		State or province for the billing address.
paymentMethod.billingZip	String		Postal or ZIP code for the billing address.
paymentMethod.billingCountry	String		Country for the billing address (ISO 3166-1 alpha-2 code).
paymentMethod.token.type	String	Conditionally Required**	Specifies the type of tokenization used (e.g., CARD, GATEWAY, STICKY, APPLE, GOOGLE).
paymentMethod.token.id	String	Conditionally Required**	Unique identifier for the tokenized payment method.
paymentMethod.token.id	String		Token ID used to charge the card.
paymentMethod.card.cardHolderName	String	Conditionally Required**	Name of the cardholder as it appears on the card.
paymentMethod.card.cardNumber	String	Conditionally Required**	Full card number (PAN) to be used for the recovery attempt.
paymentMethod.card.cvv	String		Card Verification Value is used for authentication.
paymentMethod.card.expMonth	String	Conditionally Required**	Expiration month of the card (MM format).
paymentMethod.card.expYear	String	Conditionally Required**	Expiration year of the card (YYYY format).

Bulk Request Format

JSON

{
  "transactions": [
    {
      "id": "trans_001",
      "externalId": "order_001",
      "initiatedBy": "MIT",
      "isRecurring": true,
      "dunningProfileId": "101",
      "recoveryTransactionAmount": 4200,
      "recoveryTransactionCurrency": "USD",
      "amount": 4200,
      "currency": "USD",
      "declineReason": "Do Not Honor",
      "bin": "411111",
      "responseCode": "05",
      "avsResultCode": "N",
      "cvvResultCode": "N",
      "cavvResultCode": "",
      "processorName": "NMI",
      "processorDeclineCode": "",
      "networkAdviceCode": "04",
      "timeStampUTC": "2025-09-20T14:25:10Z",
      "mitReferenceTransactionId": "abc123",
      "mitReferenceSettlementDate": "2025-09-10",
      "lastSuccessfulBillingDate": "2025-08-10",
      "previousBillingCount": 3,
      "billingFrequency": "Monthly",
      "customer": {
        "customerId": "cust_001",
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "[email protected]",
        "phone": "5551234567"
      },
      "gateway": {
        "paymentProfileId": "profile_123",
        "isDefault": true
      },
      "paymentMethod": {
        "isDefault": true,
        "billingAddress1": "123 Main St",
        "billingAddress2": "Apt 4",
        "billingCity": "Los Angeles",
        "billingState": "CA",
        "billingZip": "90210",
        "billingCountry": "US",
        "token": {
          "type": "GATEWAY",
          "id": "toknen_XXXX"
        }
      }
    },
    {
      "id": "trans_02",
      "externalId": "order_002",
      "initiatedBy": "MIT",
      "isRecurring": true,
      "dunningProfileId": "101",
      "recoveryTransactionAmount": 100,
      "recoveryTransactionCurrency": "USD",
      "amount": 100,
      "currency": "USD",
      "declineReason": "Insufficent Funds",
      "bin": "411111",
      "responseCode": "05",
      "avsResultCode": "N",
      "cvvResultCode": "N",
      "cavvResultCode": "",
      "processorName": "NMI",
      "processorDeclineCode": "",
      "networkAdviceCode": "04",
      "timeStampUTC": "2025-09-20T14:25:10Z",
      "mitReferenceTransactionId": "abc123",
      "mitReferenceSettlementDate": "2025-09-10",
      "lastSuccessfulBillingDate": "2025-08-10",
      "previousBillingCount": 3,
      "billingFrequency": "Monthly",
      "customer": {
        "customerId": "cust_002",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "phone": "5551234567"
      },
      "gateway": {
        "paymentProfileId": "profile_123",
        "isDefault": true
      },
      "paymentMethod": {
        "isDefault": true,
        "billingAddress1": "123 Main St",
        "billingAddress2": "Apt 4",
        "billingCity": "Los Angeles",
        "billingState": "CA",
        "billingZip": "90210",
        "billingCountry": "US",
        "token": {
          "type": "GATEWAY",
          "id": "toknen_XXXX"
        }
      }
    }
  ]
}

❌ Bulk Cancel API

Use the Bulk Cancel Recovery endpoint to stop up to 1000 recovery sessions in a single request. This is functionally identical to the single cancel endpoint (Cancel Recovery) but is designed for bulk operations.

If you need to halt recovery attempts for an active session, such as when a customer updates their payment method or cancels their subscription, submit a list of stickyTransactionId values along with a desired status (CANCELED, DEFERRED, or RESOLVED).

Request Field Description

Element	Type	Required	Description
stickyTransactionId		Yes	Unique identifier assigned to the recovery transaction session. Required when canceling an active recovery session.
status		Yes	The status of the transactions, valid options are CANCELED, DEFERRED, and RESOLVED.

Bulk Request Format

JSON

{
  "transactions": [
    {
      "stickyTransactionId": "STICKY_TXN_123456",
      "status": "CANCELED",
    },
    {
      "stickyTransactionId": "STICKY_TXN_654321",
      "status": "RESOLVED",
    }
  ]
}

💸Bulk Refund API

Use the Bulk Refund endpoint to issue refunds for up to 1000 recovered transactions in a single request. This endpoint is functionally identical to the single refund endpoint (Refund) but supports bulk operations.

To process refunds in bulk, submit a list of stickyTransactionId values, each with a refund amount and an optional refundReason.

Request Field Description

Element	Type	Required	Description
stickyTransactionId		Yes	Unique identifier assigned to the recovery transaction session. Required when performing a refund.
amount		Yes	The amount that is going to be captured. Amount should be the same or lower than the one captured previously.
authorizationId		Conditionally Required	Unique identifier for the transaction authorization.
refundReason			Reason for processing the refund.
refundDescription			Additional details about the refund reason.

Bulk Request Format

JSON

{
  "transactions": [
    {
      "stickyTransactionId": "STICKY_TXN_654321",
      "amount": 1000,
      "authorizationId": "AUTH_ABC123",
      "refundReason": "Product defective",
      "refundDescription": "Customer returned product within 7 days"
    },
    {
      "stickyTransactionId": "STICKY_TXN_765432",
      "amount": 5000,
      "authorizationId": "AUTH_DEF456",
      "refundReason": "Partial refund after price dispute",
      "refundDescription": "Adjusted based on coupon pricing"
    }
  ]
}

📡 Bulk Request Summary Webhook

A webhook is triggered after a bulk request (Recovery, Cancel, or Refund) is fully processed. This webhook provides a summary of the submission results, showing how many records were accepted and how many were rejected. Processing may take a few minutes, depending on load and validation.

This webhook does not return per-transaction details. To access full results, including errors, use the Bulk Request Details API

JSON

{
  "clientAppKey": "7bebb0d5-ea45-44aa-9122-fb522eb12314",
  "type": "bulk.submission.status",
  "time": "2025-08-27T14:42:00Z",
  "data": {
    "requestId": "Request_00123",
    "requestType": "REFUND",
    "totalSubmitted": 1000,
    "totalAccepted": 950,
    "totalRejected": 50
  }
}

ℹ️ For retries, encryption, and other technical details, refer to the Webhooks page. This central page covers all system webhooks, including headers, retry behavior, signing secrets, and example error handling strategies.

📄 GET Bulk Request Details

📘 API Reference: Bulk Request Details

Use this API to retrieve the full outcome of any bulk submission. This includes both accepted and rejected transactions, along with their stickyTransactionId, gatewayTransactionId, and rejection reasons (if applicable).

This endpoint is typically used after receiving the Bulk Submission Webhook, using the provided requestId.