Skip to main content
Version: v2

Retry Strategies

Overview​

Split tender transactions divide a single purchase across multiple payment methods. This document outlines the robust retry strategies and recovery mechanisms Convenient Checkout Gateway (CCG) employs to maximize success and minimize cost when part of a split tender transaction fails.

Key Benefits of Retry Strategy
  • Higher Success Rate: Systematic retry approach leads to improved overall transaction success rate
  • Better Customer Experience: Automatic handling of transient failures reduces customer friction
  • Comprehensive Rollback: If one payment fails, all successful payments are properly reversed
  • Transparent Notifications: Merchants receive detailed information about failures and rollbacks

Retry Mechanism​

Business Rules

  • Pre-Condition: Merchant is allowed to retry only when parent transaction is marked as FAILED status and Retry Attempts are available.

  • Maximum Retry Attempts: Total of 5 attempts allowed across the entire transaction lifecycle.

  • Payment Finality Rule: If any one of the payments reaches a final state that is not COMPLETED (either FAILED or CANCELLED), the other payment will be automatically rolled back and the attempt will be marked as failed.

    Roll Back Transaction
    • If any payment method fails, the entire transaction under split tender will be rolled back to allow customer to pick a different set of payment methods. Refer RollBack Strategies for more details.
    • Asynchronous Rollback Process:
      • Refunds initiated as part of rollback for split tender transactions are handled asynchronously by the system. The merchant will be notified of rollbacks and can initiate retries as needed.
      • Cancellations are real-time and communicated as part of transaction.

  • Merchant Notification: Merchants will be notified with detailed rollback information when a transaction fails, including which payments were affected and the reason for failure.

  • All Retries Exhausted: If the payment cannot be moved to COMPLETED or FAILED within the maximum retry limit, the transaction will be canceled to maintain transaction integrity.

  • Single Payment Fallback: If transaction fails on split tender, customer or merchant will be allowed to submit payment with a single payment method.

  • All-or-Nothing Retry: Selective retry of only the failed payment is not supported. If any payment in a split tender transaction fails, the entire transaction must be retried from the beginning with a new set of payment methods if desired.

    • This approach allows the customer to select different payment methods and reallocate the payment amounts as needed for the retry attempt, providing flexibility in resolving the failed transaction.
    Example: All-or-Nothing Retry with Different Payment Methods and Amounts

    • Suppose a customer splits a $100 purchase between two cards:

      • Card A: $60
      • Card B: $40

    • If Card B fails (e.g., insufficient funds), the entire transaction is rolled back. On retry, the customer can:

      • Choose Card A: $50
      • Choose Card C: $50
    This flexibility allows the customer to adjust both the payment methods and the allocation of amounts to maximize the chance of success on the next attempt.
Retry Attempt Tracking
Retry Attempt Counter

Each time a transaction fails and is retried with the same merchantTransactionId, the system increments the attempt counter:

  1. Initial transaction attempt (count: 1)
  2. First retry after failure (count: 2)
  3. Second retry after failure (count: 3)
  4. Third retry after failure (count: 4)
  5. Fourth and final retry (count: 5)

If the fifth attempt fails, no further retries will be permitted for that transaction ID.

Retry Flow for Split Tender Failures​

Retry Flow Diagram

Merchant Transaction Id Idempotency Handling​

  • Idempotency Keys: Always use the same merchantTransactionId when retrying a failed transaction. This ensures that retries are recognized as part of the same transaction and prevents duplicate processing.

  • If the same Merchant Transaction ID is submitted again:

    • ⚠️ If the original payment is in a non-failed status, the new request will be rejected to prevent duplicate processing.
      • ⛔ If the original payment is in a failed status and retry attempts are exhausted, the request will be forbidden.
      • 🚧 If the original payment is in a failed status and retry attempts are not exhausted, only the following parameters are allowed to be overridden:
        • Amount at individual payment level
        • Payment Method
Preserved Parameters
Fields that cannot be overridden during retries

The following fields will not be overridden when merchant retries with the same merchant transaction id:

  • statementDescriptorSuffix
  • description
  • paymentType
  • partialAuthorization
  • authorizeFlag
  • payment metadata
  • parent amount

Retry Best Practices for Merchants​

Integration Recommendations
  • Error Handling: Always check the transaction status and error codes before retrying
  • Progressive Backoff: Implement increasing delays between retry attempts (e.g., 1s, 2s, 4s)
  • Timeout Management: Set appropriate timeouts for payment operations (recommended: 30s)
  • Fallback Strategies: Consider offering single-payment fallback option when split tender fails

Transient Failures Retry Mechanisms​

Retry for Stripe Calls​

When any API call to Stripe fails, CCG automatically attempts to recover through systematic retries:

Retry Configuration for Stripe Timeouts and Too Many Requests
  • Maximum of 3 retry attempts
  • Exponential backoff: 2s, 4s, 8s (total ~14s)
  • Automatic retry for idempotent operations only