Platform fees

What a platform fee is

A platform fee is your cut of a sale, taken from the account’s proceeds. It comes out of what the account would otherwise keep, not out of Bachs’s processing fee. Those are two different amounts leaving the charge for two different reasons, and conflating them will get your accounting wrong.

Setting one

Send platform_fee on create-checkout, as an amount in the sale’s base currency, the currency the price itself is set in:

curl https://sandbox-api.bachs.io/v1/checkout-sessions \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -H "X-Account-Id: acct_3Wq8ZfT1yHnJ5sVe" \
  -d '{
    "product_cart": [
      {
        "product_id": "prod_8f2a71c4e05b",
        "quantity": 1,
        "pricing": { "price_type": "fixed", "amount": "100000.00" }
      }
    ],
    "platform_fee": "20000.00",
    "customer": { "email": "jane@example.com" },
    "success_url": "https://example.com/thank-you",
    "cancel_url": "https://example.com/checkout"
  }'

platform_fee is always an amount, never a percentage. A percentage is pricing policy you already own somewhere; restating it on every checkout request would give it a second place to drift out of sync with the first. Send the amount you’ve already computed, in the product’s base currency, even if the customer ends up paying in a different one. See Currency below. platform_fee is available on both create-checkout surfaces: acting as the account with X-Account-Id (a direct charge) and naming the account in transfer_data.destination (a destination charge).

Two ways to state the split

platform_fee says what you keep. There’s a second field, transfer_data.amount, that says the opposite: what the account receives. Send exactly one. Sending both, or neither on a destination charge, is rejected before the customer pays.

Field	States	Where
`platform_fee`	What your platform keeps	Top level, beside `transfer_data`
`transfer_data.amount`	What the account receives	Nested under `transfer_data`, alongside `destination`

Both are amounts in the sale’s base currency. Sending both is a VALIDATION_ERROR (400): they are two descriptions of the same split, and nothing about the request says which one should win. The two forms are not interchangeable bookkeeping. Which one you send changes what the account is paid and what you can see afterward:

Lead with platform_fee (fee-first). You state your cut; the account gets the rest. This is a PlatformFee record, readable at GET /v1/platform_fees. On a destination charge, the transfer that pays the account out carries the sale’s full gross amount alongside that record, so the account’s own read of the transfer shows the sale and your cut side by side.
Lead with transfer_data.amount (share-first). You state what the account gets, and your platform keeps the rest of the sale. No PlatformFee record is created, because you never stated a cut, only a payout. The transfer that pays the account carries exactly that amount, its net, and nothing else. Read Who pays the processing fee before you set this close to the full sale: the amount you name is what the account receives in almost every case, but not in the one where the sale cannot fund our fee.

Pick fee-first when you need a queryable record of what you earned on every sale. Pick share-first when you only care that the account is paid a fixed amount and you are willing to let your own take float with it. On a direct charge, use platform_fee only. There is no seller balance for transfer_data.amount to name a share of: the account is the merchant, and what it keeps is the gross minus your fee.

What bounds it

All of these return the standard error envelope with status 400.

Rule	Error
`platform_fee` must be greater than zero.	`INVALID_PLATFORM_FEE`
`platform_fee` must be less than the gross amount, so the account is left a share of the sale.	`INVALID_PLATFORM_FEE`
`transfer_data.amount` must be greater than zero.	`INVALID_PLATFORM_FEE`
`transfer_data.amount` must be less than the gross amount, so your platform keeps a share of the sale.	`INVALID_PLATFORM_FEE`
`platform_fee` and `transfer_data.amount` cannot both be sent.	`VALIDATION_ERROR`
A destination charge requires one of `platform_fee` or `transfer_data.amount`. With neither, there is nothing to say what the account is owed.	`INVALID_PLATFORM_FEE`
`X-Account-Id` and `transfer_data` cannot both be sent. The header alone makes the sale the account’s; naming a destination makes it yours, and a request cannot be both at once.	`CONTRADICTORY_CHARGE_TYPE`
Either term must be at least one minor unit of the sale’s base currency. `"0.001"` on a USD sale rounds to nothing, so it is refused rather than stored as a fee of zero.	`INVALID_PLATFORM_FEE`
`transfer_data` accepts `destination` and `amount` and nothing else. A key it does not recognise is refused rather than ignored, so a misspelling cannot look like a split you never sent.	`VALIDATION_ERROR`
`platform_fee` inside `transfer_data`. It is a top-level field; the error says so.	`VALIDATION_ERROR`

Currency

platform_fee and transfer_data.amount are always base-currency amounts, the currency the sale was priced in. The split is struck in that same currency, even when the customer pays in something else and the charge converts on its way to settlement. A platform fee on a converting charge settles correctly: it doesn’t need the account to hold the payment currency, only its own base currency. Only USD is held by default. Any other currency has to be enabled on an account before it can receive money in it. See Balances.

Precision

Both terms are held to the precision of the currency they are stated in: two decimal places on USD or NGN, six on a stablecoin rail. A value carrying more than that is rounded half-up to the nearest minor unit when the checkout is created, and the rounded value is what the response echoes, what settles, and what the PlatformFee record keeps. So a percentage you compute yourself is worth rounding before you send it. platform_fee: "33.337" on a USD sale is stored and paid as "33.34", and the account’s share is the rest of the sale after that rounded figure. A value that rounds to zero is refused rather than treated as a fee of nothing.

Who pays the processing fee

Bachs charges a processing fee on every sale. On a destination charge the sale is yours, so that fee is yours to pay, and it is taken in this order.

Your cut of the sale. Whatever you kept, whether you stated it as platform_fee or left it as the remainder after a transfer_data.amount.
Your platform’s available balance. If your cut on this sale is too small to cover the fee, the rest comes out of your balance: money from your other sales, not this one. Your balance has to cover the whole remainder for this step to apply. If it cannot cover all of it, none of it is taken from there.
The account’s share. Only when your cut and your balance together cannot pay the fee does the remainder come out of what the account receives.

The third step is the one to plan around, because it is the only case where an account is paid less than the split you described. If you named transfer_data.amount, that is also the only case where the account receives less than the amount you named.

When the customer bears the processing fee, none of this applies. The customer paid the fee on top of the price, so it is already funded and neither your cut nor the account’s share is touched by it.

When you receive it

On a direct charge, your cut becomes available on the account’s settlement schedule, never sooner. Settlement is what turns a charge into money either party can actually move; crediting your fee before that point would let you spend money that hasn’t cleared yet. On a destination charge, whatever your platform keeps is never transferred at all: it is already part of your platform’s own balance when the charge settles, since the charge was yours to begin with. Only the account’s share moves, as a transfer to the account.

Reading it back

The checkout and payment objects echo back whichever term you sent: platform_fee on a fee-first split, destination_amount on a share-first one. The one you didn’t send is null.

Both fields are null, not "0.00", when the sale carries no split at all. Most charges carry neither. The fields are always on the wire; test whether the value is null rather than checking whether the field exists, and don’t assume a typed client that expects a string will accept a null the same way it accepts a zero one.

A fee-first split also mints a platform fee record: a standalone object naming the charge it came from, the amount, and both parties. This is the queryable, permanent record of your cut. A share-first split never mints one, since you never stated a cut, only a payout. There, read what the account was paid straight off the transfer or the payment’s destination_amount. Get one by id, or list every fee your platform was a party to:

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

{
  "items": [
    {
      "id": "pf_8c1e04a7b93f2d6540ab1234",
      "charge": "ch_2f8a71c4e05b",
      "collected_from": "acct_7KpQ2mNv4XbR9dLc",
      "earned_by": "acct_3Wq8ZfT1yHnJ5sVe",
      "amount": "20000.00",
      "currency": "NGN",
      "amount_refunded": "0.00",
      "refunded": false,
      "created_at": "2026-08-12T10:31:00.000Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false,
    "limit": 50,
    "offset": 0,
    "returned": 1,
    "total": 1
  }
}

GET /v1/platform_fees · GET /v1/platform_fees/{fee_id} · scope transfers:read collected_from is the account the cut came out of, on either shape. earned_by is your platform. Both the account and your platform can read a fee they were party to; filter the list with charge to see the one fee tied to a specific sale. This replaces reading a direct charge’s fee as a kind=platform_fee transfer. That transfer kind is retired: platform_fee is not a movement between two balances, it is money your platform keeps, and GET /v1/transfers?kind=platform_fee now returns 400.

What it does not do

A platform fee is not reversed on a refund. The refund debits whichever party owns the charge: the account on a direct charge, your platform on a destination charge. Bachs’s own takes do not reverse either. On a direct charge, work out the consequence before an account asks you about it: the account is debited the full amount the customer paid, but it only ever received gross minus your platform fee. On a 20% platform fee, that leaves the account 20% short on every refunded sale. On a destination charge, the refund debits your platform instead, and your platform keeps its cut. The payout transfer already sent to the account is not reversed: your platform bears the full refund, and the account keeps the share it received. See Refunds for the fuller treatment.

Get started

Core concepts

Reversals and risk

Onboard an account

Build with Connect

Go live

Platform fees

What a platform fee is

Setting one

Two ways to state the split

What bounds it

Currency

Precision

Who pays the processing fee

When you receive it

Reading it back

What it does not do

Next steps

​What a platform fee is

​Setting one

​Two ways to state the split

​What bounds it

​Currency

​Precision

​Who pays the processing fee

​When you receive it

​Reading it back

​What it does not do

​Next steps

What a platform fee is

Setting one

Two ways to state the split

What bounds it

Currency

Precision

Who pays the processing fee

When you receive it

Reading it back

What it does not do

Next steps