bachs-io — Python SDK for the Bachs API

Production-grade Python SDK for the Bachs payments & billing platform — the payments stack for African internet businesses. Define products, run hosted checkouts, collect payments in customers' local currencies, manage subscriptions and trials, issue refunds, respond to disputes, convert balances, withdraw funds, configure webhooks, and run a Connect-style platform with connected accounts, transfers, and split payments.

Generated from the official Bachs OpenAPI spec (v1.0.0, 96 operations).

Installation

pip install bachs-io

Python 3.9+ required. Depends on httpx and pydantic>=2.

Quickstart

import bachs

client = bachs.BachsClient(api_key="sk_sandbox_...")

# Product-based hosted checkout
session = client.checkouts.create_checkout_session(
    customer={"email": "jane@example.com", "name": "Jane Doe"},
    product_cart=[{"product_id": "prod_abc", "quantity": 1}],
    success_url="https://shop.example.com/success",
)
print(session.checkout_url)

# Retrieve a payment
payment = client.payments.get_payment_detail("pay_123")

client.close()

Authentication & environments

Every request is authenticated with Authorization: Bearer sk_....

• sk_sandbox_... keys automatically target https://sandbox-api.bachs.io
• sk_live_... keys automatically target https://api.bachs.io
• Override with base_url=... (useful for mocking/staging)

You can also set the BACHS_API_KEY environment variable and omit api_key.

The API surface

Methods are grouped into typed resources on the client:

Every method is fully typed — parameters map 1:1 to the API request body/query, and every response is validated into a typed model (see bachs.models, also exported from the package root). Unknown fields in API responses are preserved rather than dropped, so the SDK tolerates additive API changes.

Conventions

• Money is always a decimal string (e.g. "29.00") at the currency's precision — the SDK never converts between units.
• Timestamps are ISO 8601 UTC strings.
• IDs (cust_, prod_, sub_, chk_, evt_, ...) are opaque strings.

Sending null to clear a field

Request models are serialized with None fields omitted. If you need to send an explicit null (e.g. clearing billing_address on update_customer), pass an empty representation for that field after reviewing the API docs for the endpoint's accepted values.

Pagination

List endpoints return a typed response carrying items (or items + a pagination block). Use the limit/offset (or cursor) parameters and read pagination.next_cursor / pagination.has_more to walk pages:

page = client.payments.list_payments(limit=100)
while True:
    for payment in page.items:
        ...
    if not page.pagination.has_more:
        break
    page = client.payments.list_payments(limit=100, offset=page.pagination.offset + page.pagination.returned)

Error handling

Every failure is raised as a subclass of bachs.BachsError:

try:
    client.refunds.create_refund(charge_id="pay_1", reference="ref_1")
except bachs.NotFoundError as exc:
    print(exc.error_code, exc.detail, exc.doc_url)
except bachs.RateLimitError as exc:
    print(exc.retry_after)  # seconds, from Retry-After
except bachs.ApiServerError as exc:
    pass  # safe to retry

Errors carry status_code, error_code, detail, doc_url, and errors (field-level validation details on 400).

Idempotency

All mutating requests accept an idempotency_key= argument that is sent as the Idempotency-Key header. Reuse the same key across retries to avoid duplicate creates.

Retries

429 and 5xx responses are retried automatically (up to max_retries=2, with exponential backoff and Retry-After honoured for rate limits). Configure via BachsClient(max_retries=..., retry_on_429=...).

Webhook verification

Webhooks are the source of truth for fulfilment. Verify every delivery with the endpoint's signing secret:

from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

@app.post("/webhooks")
async def receive(request: Request):
    raw = await request.body()
    try:
        event = bachs.construct_event(
            raw,
            request.headers.get("X-Bachs-Signature", ""),
            "whsec_...",
            timestamp_header=request.headers.get("X-Bachs-Timestamp"),
        )
    except bachs.SignatureVerificationError:
        raise HTTPException(400, "Bad signature")
    if event.event_type == "collection.succeeded":
        ...  # fulfil the order
    return {"status": "ok"}

verify_header returns a bool; construct_event parses and validates in one step. generate_signature is provided for testing.

Async

AsyncBachsClient mirrors the sync client:

async with bachs.AsyncBachsClient(api_key="sk_sandbox_...") as client:
    session = await client.checkouts.create_checkout_session(
        customer={"email": "jane@example.com", "name": "Jane Doe"},
        product_cart=[{"product_id": "prod_abc"}],
    )

Connect & acting on behalf of accounts

Endpoints that support X-Connected-Account-ID (checkout settings, transfers) expose a connected_account_id= parameter:

client.organizations.get_checkout_settings(connected_account_id="org_ca")
client.transfers.create_transfer(
    destination="org_ca", amount="7000.00", currency="NGN",
    connected_account_id="org_ca",
)

Uploads

Upload endpoints accept a file path, bytes, a file-like object, or an httpx (filename, content, content_type) tuple:

upload = client.uploads.create_upload(file="./cover.jpg", scope="product-media")
client.products.create_product(name="Pro", price={"currency": "USD", "amount": "29.00"},
                               media=[upload.upload_id])

Development

python -m venv .venv && .venv/bin/pip install -e .
.venv/bin/python -m pytest

The typed models and resource clients are generated from the Bachs OpenAPI spec (docs.bachs.io/docs/openapi/openapi.json) and checked in under bachs/_models.py, bachs/_resources.py, and bachs/_async_resources.py.