Destination charges

What you’ll build

A checkout that belongs to your platform, with an account named as the seller. Your platform is the merchant of record, the sale lands in your balance, and the seller’s share moves down to the account as part of settling the charge. By the end you’ll have created the checkout as your platform, sent the customer to it, confirmed the payment with a webhook, and read the seller’s payout back as a transfer, along with your own cut when you stated the split that way.

When to use it

Customers transact with your platform, not with the account, for the goods or services the account provides.
Each charge names exactly one account as the seller.
Your platform is the merchant of record.

The flow

A customer pays the platform, which transfers a share to the account and pays Bachs its processing fee.

The customer pays your platform directly. Your platform settles Bachs’s processing fee out of that one charge, and the split with the account is settled the way you stated it: either your platform names its own cut, or it names what the account receives.

Create the checkout as your platform

Do not send X-Account-Id. Name the account in transfer_data.destination; its presence, on its own, is what makes this a destination charge. State the split with exactly one of two terms: platform_fee, what your platform keeps, or transfer_data.amount, what the account receives. Sending both is rejected, and sending neither is too, since the account’s share cannot be computed without one. Whichever you send, it is an amount in the base currency of the sale, not necessarily the currency the customer pays in.

platform_fee
transfer_data.amount

Name your platform’s cut. The account receives whatever is left.

curl 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_8f2a71c4e05b",
        "quantity": 1,
        "pricing": { "price_type": "fixed", "amount": "100000.00" }
      }
    ],
    "platform_fee": "20000.00",
    "transfer_data": { "destination": "acct_3Wq8ZfT1yHnJ5sVe" },
    "customer": { "email": "jane@example.com" },
    "success_url": "https://example.com/thank-you",
    "cancel_url": "https://example.com/checkout"
  }'

{
  "checkout_id": "chk_c48e2a917d3f",
  "status": "open",
  "source_type": "CHECKOUT_SESSION",
  "amount": "100000.00",
  "currency": "NGN",
  "checkout_url": "https://checkout.bachs.io/c/Fq7mZv2XpN9kRtB",
  "platform_fee": "20000.00",
  "products": [
    {
      "product_id": "prod_8f2a71c4e05b",
      "quantity": 1,
      "unit_amount": "100000.00",
      "currency": "NGN",
      "price_type": "fixed",
      "line_total": "100000.00"
    }
  ]
}

Name what the account receives instead. Your platform keeps whatever is left, and absorbs any variance in the total.

curl 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_8f2a71c4e05b",
        "quantity": 1,
        "pricing": { "price_type": "fixed", "amount": "100000.00" }
      }
    ],
    "transfer_data": { "destination": "acct_3Wq8ZfT1yHnJ5sVe", "amount": "80000.00" },
    "customer": { "email": "jane@example.com" },
    "success_url": "https://example.com/thank-you",
    "cancel_url": "https://example.com/checkout"
  }'

{
  "checkout_id": "chk_c48e2a917d3f",
  "status": "open",
  "source_type": "CHECKOUT_SESSION",
  "amount": "100000.00",
  "currency": "NGN",
  "checkout_url": "https://checkout.bachs.io/c/Fq7mZv2XpN9kRtB",
  "platform_fee": null,
  "products": [
    {
      "product_id": "prod_8f2a71c4e05b",
      "quantity": 1,
      "unit_amount": "100000.00",
      "currency": "NGN",
      "price_type": "fixed",
      "line_total": "100000.00"
    }
  ]
}

platform_fee carries the amount because there is one; a checkout with none returns "platform_fee": null rather than "0.00". The key is always present regardless of which term you sent. transfer_data is never echoed back, on either tab.

Send the customer to the checkout

Redirect the customer to checkout_url. Bachs hosts the payment page and collects the charge against your platform.

Confirm with the webhook

Bachs sends checkout.completed once the customer finishes. Check data.payment_status: paid means a charge was made.

Event

{
  "id": "evt_7f6e5d4c3b2a1908",
  "type": "checkout.completed",
  "created_at": "2026-08-12T09:15:00.000000+00:00",
  "organization_id": "acct_7KpQ2mNv4XbR9dLc",
  "data": {
    "checkout_id": "chk_c48e2a917d3f",
    "status": "completed",
    "mode": "payment",
    "payment_status": "paid",
    "amount": "100000.00",
    "currency": "NGN",
    "charge": {
      "id": "ch_2f8a71c4e05b",
      "amount": "100000.00",
      "currency": "NGN",
      "status": "succeeded"
    },
    "completed_at": "2026-08-12T09:15:00.000000+00:00"
  }
}

organization_id is your platform: it is the party whose checkout completed, so it is also the event’s origin. See checkout.completed for the full payload.

Read the seller's payout back

The account’s share settles as a transfer from your platform. List it with kind=payout. What it carries, and whether your platform’s cut appears anywhere else, depends on which term you used to state the split.

platform_fee
transfer_data.amount

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

{
  "items": [
    {
      "id": "tr_8c1e04a7b93f2d6540ab",
      "source": "acct_7KpQ2mNv4XbR9dLc",
      "destination": "acct_3Wq8ZfT1yHnJ5sVe",
      "amount": "100000.00",
      "currency": "NGN",
      "status": "paid",
      "metadata": {},
      "kind": "payout",
      "source_charge_id": "ch_2f8a71c4e05b",
      "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
  }
}

The transfer carries the full "100000.00" the customer paid, not the "80000.00" left after your fee. Your platform’s cut is not on this record: it settles separately, as its own record.

Read it from GET /v1/platform_fees:

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

{
  "items": [
    {
      "id": "pf_9c2e04a7b93f2d654012",
      "charge": "ch_2f8a71c4e05b",
      "collected_from": "acct_3Wq8ZfT1yHnJ5sVe",
      "earned_by": "acct_7KpQ2mNv4XbR9dLc",
      "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
  }
}

collected_from is the account whose sale funded the fee, and earned_by is your platform. The transfer’s "100000.00" minus this fee’s "20000.00" is what actually reaches the account. See Platform fees.

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

{
  "items": [
    {
      "id": "tr_8c1e04a7b93f2d6540ab",
      "source": "acct_7KpQ2mNv4XbR9dLc",
      "destination": "acct_3Wq8ZfT1yHnJ5sVe",
      "amount": "80000.00",
      "currency": "NGN",
      "status": "paid",
      "metadata": {},
      "kind": "payout",
      "source_charge_id": "ch_2f8a71c4e05b",
      "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
  }
}

The transfer carries exactly the "80000.00" you fixed. Your platform keeps the remaining "20000.00", but no record of it exists at GET /v1/platform_fees: you never named a fee, so none is minted.

status is paid once settlement has posted the movement, and pending before it has. source_charge_id ties the transfer back to the checkout’s charge. See Transfers.

With this shape

The charge lands in your platform’s balance, not the account’s.
One of platform_fee or transfer_data.amount is required. platform_fee fixes what your platform keeps; transfer_data.amount fixes what the account receives.
With platform_fee, the account’s payout carries the sale’s gross, and your platform’s cut settles separately, readable at Platform fees. With transfer_data.amount, the payout carries only the account’s fixed share, and your platform mints no fee record for the rest.
A refund debits your platform’s balance for the full amount the customer paid. 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.
A lost dispute drains your platform’s available balance, then its pending balance. Any amount still owed drives the available balance negative: that negative balance is the debt, and it heals as your platform’s own future settlement credits land. A dispute also debits a flat dispute fee when it opens, whether it is later won or lost. See Disputes.
Your platform needs the capability for every payment method it plans to accept, active before a customer can pay it that way: card_collection, ngn_card_collection, bank_transfer, mobile_money, crypto. The named account is checked only for ownership and active status, not for the capability. See Capabilities.
The account needs payouts active to withdraw its share once it settles.

Errors

Destination-charge errors return the standard error envelope.

Cause	Resolution
`transfer_data.destination` was sent with neither `platform_fee` nor `transfer_data.amount` set (`INVALID_PLATFORM_FEE`, 400). Without one of them, the split between your platform and the account is undefined.	Send `platform_fee` or `transfer_data.amount`, whichever term you want to fix.
`platform_fee` and `transfer_data.amount` were both sent on the same request. They are two ways to state the same split, and only one may be present.	Send only one of the two fields.
`platform_fee` or `transfer_data.amount` is not less than the gross amount (`INVALID_PLATFORM_FEE`, 400).	Lower whichever one you sent, so the other side of the split is left with something.
`X-Account-Id` and `transfer_data` were sent on the same request (`CONTRADICTORY_CHARGE_TYPE`, 400). The header alone makes the sale the account’s; naming a destination makes it yours, and a request cannot be both.	Send only `transfer_data` for a destination charge. Drop the header entirely, or drop `transfer_data` and use Direct charges instead.
Your platform has not been granted the capability for a payment method a customer tries to use (`PAYMENT_METHOD_NOT_ENABLED`, 400). The check runs against your platform, since the sale is your platform’s; the account is not checked. This is resolved when the method is chosen, not at checkout creation, so it can surface after the customer reaches the hosted page rather than on your `curl` call.	Request and activate the capability for that method on your platform before offering it. See Capabilities.

A charge priced in a currency different from the one it settles in still splits and settles: your platform’s cut and the account’s share are computed in the currency the sale was priced in. See Platform fees.

Get started

Core concepts

Reversals and risk

Onboard an account

Build with Connect

Go live

Destination charges

What you’ll build

When to use it

The flow

With this shape

Errors

Next steps

​What you’ll build

​When to use it

​The flow

​With this shape

​Errors

​Next steps

What you’ll build

When to use it

The flow

With this shape

Errors

Next steps