> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bachs.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Money is always a decimal string at the currency's precision (for example "29.00"), paired with an ISO 4217 currency field. Never use minor units.
> Build against the sandbox first: base URL https://sandbox-api.bachs.io with sk_sandbox_ keys. Production is https://api.bachs.io with sk_live_ keys; going live is a key swap.
> Treat webhooks (for example collection.succeeded) as the source of truth for fulfilment, never client-side events or redirects.
> Subscriptions are created by completing a checkout for a recurring product. There is no direct create-subscription endpoint.
> IDs carry resource prefixes (cust_, prod_, sub_, chk_, inv_, ref_) and timestamps are ISO 8601 UTC.

# Split a payment between sellers

> Let a buyer pay once and split the payment between multiple sellers. Manage each seller’s share through settlement, refunds and disputes.

Split Pay lets a buyer pay once while you divide the payment between several sellers. Each seller gets their agreed share when the payment settles.

For example, a buyer books a room makeover through your marketplace. Three sellers work on the order: a lead seller, a designer, and an installer. The buyer makes one payment. You decide how much each seller receives and how much your platform keeps.

The flow is:

1. Create a checkout and name the sellers and their shares.
2. The buyer pays once.
3. Bachs records the shares and releases them when the payment settles, or holds them for you to release later.

Each seller needs a **connected account** to hold their money.

In the examples below, the **lead seller** is `acct_seller`. You pass this account in the `X-Account-Id` header. The designer and installer are the other sellers; you put their account IDs in `splits`.

For a payment shared between your platform and just one seller, see [direct and destination charges](https://docs.bachs.io/connect/split-payments.md).

## Before you start

* The platform API key creates the checkout for a seller account using `X-Account-Id`.
* All sellers must belong to the same platform. Accounts that are closed, suspended, or outside your platform cannot receive a share.
* Each receiving seller needs the `transfers` capability to receive money immediately. If a seller is still onboarding, configure whether their share should wait or whether the checkout should be refused.
* Grant the API key `payments:write` to create checkouts. Grant `splits:read` and `splits:write` to manage agreements and shares.

## Create the checkout

Call `POST /v1/checkout-sessions` with your platform API key.

This example has two cart lines: design costs NGN 2,000 and installation costs NGN 1,000. The buyer pays NGN 3,000 in total.

| Who receives money | How their share is calculated | Amount |
| - | - | - |
| Designer | 50% of the NGN 2,000 design line | NGN 1,000 |
| Installer | A fixed share of the installation line | NGN 300 |
| Your platform | A fixed platform fee | NGN 100 |
| Lead seller | What remains | NGN 1,600 before processing fees |

Replace the example account and product IDs with your own. Create the products with the prices above before using this request.

```bash theme={"dark"}
curl https://sandbox-api.bachs.io/v1/checkout-sessions \
  -H "Authorization: Bearer sk_sandbox_your_platform_key" \
  -H "Content-Type: application/json" \
  -H "X-Account-Id: acct_seller" \
  -d '{
    "product_cart": [
      {
        "product_id": "prod_design_package",
        "quantity": 1,
        "splits": [
          { "account": "acct_designer", "percent": "50" }
        ]
      },
      {
        "product_id": "prod_installation",
        "quantity": 1,
        "splits": [
          { "account": "acct_installer", "amount": "300.00" }
        ]
      }
    ],
    "platform_fee": "100.00",
    "settle_to": "seller",
    "release": "with_charge",
    "customer": { "email": "buyer@example.com" },
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/checkout"
  }'
```

### Understand the request

| Field or value | Meaning in this example |
| - | - |
| `X-Account-Id: acct_seller` | The connected account ID of the lead seller you are creating the checkout for. Replace the example with a real seller account ID. |
| `product_cart` | The products being purchased. Each entry is a separate cart line. |
| `product_id` | The ID of an existing product: `prod_design_package` for design and `prod_installation` for installation. The product supplies its price and currency. |
| `quantity: 1` | Buy one unit of that product. |
| `splits` | The shares for other sellers on this cart line. You can instead put `splits` on the checkout to split the whole payment. |
| `account` | The connected account ID of the seller receiving that share: the designer or installer here. |
| `percent: "50"` | Give this seller 50% of this line’s amount. Use `"50"` for 50%, rather than `"0.5"`. |
| `amount: "300.00"` | Give this seller a fixed 300 in the product’s price currency. This is a decimal amount, not an amount in the smallest currency unit. Use either `percent` or `amount` for a share. |
| `platform_fee: "100.00"` | Your platform takes a fixed 100 in the checkout currency. This is an amount, not a percentage. |
| `settle_to: "seller"` | The lead seller owns the charge and keeps the remaining proceeds after shares and fees. `"platform"` makes your platform own the charge and records the lead seller’s remainder as a share. |
| `release: "with_charge"` | Release the shares when the charge settles. `"manual"` holds them for later release. |
| `customer.email` | The buyer’s email address. |
| `success_url` | Where to send the buyer after a successful checkout. |
| `cancel_url` | Where to send the buyer when they cancel checkout. |

### Read the response

Bachs calculates an amount for each share. Here is an example response excerpt:

```json theme={"dark"}
{
  "checkout_id": "chk_example",
  "status": "open",
  "amount": "3000.00",
  "currency": "NGN",
  "settle_to": "seller",
  "release": "with_charge",
  "splits": [
    {
      "id": "<share_id>",
      "account": "acct_designer",
      "role": "collaborator",
      "line_item": 0,
      "amount": "1000.00",
      "currency": "NGN",
      "amount_reversed": "0.00",
      "status": "pending"
    },
    {
      "id": "<share_id>",
      "account": "acct_installer",
      "role": "collaborator",
      "line_item": 1,
      "amount": "300.00",
      "currency": "NGN",
      "amount_reversed": "0.00",
      "status": "pending"
    }
  ]
}
```

The fields in each share tell you:

| Field | What it means |
| - | - |
| `id` | The share ID. Use it to release or reverse this share. |
| `account` | The seller receiving this share. |
| `role` | `collaborator` means another seller. `seller` means the lead seller’s share when the platform holds the payment. Keep these exact API values. |
| `line_item` | Which cart line the share belongs to. Counting starts at `0`: design is `0`, installation is `1`. |
| `amount` and `currency` | How much the seller is due and in which currency. |
| `amount_reversed` | How much has been taken back from this share. `"0.00"` means nothing has been taken back. |
| `status` | Where the share is in its lifecycle. `pending` means it has not settled yet. |

### Split the whole payment or one cart line

Put `splits` inside a `product_cart` item to split that line, as shown above. Put it on the checkout itself to split the whole payment. A whole-payment share has no `line_item`.

For each share, use either `percent` or a fixed `amount`. If you include `currency`, it must match the sale’s price currency.

> [!NOTE]
>
> Use either `splits` or `split_agreement` on the same checkout or cart line. Split Pay cannot be combined with `transfer_data`.

## Decide who holds the payment

`settle_to: "seller"` makes the seller the charge owner. Other sellers receive their shares from that sale, and the seller keeps the remainder.

`settle_to: "platform"` makes the platform the charge owner. Other sellers receive their shares, and the seller is recorded as an additional share with `role: "seller"`. All sellers must be able to receive the shares, or qualify for the configured pending-share behavior.

When omitted, `settle_to` and `release` use the platform's saved defaults.

## Save an agreement for future payments

Use a saved agreement when sellers should accept their shares before you take payments.

Your platform’s `split_consent` setting chooses how this works:

* `platform`: specify shares directly in the checkout request, as in the first example.
* `agreement`: use a saved agreement that every other seller has accepted. You cannot send shares directly in `splits`.

Create an agreement with `POST /v1/split_agreements` using a platform API key with `splits:write`:

```json theme={"dark"}
{
  "seller": "acct_seller",
  "name": "Room makeover split",
  "parties": [
    { "account": "acct_designer", "percent": "40" },
    { "account": "acct_installer", "percent": "10" }
  ]
}
```

| Field | Meaning |
| - | - |
| `seller` | The lead seller’s account ID. |
| `name` | A label you choose so sellers can recognise the agreement. |
| `parties` | The other sellers and their agreed shares. Here, the designer gets 40% and the installer gets 10% of the amount the agreement applies to. |

The lead seller keeps the remainder after shares and fees.

The other sellers answer from their own connected-account dashboard. A connected-account member with permission to respond must accept the version; a platform administrator cannot accept on a seller's behalf. Until all parties accept, that version is pending and cannot be used at checkout.

Name the accepted agreement on the whole checkout with `split_agreement`, or on one cart line with `product_cart[].split_agreement`. For example:

```json theme={"dark"}
{
  "product_cart": [
    { "product_id": "prod_design_package", "split_agreement": "sagr_example" }
  ]
}
```

Create a new version with `POST /v1/split_agreements/{agreement_id}/versions`. Sales already created keep their original version; the new version applies only after every seller accepts it. You can list, retrieve, and archive agreements with the other endpoints under `/v1/split_agreements`.

Other sellers use these signed-in dashboard routes:

| Action | Route |
| - | - |
| List agreements | `GET /v1/i/split_agreements?filter=awaiting_my_answer` |
| View an agreement | `GET /v1/i/split_agreements/{agreement_id}` |
| Accept a version | `POST /v1/i/split_agreements/{agreement_id}/versions/{version}/accept` |
| Decline a version | `POST /v1/i/split_agreements/{agreement_id}/versions/{version}/decline` |

Use `awaiting_my_answer` to show agreements the signed-in seller needs to accept or decline, `active` to show active agreements, or `all` to show every agreement visible to that seller. In the accept and decline routes, `{version}` is the agreement version being answered.

## Follow each share through settlement

A share starts as `pending`. Its status changes as the payment settles, the seller withdraws money, or a refund or dispute affects it:

| Status | Meaning |
| - | - |
| `available` | The share reached the seller's available balance. |
| `held` | The share is held for manual release. A held share can be released by the platform or automatically after 90 days if the seller can receive it. |
| `pending_kyc` | The seller is not yet able to receive transfers. Once eligible, the share can be released; the 90-day pending-share policy determines whether it is returned or continues waiting. |
| `on_hold` | The share is held while its charge is under dispute. |
| `paid_out` | The seller has withdrawn the share. A later refund or reversal may recover only what remains available from the recipient; the charge holder covers the rest. |
| `reversed` | The share has been taken back in full. |
| `returned` | The share was returned to the seller or charge holder under the pending-share policy. |

### Release a held share

Call `POST /v1/split_shares/{share_id}/release`. Replace `{share_id}` with the share’s `id`. The receiving seller must be able to receive money.

### Take back a share

Call `POST /v1/split_shares/{share_id}/reversals` to take back all or part of a share. You can include:

* `amount`: the decimal amount to take back.
* `reason`: why you are taking it back.

You cannot use this endpoint while the share is held for a dispute.

### Find shares

Call `GET /v1/split_shares`. These query parameters help you find what you need:

| Parameter | What to pass |
| - | - |
| `charge` | A charge ID, to find shares for one payment. |
| `account` | A seller account ID, to find that seller’s shares. |
| `status` | A status from the table above, such as `held`. |
| `limit` | How many results to return. |
| `offset` | How many results to skip. `limit=20&offset=20` gets the second page of 20. |

Your platform API key needs `splits:read` to read shares and `splits:write` to release or reverse them.

The signed-in dashboard uses `GET /v1/i/split_shares` and `GET /v1/i/split_shares/{share_id}`. Releasing or reversing shares there requires `splits:manage` permission.

### Receive updates

Listen for `split_share.created` and `split_share.updated` to follow a share without repeatedly fetching it. Bachs sends these webhooks to the receiving seller and your platform.

Agreement changes send `split_agreement.updated` to all sellers and your platform.

## Handle refunds and disputes

### Refunds

The platform's `split_refund_shares` setting controls how a refund changes the shares:

* `by_item` reverses shares tied to the refunded cart line when the refund includes its zero-based `line_item`. Without a line, shares are reduced proportionally.
* `proportional` reduces the shares in proportion to the refund.
* `none` leaves seller shares unchanged; the charge holder is responsible for the refund amount.

The setting is the default policy for new checkouts. A refund request can use the refund flow's `refund_shares` option to select the policy for that refund. In seller-settlement mode, `refund_platform_fee: true` also returns the platform fee; when the platform holds the sale, the fee is returned with the sale instead.

### Disputes

When a dispute opens, unsettled or unpaid shares can move to `on_hold`. If the dispute is won, the shares are released back to their prior destination; if it is lost, the shares are taken back to cover the loss. A share already withdrawn cannot be recovered from the recipient beyond the funds they still have; the charge holder covers any shortfall.

## Split subscription payments

A recurring checkout can carry its split terms to each subscription renewal. If customer credit reduces the amount due, the shares scale with the amount collected. Replacing an agreement affects future renewal charges, not a charge that has already been created.

## Set your platform defaults

Split Pay settings live in **Connect settings** in the platform dashboard. `GET /v1/i/connect/setup` reads the settings; `PUT /v1/i/connect/setup` updates the fields you send. These dashboard routes use a signed-in platform user; reading requires Connect view access and updating requires Connect management permission.

For example, a platform that lets other sellers accept saved agreements and holds shares until the platform releases them can save:

```json theme={"dark"}
{
  "split_settle_to": "seller",
  "split_refund_shares": "by_item",
  "split_release": "manual",
  "split_consent": "agreement",
  "split_pending_shares": "hold"
}
```

These settings apply when a checkout does not override them. The defaults are `platform` for `split_settle_to`, `by_item` for `split_refund_shares`, `with_charge` for `split_release`, `platform` for `split_consent`, and `refuse` for `split_pending_shares`.

Here is what each setting means:

* `split_settle_to`: `seller` makes the lead seller own the charge; `platform` makes your platform own it and gives the lead seller a share.
* `split_refund_shares`: `by_item` takes shares back from the refunded cart line (or proportionally when no line is supplied); `proportional` reduces shares in proportion to the refund; `none` keeps the sellers’ shares unchanged and leaves the charge owner to fund the refund.
* `split_release`: `with_charge` releases shares at settlement; `manual` holds them for later release.
* `split_consent`: `platform` lets you specify shares directly in the checkout request; `agreement` requires a saved agreement accepted by every other seller.
* `split_pending_shares`: `refuse` rejects checkout if a receiving seller is still onboarding; `hold` allows checkout and holds that seller’s share until they can receive it.

Settings apply to new checkouts. Existing charges and shares keep the terms they were created with.

## Next steps

* [Direct and destination charges](https://docs.bachs.io/connect/split-payments.md) for a charge shared between your platform and one account.
* [Connect quickstart](https://docs.bachs.io/connect/quickstart.md) to create and onboard connected accounts.
* [Refunds on Connect charges](https://docs.bachs.io/connect/refunds.md) and [disputes on Connect charges](https://docs.bachs.io/connect/disputes.md).
* [Testing Connect](https://docs.bachs.io/connect/testing.md) before you go live.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.