In a marketplace payment stack, every transaction involves three parties: customer, seller, and platform and split payments is the mechanism that distributes funds among them at settlement time. Juspay Hyperswitch supports split payments through Stripe Connect and Adyen for Platforms as underlying infrastructure, each with distinct split models: Stripe uses direct or destination charges with application fees; Adyen uses a `split_items` array with typed allocations (BalanceAccount, Commission, Vat). Hyperswitch abstracts these differences behind a unified `split_payments` field in the payment create request, the same API call, regardless of which underlying processor handles the transaction.

How does a marketplace payment differ from a standard payment?

Split payment: A single customer transaction that is settled across multiple parties typically the seller, the platform, and any applicable fees in a single authorization. Unlike a standard payment where funds flow entirely to one merchant, a marketplace split payment allocates portions of each transaction to different accounts at settlement time.

A marketplace selling handmade goods takes a 10% commission. When a customer pays $100, the seller should receive $90 and the platform should receive $10. Without split payments, the platform would receive the full $100 and be responsible for separately transferring $90 to the seller - a deferred settlement model that creates cash flow risk, reconciliation overhead, and regulatory complexity around holding seller funds.

Split payments solve this by encoding the distribution at authorization time. The payment service provider settles directly to each party's account according to the split rules attached to the payment. No secondary transfer is required. No float is held by the platform.

The infrastructure that makes this possible at the PSP level is Stripe Connect (for Stripe-routed transactions) and Adyen for Platforms or Adyen for Marketplaces (for Adyen-routed transactions). Both provide sub-merchant account models where sellers have their own settlement accounts, and both accept split instructions alongside the payment authorization.

How does Stripe Connect handle split payments - direct vs. destination charges?

Stripe Connect: Stripe's infrastructure for platforms and marketplaces, which allows a platform to process payments on behalf of connected accounts (sellers) and distribute funds at settlement. Two charge models are supported: direct charges and destination charges.

Direct charge: The payment is created on the connected account, the seller's Stripe account and not on the platform's account. The customer's bank statement shows the seller's business name. Stripe fees are debited from the connected account. The platform's share of the transaction is taken as an application_fee, which Stripe automatically transfers to the platform account.

{
  "split_payments": {
    "stripe_split_payment": {
      "charge_type": "direct",
      "application_fees": 1000,
      "transfer_account_id": "acct_1PDftAIhl7EEkW0O"
    }
  }
}

Destination charge: The payment is created on the platform's Stripe account. The customer's bank statement shows the platform's business name. Stripe fees are debited from the platform. The seller's share is transferred to the destination account transfer_account_id after the platform's cut is retained.

The key difference between the two models:

Hyperswitch passes the charge_type, application_fees,transfer_account_id to Stripe as part of the payment create call. Hyperswitch returns the `charge_id` in the payment response, which is the Stripe charge identifier on the connected or platform account. Other key fields and their associated usage - on_behalf_of tells Stripe that the charge is being made on behalf of a connected account. Statement descriptor is the connected account's statement descriptor and appears on the customer's bank statement. The connected account's country and currency settings are used for authorization and the connected account is responsible for dispute and compliance

How does Adyen for Platforms handle split payments?

Adyen split settlement: Adyen's infrastructure for platforms uses a `split_items` array in the payment authorization request. Each item in the array specifies a split type, an amount, and optionally an account. The sum of all `amount` fields in the array must equal the total payment amount - Adyen validates this at the API level.

{
  "split_payments": {
    "adyen_split_payment": {
      "store": "4935y84385736",
      "split_items": [
        {
          "split_type": "BalanceAccount",
          "amount": 9000,
          "account": "BA3227C223222B5GH9H",
          "reference": "seller-split-ref",
          "description": "Seller payout"
        },
        {
          "split_type": "Commission",
          "amount": 1000,
          "account": "BA_platform_account",
          "reference": "platform-commission-ref",
          "description": "Platform commission"
        }
      ]
    }
  }
}

The split_type field controls what each item represents:

The store field is required only for Adyen Platform implementations (not Adyen Marketplace). If you are using Adyen's Platform model and omit store, the split transaction fails.

Hyperswitch passes the split configuration to Stripe or Adyen in the payment authorization request. The actual fund distribution at settlement is performed by those platforms Stripe's internal transfer engine and Adyen's balance platform. If a Stripe connected account hasn't completed onboarding and activated payouts, or if an Adyen balance account isn't configured, the settlement fails downstream.

How does Hyperswitch unify split payments across Stripe and Adyen?

Hyperswitch's split_payments field in the payment create request accepts a connector-specific sub-object: stripe_split_payment or adyen_split_payment. The calling application passes the appropriate sub-object based on which connector is handling the transaction.

This connector-specific structure exists because Stripe Connect and Adyen for Platforms have fundamentally different split models. A unified split format would require either lossy abstraction (losing connector-specific capabilities) or complex translation logic. Instead, Hyperswitch preserves each connector's native split semantics and routes the correct configuration to each.

The full payment create request for a Stripe-routed marketplace payment:

{
  "amount": 10000,
  "currency": "USD",
  "payment_method": "card",
  "customer_id": "cus_marketplace_buyer",
  "split_payments": {
    "stripe_split_payment": {
      "charge_type": "destination",
      "application_fees": 1000,
      "transfer_account_id": "acct_seller_stripe_id"
    }
  }
}

How does refund handling work in split payment transactions?

Refund behavior in split payments differs between Stripe charge types and requires explicit configuration.

Stripe direct charge refunds: The refund is issued from the connected account's balance. The revert_platform_fee flag returns the application_fee to the connected account before the refund is processed. Without revert_platform_fee: true, the platform retains the application fee even when the underlying transaction is refunded, creating a fee liability without a corresponding sale.

Stripe destination charge refunds: Requires both revert_platform_fee: true and revert_transfer: true. The revert_transfer flag returns the transferred funds from the destination (seller) account back to the platform before the refund fires. Without this, the platform account may not have sufficient funds to cover the refund because the seller's portion has already settled to the destination account.

{
  "refund_id": "ref_001",
  "payment_id": "pay_001",
  "amount": 10000,
  "split_refunds": {
    "stripe_split_refund": {
      "revert_platform_fee": true,
      "revert_transfer": true
    }
  }
}

Adyen split refunds: The same split_items structure used in the original payment is passed in the refund request. Adyen supports proportional refunds - if you refund 50% of the original amount, each split item should reflect the proportional reduction. Adyen validates that the refund split amounts sum to the total refund amount.

How do recurring split payments work?

Split payment configuration for recurring mandates follows a two-step sequence - Customer-Initiated Transaction (CIT) with setup_future_usage:off_session and Mandate-Initiated Transaction (MIT) using the payment_method_id. The split configuration is established at CIT time and referenced at MIT time.

The CIT creates the mandate and stores the split settlement metadata. The customer_id field is required. Hyperswitch stores the split configuration alongside the mandate however it still expects the subsequent MIT to specify the split payload which can be passed as part of the MIT call, without requiring the customer to re-authorize.

This is particularly relevant for subscription marketplaces where a seller's revenue share is taken on each recurring billing cycle: the transfer_account_id and application_fees (for Stripe) or the split_items (for Adyen) must be part of the CIT mandate configuration.

Wallets - Google pay, Apple pay and BNPLs - Klarna, Affirm with split payments

When enabling wallets or BNPLs via a PSP that supports split payments, the transaction-splitting mechanics work the same way as with cards. What changes is simply the payment method the end-user uses to complete the transaction.

Users see all available payment options in the unified payment SDK, and can select a wallet or BNPL based on their preference. The specific modes offered for each payment method - such as the decryption flow (PSP-managed, merchant-managed, or Hyperswitch-managed) for wallets like Apple Pay or Google Pay, or the in-SDK vs. redirect experience for BNPLs, are determined by Hyperswitch configuration and availability with underlying PSP. These modes are unaffected by whether the transaction is a split payment or a regular one.

What is the Hyperswitch platform account structure for marketplace operators?

Hyperswitch's account model for marketplace operators uses a three-level hierarchy: Organization → Merchant Account → Profile. Every payment is tagged to exactly one profile.

Platform Merchant: A privileged parent merchant account that manages connected sub-merchants. The platform merchant cannot process payments for itself, it acts exclusively as an orchestration layer. It owns the shared customer and payment method scope across all connected merchants and can act on behalf of connected merchants using the Platform API Key.

Connected Merchants: Sub-merchant accounts that participate in the platform's shared resource model. Customers and payment methods created by connected merchants are visible across the connected group. The platform merchant can operate connected merchants on-behalf - useful for handling payments, refunds, and payouts centrally while maintaining clear merchant attribution.

Standard Merchants: Fully isolated merchant accounts with their own customer and payment method scope. The platform merchant cannot act on behalf of standard merchants. These are appropriate when regulatory requirements, data boundary rules, or contractual obligations demand complete isolation between merchants.

Platform operators set up connected merchants using the Platform API Key - the same key creates merchant accounts, generates merchant-specific API keys, and configures connectors for each sub-merchant.

What breaks when marketplace split payments are misconfigured

Adyen split_items amounts not summing to the total. Adyen validates that the sum of all amount fields in the split_items array equals the total payment amount. If the split items add up to less or more than the total, the payment fails. This validation happens at the Hyperswitch level. Always verify that split amounts sum to the transaction total before making the API call.

Missing `store` field for Adyen Platform implementations. The store field in adyen_split_payment is required for Adyen Platform integrations (not Adyen Marketplace). If you are using Adyen's Platform model and omit `store`, the payment is rejected at the Adyen connector level. Adyen Marketplace integrations do not require `store`; Platform integrations do. Verify your Adyen account type before configuring split payments.

Stripe destination charge refunds without `revert_transfer`. When a destination charge is refunded, the platform account needs to reclaim the transferred funds from the seller account before issuing the refund to the customer. Without revert_transfer: true, the refund fails if the platform account doesn't have the funds, because they have already settled to the seller's connected account. Every destination charge refund must include both revert_platform_fee: true and revert_transfer: true.

Recurring split payments not configured at CIT. For subscription or recurring marketplace payments, the split configuration must be established during the Customer-Initiated Transaction (CIT) that creates the mandate. MIT calls reference the stored mandate; if the split metadata wasn't included in the CIT, the MIT charges might fail depending on the underlying PSP flexibility

Connected account not activated at the PSP level. A Stripe connected account must complete Stripe's onboarding and have payouts enabled before split settlements reach it. A payment can authorize and capture successfully through Hyperswitch; the split configuration is valid; but the funds don't reach the seller's account because Stripe's connected account hasn't cleared KYC. The payment fails as Stripe throws an invalid account error.

How to configure split payments in Hyperswitch

Step 1 - Configure the connector with sub-merchant account details. For Stripe, connected account IDs must be provisioned through Stripe Connect onboarding. For Adyen, balance accounts must be configured in the Adyen Customer Area before they can receive split allocations. Hyperswitch's connector configuration stores the platform-level PSP credentials; sub-merchant account IDs are passed per-payment in the split_payments field.

Step 2 - Implement split configuration in the payment create request. Pass `stripe_split_payment` or `adyen_split_payment` in the `split_payments` object depending on the target PSP.

Step 3 - Configure refund handling per charge type. For Stripe direct charges, include revert_platform_fee: true in refund requests. For Stripe destination charges, include both revert_platform_fee: true and revert_transfer: true. For Adyen, pass the same split_items structure in refund requests with proportional amounts.

The split_payments field is connector-scoped by design - Stripe Connect and Adyen for Platforms have different split models, and Hyperswitch preserves each model's native semantics rather than abstracting them into a lowest-common-denominator format. Understanding which model each connector uses and configuring accordingly is the core of marketplace payment integration through Hyperswitch.