Connect quickstart

In this guide you’ll create an account, send it through onboarding, create a checkout that charges the account and takes your platform fee out of it, and read that fee back once the charge settles. By the end you’ll have run a full direct charge without moving real money.

Before you start

A sandbox API key (sk_sandbox_...). See Authentication.
The connect capability active on your account. See Become a platform.
A product to sell. See Products.
A webhook endpoint with event_source set to connect or all, so your platform receives an event that originates with the account. See Connect events.

Steps

Create the account

This account is going to be the merchant of record on a direct charge, so it needs a payment-accepting capability, and it will also be paid out, so it needs the recipient persona too. Name both 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": "ada@example.com",
    "display_name": "Ada Stores",
    "country": "NG",
    "entity_type": "individual",
    "configuration": {
      "merchant": {
        "capabilities": { "card_collection": { "requested": true } }
      },
      "recipient": {
        "capabilities": {
          "payouts": { "requested": true },
          "transfers": { "requested": true }
        }
      }
    }
  }'

{
  "id": "acct_3Wq8ZfT1yHnJ5sVe",
  "name": "Ada Stores",
  "country": "NG",
  "entity_type": "individual",
  "capabilities": {
    "card_collection": { "status": "active", "requested": true, "status_details": null },
    "payouts":         { "status": "active", "requested": true, "status_details": null },
    "transfers":       { "status": "active", "requested": true, "status_details": null }
  },
  "configuration": { "merchant": {}, "recipient": {} },
  "responsibilities": { "fees": { "collector": "bachs" } },
  "is_active": true,
  "created_at": "2026-08-12T09:00:00.000000+00:00"
}

The response carries exactly the three capabilities named above. Keep the id. Every step below uses it.

In sandbox, a capability whose persona is applied is granted active at creation, with no review. card_collection is requested against merchant, named in the same call, so it comes back active immediately, unlike in production, where it lands restricted until a reviewer enables it. See Testing.

card_collection accepts cards charged in USD. To accept Nigerian naira cards as well, request ngn_card_collection alongside it — it is a separate capability, so this NG merchant would name both under merchant.capabilities. Requesting one does not enable the other. See Capabilities.

Send it through onboarding

card_collection is already active, but a real account still needs its requirements satisfied to stay eligible, and this is the flow that collects them.

curl -X POST https://sandbox-api.bachs.io/v1/accounts/acct_3Wq8ZfT1yHnJ5sVe/account-links \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "onboarding",
    "refresh_url": "https://example.com/connect/refresh",
    "return_url": "https://example.com/connect/done"
  }'

{
  "id": "alnk_5e2c7b09a134f8c91a20",
  "object": "connected_account_link",
  "account": "acct_3Wq8ZfT1yHnJ5sVe",
  "type": "onboarding",
  "created": "2026-08-12T09:00:05.000Z",
  "expires_at": "2026-08-12T10:00:05.000Z",
  "url": "https://connect.bachs.io/setup/c/acct_3Wq8ZfT1yHnJ5sVe/al_QwErTy12ZxCvBn34UiOp56AsDf78GhJk90Lm",
  "previous_link_superseded": false
}

Open url and complete the flow. To build the interface yourself instead, see Onboard through the API.

Confirm the capability is active

Confirm the state at any point rather than waiting on it, since in sandbox card_collection is already active from step 1:

curl https://sandbox-api.bachs.io/v1/accounts/acct_3Wq8ZfT1yHnJ5sVe/capabilities \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..."

{
  "items": [
    { "name": "card_collection", "status": "active", "requested": true, "status_details": null },
    { "name": "payouts", "status": "active", "requested": false, "status_details": null }
  ]
}

In production, the same create call leaves card_collection restricted, and enabling it on review fires capability.updated:

capability.updated

{
  "type": "capability.updated",
  "organization_id": "acct_3Wq8ZfT1yHnJ5sVe",
  "data": {
    "account": "acct_3Wq8ZfT1yHnJ5sVe",
    "capability": "card_collection",
    "status": "active",
    "requested": true
  }
}

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: the account becomes the merchant of record, and the sale lands in its balance. 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": "9f3a71c4-e05b-4b2a-91b4-0e6c7d2a91b4",
  "status": "open",
  "source_type": "CHECKOUT_SESSION",
  "amount": "100000.00",
  "currency": "NGN",
  "checkout_url": "https://checkout.bachs.io/c/Xk7fQ2mNv4XbR9d",
  "platform_fee": "20000.00",
  "products": [
    {
      "product_id": "prod_8f2a71c4e05b",
      "quantity": 1,
      "unit_amount": "100000.00",
      "currency": "NGN",
      "price_type": "fixed",
      "line_total": "100000.00"
    }
  ]
}

Out of the 100000.00 NGN the customer pays, 20000.00 is your cut. The rest, minus Bachs’s processing fee, is the account’s. See Platform fees and Direct charges.

Send the customer to the checkout

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

Receive 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, not your platform. This is why the webhook endpoint you set up before starting needed event_source set to connect or all: with the default, account, this event never reaches you.

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": "9f3a71c4-e05b-4b2a-91b4-0e6c7d2a91b4",
    "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"
  }
}

Read your cut back

Your platform 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_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. charge ties it back to the checkout’s charge.

What happens next

You have run a direct charge end to end: an account that accepts money, and a platform fee that comes back to you. Going live is a key swap: the same calls against https://api.bachs.io with an sk_live_ key. See Take Connect live.

Get started

Core concepts

Reversals and risk

Onboard an account

Build with Connect

Go live

Connect quickstart

Before you start

Steps

What happens next

Next steps

​Before you start

​Steps

​What happens next

​Next steps

Before you start

Steps

What happens next

Next steps