- Create a checkout and name the sellers and their shares.
- The buyer pays once.
- Bachs records the shares and releases them when the payment settles, or holds them for you to release later.
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
transferscapability 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:writeto create checkouts. Grantsplits:readandsplits:writeto manage agreements and shares.
Create the checkout
CallPOST /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:Split the whole payment or one cart line
Putsplits 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’ssplit_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 insplits.
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:
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 aspending. Its status changes as the payment settles, the seller withdraws money, or a refund or dispute affects it:
Release a held share
CallPOST /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
CallPOST /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.
Find shares
CallGET /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 forsplit_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’ssplit_refund_shares setting controls how a refund changes the shares:
by_itemreverses shares tied to the refunded cart line when the refund includes its zero-basedline_item. Without a line, shares are reduced proportionally.proportionalreduces the shares in proportion to the refund.noneleaves seller shares unchanged; the charge holder is responsible for the refund amount.
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 toon_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:
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:sellermakes the lead seller own the charge;platformmakes your platform own it and gives the lead seller a share.split_refund_shares:by_itemtakes shares back from the refunded cart line (or proportionally when no line is supplied);proportionalreduces shares in proportion to the refund;nonekeeps the sellers’ shares unchanged and leaves the charge owner to fund the refund.split_release:with_chargereleases shares at settlement;manualholds them for later release.split_consent:platformlets you specify shares directly in the checkout request;agreementrequires a saved agreement accepted by every other seller.split_pending_shares:refuserejects checkout if a receiving seller is still onboarding;holdallows checkout and holds that seller’s share until they can receive it.
Next steps
- Direct and destination charges for a charge shared between your platform and one account.
- Connect quickstart to create and onboard connected accounts.
- Refunds on Connect charges and disputes on Connect charges.
- Testing Connect before you go live.

