Stripe Split Settlement

Overview

Stripe's Split Settlements functionality allows you to create charges and distribute payments between your platform and connected accounts (sellers or service providers). This feature is implemented in Hyperswitch through the SplitPaymentsRequest and supports both payment authorization and refund processing.

Payment Authorization

In the Payment Create request, include the Stripe split rule as provided below to dictate fund distribution at the time of transaction.

"split_payments": {
    "stripe_split_payment": {
        "charge_type": "direct",
        "application_fees": 100,
        "transfer_account_id": "{{CONNECTED_ACCOUNT_ID}}"
    }
}

Request Parameters

Payment Response

The response includes charge details for Split Settlements to verify distribution:

JSON

"split_payments": {
    "stripe_split_payment": {
        "charge_id": "ch_3QSzoAIhl7EEkW0O12IPHRiC",
        "charge_type": "direct",
        "application_fees": 100,
        "transfer_account_id": "acct_1PDftAIhl7EEkW0O"
    }
}

Split Refunds via Hyperswitch

For Refunds, include the appropriate split refund configuration based on the original charge_type.

1. For "charge_type": "direct"

JSON

"split_refunds": {
    "stripe_split_refund": {
        "revert_platform_fee": true
    }
}

2. For "charge_type": "destination"

JSON

"split_refunds": {
    "stripe_split_refund": {
        "revert_platform_fee": true,
        "revert_transfer": true
    }
}

Refund Parameters

• revert_platform_fee (boolean): Indicates whether the application fee should be refunded. If a full charge refund is given, the full fee is refunded; otherwise, it is proportional. Only the application that created the charge can refund it.
• revert_transfer (boolean): Indicates whether the transfer should be reversed. Reversal is proportional to the amount being refunded (either the entire or partial amount). Only the application that created the charge can reverse the transfer.

Recurring Payments (CIT/MIT)

Customer-Initiated Transaction (CIT)

In a CIT call, passing customer_id is mandatory along with the Stripe Split settlements object. The split settlement metadata is stored in the mandate for future MIT calls.

JSON

{  
    "customer_id": "StripeCustomer123",  
    "split_payments": {  
        "stripe_split_payment": {  
            "charge_type": "direct",  
            "application_fees": 100,  
            "transfer_account_id": "acct_123456789"  
        }  
    },  
    "customer_acceptance": {  
        "acceptance_type": "offline",  
        "accepted_at": "1963-05-03T04:07:52.723Z",  
        "online": {  
            "ip_address": "125.0.0.1",  
            "user_agent": "amet"  
        }  
    }  
}

Implementation Notes

• For direct charges, the transfer_account_id must be the connected account ID, not your platform account ID.
• For destination charges, the transfer_account_id cannot be your platform account ID as Stripe doesn't allow charges to your own account.
• The system validates that MIT calls match the split settlement configuration from the original CIT call.