southbill (Python)

Official Python SDK for the Southbill API. No third-party dependencies — standard library only. Requires Python 3.8+.

pip install southbill

Quick start

from southbill import Southbill

southbill = Southbill()  # or Southbill("sk_live_...")

session = southbill.checkout.sessions.create(
    amount=4900,
    currency="EUR",
    customer_email="ada@acme.com",
    success_url="https://acme.com/thanks",
)

print(session["checkout_url"])

The Merchant API accepts live keys only (sk_live_... for server calls, pk_live_... for publishable/browser use). Legacy sk_test_... keys are rejected with 401 authentication_error — sandbox testing happens on the Developer Platform, not through merchant keys.

Errors carry a machine-readable error.type plus an optional error.code:

Note: the App API (OAuth apps) uses not_found as an error type, while the Merchant API returns invalid_request with code: "resource_missing" instead.

Resources

Payouts, bank details, KYC and API-key management stay merchant-controlled in the dashboard and are intentionally not part of the API surface.

Installment payments (invoices)

installments = southbill.invoices.list_installments("inv_123")
payments = southbill.invoices.list_payments("inv_123")

Webhook endpoints (API-managed)

endpoint = southbill.webhook_endpoints.create(
    url="https://acme.com/webhooks/southbill",
    enabled_events=["invoice.paid", "payment.succeeded"],
)
southbill.webhook_endpoints.rotate_secret(endpoint["id"])  # old secret stays valid 24 h
deliveries = southbill.webhook_endpoints.list_deliveries(endpoint["id"])

Balance & transactions

balance = southbill.balance.retrieve()
for tx in southbill.balance.transactions.auto_paging_iter(type="charge"):
    print(tx["bt_id"], tx["net"], tx["currency"])

Idempotency

Every POST sends an Idempotency-Key header (random UUID). Pass your own for safe retries across processes:

southbill.invoices.create(idempotency_key=f"inv-{order_id}", customer="cus_123")

Pagination

for invoice in southbill.invoices.auto_paging_iter(status="open"):
    print(invoice["id"])

Errors

Network errors, 429 and 5xx are retried twice with exponential backoff. Everything else raises SouthbillError:

from southbill import SouthbillError

try:
    southbill.refunds.create(payment="pi_123", amount=500)
except SouthbillError as error:
    print(error.status, error.type, error.param, error.request_id)

Webhooks

Verify the raw request body — never a re-serialized object.

from flask import Flask, request
from southbill import construct_event, SouthbillSignatureError

app = Flask(__name__)

@app.post("/webhooks/southbill")
def webhook():
    try:
        event = construct_event(
            payload=request.get_data(),
            signature=request.headers.get("southbill-signature", ""),
            secret=os.environ["SOUTHBILL_WEBHOOK_SECRET"],
        )
    except SouthbillSignatureError:
        return "", 400

    if event["type"] == "invoice.paid":
        ...  # handle it

    return "", 200

Signature scheme: Southbill-Signature: t=<unix seconds>,v1=<hex> where the hex digest is HMAC-SHA256(secret, "<timestamp>.<raw body>"). Default tolerance 300s.

License

MIT