Skip to main content
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.

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. Replace the example account and product IDs with your own. Create the products with the prices above before using this request.

Understand the request

Read the response

Bachs calculates an amount for each share. Here is an example response excerpt:
The fields in each share tell you:

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.
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:
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:
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: 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:

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: 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:
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