Direct charges

What you’ll build

A checkout that belongs to an account. The account is the merchant of record, the sale lands in its balance, and your platform fee moves up to you as part of settling the charge. By the end you’ll have created the checkout as the account, sent the customer to it, confirmed the payment with a webhook, and read your cut back.

When to use it

The account transacts with its own customers, not yours.
The customer may never need to know your platform exists.
Each charge belongs to exactly one account.

The flow

A customer pays an account, which pays the platform its fee and Bachs its processing fee.

The customer pays the account directly. The account settles Bachs’s processing fee and your platform fee out of that one charge; the remainder is the account’s proceeds.

Create the checkout as the account

Send X-Account-Id with the account’s id. Its presence, on its own, is what makes this a direct charge. Add platform_fee for your cut, in the base currency of the sale, taken from the account’s proceeds.

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"
  }'

{
  "checkout_id": "chk_9f3a71c4e05b",
  "status": "open",
  "source_type": "CHECKOUT_SESSION",
  "amount": "100000.00",
  "currency": "NGN",
  "checkout_url": "https://checkout.bachs.io/c/Jd5nQx8VmT3yLcR",
  "platform_fee": "20000.00",
  "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.

Send the customer to the checkout

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

Confirm with the webhook

Bachs sends checkout.completed once the customer finishes. Check data.payment_status: paid means a charge was made.A direct charge’s event originates with the account. Your platform receives it only on an endpoint with event_source set to connect or all; the default is account. See Connect events.

Event

{
  "id": "evt_7f6e5d4c3b2a1908",
  "type": "checkout.completed",
  "created_at": "2026-08-12T09:15:00.000000+00:00",
  "organization_id": "acct_3Wq8ZfT1yHnJ5sVe",
  "account": "acct_3Wq8ZfT1yHnJ5sVe",
  "data": {
    "checkout_id": "chk_9f3a71c4e05b",
    "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"
  }
}

Use account to attribute the event to the account that generated it; it is the field added specifically for that. See checkout.completed for the full payload.

Read your cut back

Your platform fee is not a transfer: it settles 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. amount and currency are the fee as struck: the currency the checkout was created in, before any conversion. See Platform fees.

With this shape

The charge lands in the account’s balance, not yours.
Your platform fee moves to your balance on the account’s settlement schedule, never sooner. See Platform fees.
A refund debits the account’s balance.
A lost dispute drains the account’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 the account’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.
The account 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. See Capabilities.

Errors

Direct-charge errors return the standard error envelope.

Cause	Resolution
`platform_fee` is not less than the gross amount (`INVALID_PLATFORM_FEE`, 400).	Lower `platform_fee` so it leaves the account something to be charged against.
`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 the header for a direct charge. Drop `transfer_data` entirely, or drop the header and use Destination charges instead.
The account has not been granted the capability for a payment method a customer tries to use (`PAYMENT_METHOD_NOT_ENABLED`, 400). 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 the account before offering it. See Capabilities.

A charge priced in a currency different from the one it settles in still settles: your platform’s cut is 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

Direct 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