Build a SaaS platform

Each business on your platform transacts with its own customers, who often do not know you exist. So the account is the merchant of record: the charge is its sale, the money lands in its balance, and your cut comes back to you. In this guide you’ll create an account that sells, take a payment as that account, and read your fee back. By the end you’ll have run a full direct charge without moving real money.

How it fits together

The sale belongs to the business, so the money lands in its balance. Your fee comes out of its proceeds and settles to you as its own record.

What you’ll use

Object	Its job in this build	Reference
Account	The business. It takes payments, holds the money and withdraws it.	Accounts
`X-Account-Id`	Makes a request act as the account, so the checkout is the business’s sale.	Acting as an account
Checkout session	The business’s checkout. `platform_fee` is your cut.	Direct charges
Platform fee	Your cut, as its own record once the charge settles.	Platform fees
Webhook endpoint	Tells you about your accounts’ payments and onboarding. 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 account, as a merchant

This account takes its own payments and gets paid out, so it needs both personas. Name merchant and recipient as keys in configuration, and name each capability it needs under the persona it belongs to.

curl -X POST https://sandbox-api.bachs.io/v1/accounts \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "studio@example.com",
    "display_name": "Bright Studio",
    "country": "NG",
    "entity_type": "individual",
    "configuration": {
      "merchant": {
        "capabilities": {
          "card_collection": { "requested": true },
          "bank_transfer": { "requested": true },
          "mobile_money": { "requested": true }
        }
      },
      "recipient": {
        "capabilities": {
          "payouts": { "requested": true },
          "transfers": { "requested": true }
        }
      }
    }
  }'

{
  "id": "acct_neoYPwWLKjICOBnZ",
  "name": "Bright Studio",
  "country": "NG",
  "entity_type": "individual",
  "capabilities": {
    "card_collection": { "status": "active", "requested": true },
    "bank_transfer":   { "status": "active", "requested": true },
    "mobile_money":    { "status": "active", "requested": true },
    "payouts":         { "status": "active", "requested": true },
    "transfers":       { "status": "active", "requested": true }
  },
  "configuration": { "merchant": {}, "recipient": {} },
  "balance_currencies": [],
  "is_active": true
}

Copy the id. Every step below uses it as the account id.The response lists exactly the five capabilities named above, one status per capability. In sandbox they are granted immediately; in live they start pending_review until a reviewer enables them. See Capabilities and Testing Connect.

Let it hold the currency it sells in

Holding a currency decides what the account settles in. A new account holds only USD. This walkthrough sells a subscription in NGN, so give the account NGN: its takings then stay in NGN instead of converting to USD on the way to the balance. Today holding the price currency is also required to create a recurring checkout at all (an unheld one is refused with BASE_CURRENCY_NOT_HELD_BY_ORG until renewals settle to USD like one-time charges do), so an account selling an NGN plan has to hold NGN first either way. Not every currency Bachs collects in can be held as a balance, so check Balance currencies before you build against one.

curl -X POST https://sandbox-api.bachs.io/v1/accounts/acct_neoYPwWLKjICOBnZ \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{ "balance_currencies": { "NGN": true } }'

{
  "id": "acct_neoYPwWLKjICOBnZ",
  "name": "Bright Studio",
  "balance_currencies": ["NGN"]
}

USD is always held, cannot be turned off, and does not appear in the list. See Accounts for the field, and Balance currencies for what you can ask for.

Skip this step and the checkout below is refused with BASE_CURRENCY_NOT_HELD_BY_ORG. It is the account’s own currencies that decide this, not yours.

Create the product as the account

The account is selling, so the product is the account’s. X-Account-Id is what makes a call act as the account rather than as you.

curl -X POST https://sandbox-api.bachs.io/v1/products \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "X-Account-Id: acct_neoYPwWLKjICOBnZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Studio session",
    "description": "A one-hour booking.",
    "price": { "currency": "NGN", "amount": "50000.00" }
  }'

{
  "id": "prod_be4d87e4f01a4570a98a",
  "organization_id": "acct_neoYPwWLKjICOBnZ",
  "name": "Studio session",
  "price": { "currency": "NGN", "price_type": "fixed", "amount": "50000.00" },
  "status": "active"
}

Copy the product id. Note organization_id: the product belongs to the account.

Create the checkout as the account

X-Account-Id, on its own, is what makes this a direct charge: the account becomes the merchant of record and the sale lands in its balance. platform_fee is your cut, taken out of its proceeds.

curl -X POST https://sandbox-api.bachs.io/v1/checkout-sessions \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "X-Account-Id: acct_neoYPwWLKjICOBnZ" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      { "product_id": "prod_be4d87e4f01a4570a98a", "quantity": 1 }
    ],
    "platform_fee": "10000.00",
    "customer": { "email": "buyer@example.com" },
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/cancel"
  }'

{
  "checkout_id": "chk_B1Pa8HgYyRNvyvht",
  "status": "open",
  "amount": "50000.00",
  "currency": "NGN",
  "platform_fee": "10000.00",
  "checkout_url": "https://sandbox-checkout.bachs.io/c/oudFvcBOWo5vBPM"
}

Copy the checkout_id and checkout_url.

This checkout is the account’s, not yours. Every later read of it needs X-Account-Id too. Without the header the answer is 404 Checkout not found, which reads as though the checkout was never created.

Send the customer to pay

In your integration the account’s customer pays on the page we host at checkout_url. 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

Read the checkout back until status is completed. Note the X-Account-Id: this is the account’s checkout.

curl https://sandbox-api.bachs.io/v1/checkout-sessions/chk_B1Pa8HgYyRNvyvht \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "X-Account-Id: acct_neoYPwWLKjICOBnZ"

{
  "checkout_id": "chk_B1Pa8HgYyRNvyvht",
  "status": "completed",
  "payment_status": "succeeded",
  "amount": "50000.00",
  "currency": "NGN",
  "platform_fee": "10000.00"
}

In your integration you would not poll for this. Subscribe to checkout.completed instead. A direct charge’s event originates with the account, so your webhook endpoint needs event_source set to connect or all to receive it. See Connect events.

Read your cut back

Your fee is not a transfer: it settles as its own record once the charge settles, never sooner. Read it from GET /v1/platform_fees:

curl "https://sandbox-api.bachs.io/v1/platform_fees?charge=ch_536484a789f84d58840e85ce1e8b1a84" \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..."

{
  "items": [
    {
      "id": "pf_dee4d8fea7834083a086",
      "charge": "ch_536484a789f84d58840e85ce1e8b1a84",
      "collected_from": "acct_neoYPwWLKjICOBnZ",
      "earned_by": "org_bd31b6b3037d404ebe116ec69d955ee3",
      "amount": "10000.00",
      "currency": "NGN",
      "amount_refunded": "0.00",
      "refunded": false,
      "created_at": "2026-08-12T20:13:31.238555+00:00"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false,
    "limit": 50,
    "offset": 0,
    "returned": 1,
    "total": 1
  }
}

collected_from is the account and earned_by is you, because the sale was theirs and the fee is yours. charge ties it back to the sale.

Read the account's balance

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

{
  "account_id": "acct_neoYPwWLKjICOBnZ",
  "balances": [
    { "currency": "NGN", "available_balance": "39850.00", "pending_balance": "0.00" },
    { "currency": "USD", "available_balance": "0.00",     "pending_balance": "0.00" }
  ]
}

The whole sale, accounted for:

	NGN
Customer paid	50000.00
The account keeps	39850.00
Your platform fee	10000.00
Our processing fee	150.00

The account bears our processing fee because it is the merchant of record. That is the default, and Processing fees covers moving it. Your 10000.00 arrives whole.

How this differs from a marketplace

The same two calls, with the parties swapped.

	This page	Marketplace
Merchant of record	The account	You
What makes it so	`X-Account-Id`	`transfer_data.destination`
Where the charge lands	The account’s balance	Yours
Which way the fee moves	Account to you, its own record at `/v1/platform_fees`	You to seller, a transfer with `kind: payout`
Who bears a refund or lost dispute	The account	You
Who pays our processing fee, by default	The account	You

If you are still choosing, see Choose your integration.

What happens next

The account 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. A refund or a lost dispute debits the account here, not you. That is the point of this shape, and the reason its onboarding is longer than a marketplace seller’s. See Refunds and Disputes.

Webhooks to handle

Create your endpoint with event_source set to connect or all, or it receives nothing from your accounts. An event from an account carries a top-level account field naming it.

Event	What it means	What your platform does
`account.updated`	An account’s onboarding state changed.	Read `requirements.currently_due` and ask the business for what is missing.
`capability.updated`	A capability on an account changed status.	Let the business take payments once its payment capabilities are `active`, and withdraw once `payouts` is.
`checkout.completed`	A customer paid the business.	Read the checkout back as the account, then update the business’s order.
`payout.paid`, `payout.failed`	The business’s withdrawal arrived or failed.	Show the business its payout status.

Your platform fee has no event of its own. Read it from /v1/platform_fees after the charge settles.

Edge cases

The business cannot take payments yet

A checkout as the account needs its payment capabilities active. In production, capabilities start restricted until a reviewer enables them, and a business that accepts payments owes more requirements than a marketplace seller. Wait for capability.updated. See Requirements.

A customer asks the business for a refund

The sale is the business’s, so a refund debits the account’s balance, not yours. See Refunds on Connect.

A customer disputes a payment

The account is liable. If it loses and its balance cannot cover the dispute, its balance goes negative and recovers from its future sales. See Disputes on Connect.

Who pays the processing fee

By default the account bears Bachs’s processing fee, because the sale is its own, and your platform fee arrives whole. See Processing fees to change this.

The business sells a subscription in a currency it does not hold

A recurring checkout needs the account to hold the price currency, as in the second step above. See Balance currencies.

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.
Businesses can sell only after their payment capabilities are active in production.
Every request that acts for a business sends its X-Account-Id, and every write sends an Idempotency-Key.
Businesses know that refunds and lost disputes debit their own balance.

Build it with an AI assistant

The Bachs skill covers Connect. Ask your assistant to build “a platform where each business sells as its own Bachs account, with a platform fee”, and point it at this page: https://docs.bachs.io/build/use-cases/saas-platform.md.

Start here

Use cases

Starter templates

Build with AI

Examples

Build a SaaS platform

How it fits together

What you’ll use

Before you start

Steps

How this differs from a marketplace

What happens next

Webhooks to handle

Edge cases

Go-live checklist

Build it with an AI assistant

Next steps

​How it fits together

​What you’ll use

​Before you start

​Steps

​How this differs from a marketplace

​What happens next

​Webhooks to handle

​Edge cases

​Go-live checklist

​Build it with an AI assistant

​Next steps

How it fits together

What you’ll use

Before you start

Steps

How this differs from a marketplace

What happens next

Webhooks to handle

Edge cases

Go-live checklist

Build it with an AI assistant

Next steps