Skip to main content
Version: v2

Split Tender Overview

Split Tender payments enable a single transaction to be divided across multiple payment methods (e.g., two cards). This section documents the end-to-end lifecycle, including:

Scope
  • Payment Method Type: CARD, BANK ACCOUNT
  • Allowed number of Payment Methods: 2
  • API:
    • Service Layer: Sessions - v2/sessions | Payments - v2/payments | Refunds - v2/refunds
    • Scope: merchant, user | Mode: Pay with stored card
  • UI:
    • Supported Session Mode: PAYMENT_WITH_WALLET
Split Tender Handling
  • Partial Success:
    • ⚠️ No Partial Success on payments, If any portion under split tender fails, entire payment is treated as failure and all dangling transactions will be rolled back. Learn more
    • Partial Success will be accepted only for Capture, Cancel and Refunds.
  • Payment Amount: Amount should be specified for each payment method under Split tender transaction
  • Payment Type: Payment Type should be consistent across payment methods in split tender
  • Webhooks: Webhooks will be triggered only at parent transaction level for final status

Overview​

Split Tender enables customers to pay for a single order using more than one payment method. This functionality is particularly valuable for high-value purchases, gift card + credit card combinations, or scenarios where a single card has insufficient funds. The CCG platform ensures atomicity and consistency across all payment methods involved in the transaction.

Key Benefits​

  • Flexibility for Customers: Enables payment with multiple payment methods when a single method is insufficient
  • Higher Conversion Rates: Reduces cart abandonment by offering alternative payment options when primary method fails
  • Support for Mixed Payment Types: Future capability to support combinations like card + HSA/FSA card, gift card + credit card
  • Seamless Consumer Experience: Single checkout flow handles complex payment combinations without additional steps
Related Specs
  • Authorization: How split tender payments are authorized and orchestrated
  • Capture: Capturing funds from split tender authorizations
  • Cancel: Cancelling split tender payments and handling failures
  • Refunds: Refunding split tender payments, including partial and multiple refunds

Split Tender Process Flow​

Split Tender Process Flow

Scope​

  • Payment Method Type: CARD and Bank Account
  • Supported Flows: Authorization, Capture, Cancel, Refund
  • Mode: Pay with Stored Payment Method
  • Transaction Types: Sale and PreAuth (both payment methods must use the same type)

Technical Specifications​

  • Maximum Payment Methods: 2 per transaction
  • Amount Specification: Required at individual payment method level
  • Webhooks: Single webhook at transaction level; includes details for both payment methods

Assumptions​

To ensure consistent and reliable split tender transactions, our implementation operates with the following foundational assumptions:

  • Amount Preservation: The specified amount for each payment method is preserved exactly as entered without automatic redistribution
  • Payment Type Consistency: Both payments must use identical transaction types (either both PreAuth or both Sale)
  • Stored Methods Only: Currently, only stored payment methods are supported in split tender flows
  • Retry Limitations: Maximum 5 retries allowed for the entire transaction to prevent indefinite processing
    • Retry Exhaustion Handling
      • If the payment cannot be moved to COMPLETED or FAILED within the maximum retry limit, the transaction should be canceled to maintain transaction integrity.
  • Explicit Amount Requirements: Amount must be explicitly specified at each payment method level for transaction clarity
  • ⚠️ Partial Success Handling:
    • ⚠️ Partial Success is not permitted for payment operations
    • ✅ If any payment fails during capture, refund, or cancellation operations, the transaction is marked as PARTIAL_SUCCESS and requires merchant intervention
  • Guest Payment Fallback: In PAYMENT_WITH_WALLET mode, if customer creation fails, session will fall back to guest with PAYMENT mode allowing only single payment.
  • Payment Type:
    • When ACH payment method is used, payment type is restricted to SALE
important

By rolling back partial success scenarios in split tender according to the specified assumptions, the system can maintain transaction integrity, transparency, and compliance with the defined requirements.

⚠️ Constraints​

  • Two Payment Methods only: Only Two payment methods allowed per transaction
    Impacts
    • Financial Impact: Stripe incur flat processing fees for every transaction (typically $0.30 per transaction plus percentage).
    • System Complexity:
      • Enhanced error handling and rollback mechanisms required to maintain atomicity across both payment methods
      • Additional state management overhead to track the status of multiple payment components
      • More complex database relationships and transaction logs to maintain payment associations
    • Increased payment processing time:
      • Parallel processing of multiple payment methods optimizes transaction completion time
      • Additional validation steps required for each payment method before proceeding
      • Potential for cascading retries if one payment method experiences temporary issues
  • ⚠️ Different payment Methods only:
    • Split tender transactions require different payment methods for each component the same payment method cannot be used twice
  • Same Payment Type: Both payment methods must be of the same type - either PreAuth or Sale consistently
  • Amount validation: The total transaction amount must be equal to amount specified for each payment methods.
    • ❗️In case of split payment failure, users are provided the option to retry using a single payment method.
  • ⚠️ No Time Travel: Payments initiated in v1 will not be processed in v2
    • For Example: payments initiated in v1, cannot be captured in v2
  • Session Window Benefits
    • Optimized Processing Time: Parallel processing significantly reduces transaction completion time
    • Reduced Timeout Risk: Decreased chance of session timeouts due to faster parallel processing

ACH Payments Challenges​

  • Lack of Real-Time Authorization:
    • ACH transactions do not typically offer immediate authorization or verification of funds, making it challenging to quickly confirm availability of funds for each tender portion.
    • This can result in uncertainty about transaction approval status, potentially causing delays or declined payments.
  • Settlement Timing and Synchronization
    • ACH payments have delayed processing (often 1-3 business days). When splitting tender, individual payments may settle on different schedules, complicating reconciliation and customer service.
    • Different processing timeframes between ACH and card would create Timing Discrepancies
      • Combining card and bank account payment methods creates uncertainty. You might receive immediate approval on the card portion, but later face rejection or delays on the ACH portion.
  • Increased Risk of Partial Payment Failures:
    • If any portion of the split ACH payment is returned or rejected (due to insufficient funds, invalid account information, or other issues), managing partial payment failures becomes challenging.

🔍 Edge Cases & Critical Scenarios​

Split tender introduces unique scenarios that require strategic handling. CCG approach ensures that complex payment situations are managed with precision and reliability:

🚦 Abandoned Transaction Management​

when a user suddenly closes their browser or loses connection during mid-payment, the system can be left in an ambiguous state—one payment may be completed while the other fails, see UnAttended Payment Handling

⚠️ Dashboard-Initiated State Conflicts​

When merchants perform operations directly in Stripe's dashboard instead of through CCG, transactions can enter indeterminate states. Review Transaction Management Guidelines

🛡️ Dispute Resolution​

Split tender introduces complexity to the dispute process when one payment under transaction is disputed. Understand Dispute Handling

📊 Reporting​

Reporting maintains traceability between individual payment methods and their parent transactions, enabling accurate financial reconciliation and clear audit trails.

  • Key features include transaction grouping, split payment indicators, and automatic sum validation