Build a marketplace

Your customers buy from your marketplace, so the sale is yours: the charge lands in your balance, and each seller’s share moves down to it when the charge settles. In this guide you’ll create a seller, sell something, take the payment, and watch the seller’s share arrive. By the end you’ll have run a full destination charge without moving real money.

How it fits together

The sale is yours, so the money lands in your balance first. Bachs moves the seller’s share to the seller’s balance when the charge settles, and the seller withdraws from there.

What you’ll use

Object	Its job in this build	Reference
Account	The seller. It receives money and withdraws it, but never takes payments itself.	Accounts
Checkout session	Your platform’s checkout. `transfer_data` names the seller and its share.	Destination charges
Transfer	The seller’s share, moved at settlement.	Transfers
Payout destination	Where the seller withdraws to.	Payouts on Connect
Webhook endpoint	Tells you about payments and about your sellers’ accounts. Set `event_source` to `connect` or `all`.	Connect events

Before you start

A sandbox API key (sk_sandbox_...). See Authentication.
The connect capability active on your account. See Become a platform.

Every request below goes to https://sandbox-api.bachs.io. Going live is the same calls against https://api.bachs.io with an sk_live_ key. See Take Connect live.

Steps

Create the seller

A marketplace seller receives money; it never takes payments of its own. So it only needs the recipient configuration, and its onboarding stays short. Naming no payment-accepting capability is what keeps it that way.

curl -X POST https://sandbox-api.bachs.io/v1/accounts \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "ada@example.com",
    "display_name": "Ada Stores",
    "country": "NG",
    "entity_type": "individual",
    "configuration": { "recipient": {} }
  }'

{
  "id": "acct_Shi4LnKkKht5bmbS",
  "name": "Ada Stores",
  "country": "NG",
  "entity_type": "individual",
  "capabilities": {
    "payouts":     { "status": "active", "requested": true },
    "transfers":   { "status": "active", "requested": true },
    "conversions": { "status": "active", "requested": true }
  },
  "configuration": { "recipient": {} },
  "balance_currencies": [],
  "is_active": true
}

Copy the id. Every step below uses it as the seller’s account id.transfers is what lets the seller receive its share, and payouts is what lets it withdraw. In sandbox both are active immediately; in live they start pending_review until a reviewer enables them. See Capabilities and Testing Connect.

Create something to sell

The product is yours, not the seller’s: you are the merchant of record. Price it in NGN, which settles the same day.

curl -X POST https://sandbox-api.bachs.io/v1/products \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Handwoven basket",
    "description": "Sold by Ada Stores on the marketplace.",
    "price": { "currency": "NGN", "amount": "100000.00" }
  }'

{
  "id": "prod_a3ef11afb6c446f9ba41",
  "name": "Handwoven basket",
  "price": { "currency": "NGN", "price_type": "fixed", "amount": "100000.00" },
  "status": "active"
}

Copy the product id for the next step.

Create the checkout, naming the seller

transfer_data.destination is what makes this a destination charge: the sale is yours, and the account you name is paid out of it. platform_fee is the part you keep; naming transfer_data.amount instead fixes what the seller receives, with your platform keeping the rest. See Destination charges for both.

curl -X POST https://sandbox-api.bachs.io/v1/checkout-sessions \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      { "product_id": "prod_a3ef11afb6c446f9ba41", "quantity": 1 }
    ],
    "transfer_data": { "destination": "acct_Shi4LnKkKht5bmbS" },
    "platform_fee": "20000.00",
    "customer": { "email": "jane@example.com" },
    "success_url": "https://example.com/thank-you",
    "cancel_url": "https://example.com/checkout"
  }'

{
  "checkout_id": "chk_yMpCSunbArKaSnzJ",
  "status": "open",
  "amount": "100000.00",
  "currency": "NGN",
  "platform_fee": "20000.00",
  "checkout_url": "https://sandbox-checkout.bachs.io/c/SfxP7y-gSkzJsZs"
}

Copy the checkout_id and checkout_url.Out of the 100000.00 the customer pays, 20000.00 is yours and the rest is the seller’s.

Name only an account you own. Any other id is refused, in sandbox and in live.

Send the customer to pay

In your integration you redirect the customer to checkout_url and they pay on the page we host. To finish this guide, open the link and complete the payment there.This account is in sandbox, so the payment is simulated, no funds move. See Test payment outcomes.

Confirm the payment landed

The simulated outcome finalizes a second or two later. Read the checkout back until status is completed:

curl https://sandbox-api.bachs.io/v1/checkout-sessions/chk_yMpCSunbArKaSnzJ \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..."

{
  "checkout_id": "chk_yMpCSunbArKaSnzJ",
  "status": "completed",
  "payment_status": "succeeded",
  "amount": "100000.00",
  "currency": "NGN"
}

In your integration you would not poll for this. Subscribe to checkout.completed instead and react when it arrives.

Read the split

The seller’s share moves as a transfer when the charge settles, never sooner. Filter by the seller’s account id:

curl "https://sandbox-api.bachs.io/v1/transfers?connected_account_id=acct_Shi4LnKkKht5bmbS" \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..."

{
  "items": [
    {
      "id": "tr_b13a83695e65423fa8854fab",
      "source": "org_bd31b6b3037d404ebe116ec69d955ee3",
      "destination": "acct_Shi4LnKkKht5bmbS",
      "amount": "100000.000000000000000000",
      "currency": "NGN",
      "status": "paid",
      "kind": "payout",
      "source_charge_id": "ch_ff10c7a1b6b4427caf347d748fd4a183",
      "created_at": "2026-08-12T19:41:37.021329+00:00"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false,
    "limit": 50,
    "offset": 0,
    "returned": 1,
    "total": 1
  }
}

status is paid once settlement has posted the movement. source_charge_id ties the share back to the sale that produced it, which is what you show a seller asking where an amount came from.The transfer carries the full 100000.00 the customer paid, not the 80000.00 the seller ends up with: because you named your own cut with platform_fee, that cut settles separately, readable at Platform fees. Naming transfer_data.amount instead would fix the seller’s share directly, and the transfer would carry only that. See Destination charges for both forms.

Read the seller's balance

The share is the seller’s own money now, in its own balance. Send X-Account-Id to read an account’s balance instead of yours:

curl https://sandbox-api.bachs.io/v1/balances \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "X-Account-Id: acct_Shi4LnKkKht5bmbS"

{
  "account_id": "acct_Shi4LnKkKht5bmbS",
  "balances": [
    { "currency": "NGN", "available_balance": "80000.00", "pending_balance": "0.00" },
    { "currency": "USD", "available_balance": "0.00",     "pending_balance": "0.00" }
  ]
}

Drop the header to read your own, which went up by 19850.00. That is the whole sale accounted for:

	NGN
Customer paid	100000.00
Seller’s share	80000.00
Your fee, less our processing fee	19850.00
Our processing fee	150.00

Your 20000.00 fee is what you keep, and our fee comes out of it because the sale is yours. See Processing fees.

The seller held no NGN until this sale. An account holds a currency once money arrives in it.

What you built

A sale that belongs to your marketplace, split with the seller who fulfilled it, and a transfer you can point at to explain where the money went. The seller can withdraw its balance once it has given you a payout destination, which is one of the requirements it still owes. Read what is outstanding from requirements.currently_due on the account, and see Onboard through the API for collecting it, or Onboarding to hand the whole flow to us. Because the sale is yours, a refund or a lost dispute debits you, not the seller. See Refunds and disputes before you go live.

Webhooks to handle

Create your endpoint with event_source set to connect or all, or it receives nothing about your sellers’ accounts. On an event from a seller’s account, the top-level account field names the seller.

Event	What it means	What your platform does
`account.updated`	A seller’s onboarding state changed.	Read `requirements.currently_due` and ask the seller for what is missing.
`capability.updated`	A capability on a seller’s account changed status.	Let the seller sell or withdraw once the capabilities it needs are `active`.
`checkout.completed`	The customer paid.	Read the checkout back, then mark the order paid.
`transfer.created`	The seller’s share moved to its balance at settlement.	Record the seller’s earnings.
`payout.paid`, `payout.failed`	A seller’s withdrawal arrived or failed.	Show the seller its payout status.

See Monitor onboarding for reacting to onboarding without polling.

Edge cases

The seller has not finished onboarding

A seller can withdraw only once it has given you a payout destination and its payouts capability is active. In production, capabilities start restricted until a reviewer enables them, so wait for capability.updated rather than assuming. See Requirements.

The customer asks for a refund

The sale is yours, so a refund debits your balance, not the seller’s. Decide how you recover the seller’s share before you go live. See Refunds and disputes.

The customer disputes the payment

You are liable, as the owner of the charge. The disputed amount is set aside from your available balance while the dispute is open, and the dispute fee is charged when it opens. See Disputes on Connect.

The seller asks for its money before settlement

The seller’s share moves when the charge settles, not when the customer pays. Show the seller its earnings from transfer.created, and don’t send a second, manual transfer for the same sale.

A seller's withdrawal fails

You receive payout.failed, and the amount returns to the seller’s balance. Ask the seller to check its destination. A destination is used only once it is usable. See Payouts on Connect.

Go-live checklist

Your platform has completed registered-business compliance and connect is active in production. See Take Connect live.
Your production keys have only the scopes you use, such as connected_accounts:write and payouts:write.
Your production webhook endpoint has event_source set to connect or all, and its signing secret is checked against a live delivery.
Your integration waits for capabilities to become active in production instead of assuming them.
Every transfer and withdrawal sends an Idempotency-Key, and a 5xx is checked before it is retried.
Your team knows that refunds and lost disputes debit your balance.

Build it with an AI assistant

Give this prompt to a coding assistant that can work with your app’s code. It builds the flow on this page into your own app. For prompts that need nothing from Connect, and the rules to give your assistant, see Build with AI. What you’ll build: your platform collects a payment, keeps its fee, and the seller’s share reaches the seller’s Bachs balance at settlement. The seller can then pay out to its own approved destination. Have ready: the Connect capability, seller records, your fee, and the collection currency. Start with one seller per order. If each business should own its sale, use Platform for businesses.

Prompt

Add a single-seller marketplace payment flow with Bachs Connect. Inspect our
onboarding, orders, authentication, database, and payment code. Confirm that
our platform owns the sale and takes a fee. Ask for missing currency, fee,
or seller-onboarding decisions.

Read the SDK's current scope at https://github.com/bachsdev/bachs-node.
Connect account context, seller onboarding and checkout splits are not supported
by the current SDK. Use documented API calls for these operations; never invent
SDK methods or force unsupported fields through type casts. A Node.js server can
use the SDK's webhooks.constructEvent for signature verification.

Read:
https://docs.bachs.io/build/use-cases/marketplace.md
https://docs.bachs.io/connect/onboarding.md
https://docs.bachs.io/connect/capabilities.md
https://docs.bachs.io/connect/marketplaces/refunds-and-disputes.md
https://docs.bachs.io/connect/payouts.md
https://docs.bachs.io/guides/webhooks/overview.md
https://docs.bachs.io/guides/idempotency.md

Use https://sandbox-api.bachs.io with BACHS_API_KEY on the server. Omit checkout return URLs for local testing; configured redirects must be public. Explain
Connect setup and the capabilities and requirements each seller needs.

Create and save a recipient sub account for each seller, and implement the
documented onboarding path. Choose the seller, product, and platform fee on the
server from our order. Create the platform checkout with
transfer_data.destination and platform_fee, linked to our order.

Verify X-Bachs-Signature-V2 on the raw body, with timestamp tolerance and all
v1 signatures. Confirm payment from verified events matched to the order,
amount, and currency. Deduplicate durably, keep state updates recoverable,
and return 5xx on processing failure.

Track payment, settlement into the seller's balance, and payout delivery
separately. The destination charge creates its transfer at settlement:
do not send a second manual transfer. Use documented account context for
the seller's balance and destination. Gate payouts on active capabilities
and a usable destination owned by that seller. A payout create response
does not confirm delivery.

Keep secrets server-side and amounts as decimal strings. Persist operation
idempotency keys and reconcile uncertain writes before retrying. Explain who
bears refunds and disputes. Do not describe this flow as escrow.

Test a paid sale and split, duplicate events, incomplete onboarding, a
destination awaiting approval, and a failed payout. Report which tests used
mocks and which ran in sandbox, remaining setup, and how to reconcile the
payment with the seller's balance and our fee.

Check the result

The correct seller account ID is saved against each seller.
The payment is accounted for across the seller’s share, platform fee, and processing fee.
Settlement creates one seller transfer; the app does not send another manually.
Blocked capabilities or an unusable destination prevent a payout.
The app tracks payout status through delivery or failure.
Your team understands the platform’s responsibility for refunds and disputes.

Before going live, read Connect payouts for withdrawals and refunds and disputes.

Next steps

Build a SaaS platform, where the account sells instead of you
Payouts
Destination charges
Platform fees
Take Connect live

Start here

Use cases

Starter templates

Build with AI

Examples

Build a marketplace

How it fits together

What you’ll use

Before you start

Steps

What you built

Webhooks to handle

Edge cases

Go-live checklist

Build it with an AI assistant

Check the result

Next steps

​How it fits together

​What you’ll use

​Before you start

​Steps

​What you built

​Webhooks to handle

​Edge cases

​Go-live checklist

​Build it with an AI assistant

​Check the result

​Next steps

How it fits together

What you’ll use

Before you start

Steps

What you built

Webhooks to handle

Edge cases

Go-live checklist

Build it with an AI assistant

Check the result

Next steps