Split Settlements

Use a split settlement to allocate one OpenPath payment across two or more merchant accounts. This guide is for platforms, marketplaces, and multi-party payment flows that need to specify how a payment settles.

A split settlement is an allocation instruction for one payment. It does not create multiple card charges: the customer is charged once, and the request supplies the individual settlement amounts and destination merchant accounts.

Before you begin

1. Use the OpenPath v5 Transaction API and authenticate your request as described in the Transaction API reference.
2. Confirm that your selected gateway or processor is enabled for split settlements and obtain the destination merchant_account_id values from your OpenPath or processor configuration.
3. Decide the allocation before submitting the payment. Every allocation must have a positive amount, and a split settlement must contain at least two allocations.

The split_settlement object is gateway-neutral, but processor onboarding, destination-account identifiers, supported currencies, and funding timing are processor-specific. Do not use a destination account ID until it has been provisioned for the processor route you will use.

How a split settlement works

Send a split_settlement object with the payment request. The object contains the payment total and a splits array. Each entry specifies a destination merchant account and its allocation.

Before sending the request, make sure that split_settlement.total matches the payment total and that the amounts in splits add up to that total. This is the allocation your integration intends; the API contract does not define automatic balancing or prorating.

Create a split settlement

Create a split settlement by including split_settlement in a Charge request. In a Charge request, the payment amount is detail.amount; use the same value for split_settlement.total.

The following example charges $100.00 once and allocates $90.00 to the seller and $10.00 to the platform.

{
  "capture": true,
  "token": "payment_token_from_openpath",
  "detail": {
    "amount": 100.00,
    "currency": "USD",
    "order_id": "ORDER-10001",
    "description": "Marketplace order"
  },
  "split_settlement": {
    "total": 100.00,
    "reference": "ORDER-10001",
    "description": "Marketplace order settlement",
    "splits": [
      {
        "merchant_account_id": "seller_acct_123",
        "amount": 90.00,
        "category": "merchant",
        "reference": "ORDER-10001-seller",
        "description": "Seller proceeds"
      },
      {
        "merchant_account_id": "platform_acct_001",
        "amount": 10.00,
        "category": "platform_fee",
        "reference": "ORDER-10001-platform-fee",
        "description": "Platform commission"
      }
    ]
  }
}

When the transaction response is returned, retain the OpenPath transaction ID together with your settlement and allocation references. The Transaction API response model includes split_settlement, which lets you reconcile the accepted allocation with your order records.

Authorize first, then settle or adjust

The Transaction API also accepts split_settlement on these transaction actions:

• Increment
• Capture
• Refund

For these actions, send the original transactionId, the action total, and the allocation in split_settlement. Set the split-settlement total to the amount of that action, not to the original authorization amount.

{
  "transactionId": "12088864608",
  "total": 100.00,
  "split_settlement": {
    "total": 100.00,
    "reference": "ORDER-10001-capture",
    "splits": [
      {
        "merchant_account_id": "seller_acct_123",
        "amount": 90.00,
        "category": "merchant"
      },
      {
        "merchant_account_id": "platform_acct_001",
        "amount": 10.00,
        "category": "platform_fee"
      }
    ]
  }
}

Use the same pattern for a partial capture, increment, or refund, with totals and allocations that reflect that action. Do not assume that an omitted allocation will be copied from an earlier transaction, or that a refund is automatically prorated; send the intended allocation explicitly and confirm processor-specific behavior during onboarding.

Validate and handle errors

Before submitting a request, validate the following in your application:

1. The payment or action total equals split_settlement.total.
2. The sum of all splits[].amount values equals split_settlement.total.
3. There are at least two splits, and every split has a non-empty merchant_account_id and an amount greater than zero.
4. Each destination account is valid for the gateway or processor selected for the transaction.

The Transaction endpoints document 400 for an invalid request, 401 for an authentication failure, and 415 for an unsupported media type. If a split request fails, save the request reference and transaction ID when available, verify the allocation and destination account IDs, then contact OpenPath support or your processor contact for route-specific settlement configuration.

Related API reference

• Transaction API overview
• Create a Charge
• Increment a transaction
• Capture an authorization
• Refund a transaction