# Welcome to Southbill

Take card, wallet, bank and BNPL payments with one API — no PSP account required.

# Welcome to Southbill

Southbill is a payments platform. You create a merchant account, we handle the PSP relationships (cards, wallets, SEPA, Klarna, iDEAL, and more), and you get **one REST API** to charge customers, run subscriptions, issue refunds and receive payouts to your bank.

This section gets you from zero to your first live payment.

## What you can do with the API

| Capability | Endpoint | Docs |
|---|---|---|
| One-off payment | `POST /v1/checkout/sessions` | [Checkout Sessions](/docs/api/checkout-sessions) |
| Recurring billing | `POST /v1/subscriptions` | [Subscriptions](/docs/api/subscriptions) |
| Invoicing | Dashboard (`/dashboard/invoices/new`) | [Invoices](/docs/api/invoices) |
| Catalog | `POST /v1/products` · `POST /v1/products/{id}/prices` | [Products](/docs/api/products) |
| Refunds | `POST /v1/refunds` | [Refunds](/docs/api/refunds) |
| Realtime updates | Webhooks | [How webhooks work](/docs/webhooks/overview) |

Everything is JSON over HTTPS. Base URL: **`https://api.southbill.com/v1`**.

## Quickstart (5 minutes)

**1. Onboard your merchant account.** Sign in to the [dashboard](https://southbill.com/dashboard), complete the 15-step onboarding, and wait for approval. You must be `active` before live keys work.

**2. Grab an API key.** Dashboard → **Developers** → **API keys**. You'll get two:

- `sk_test_…` — sandbox, no real money, no payout.
- `sk_live_…` — real money.

Treat these like passwords. See [API security best practices](/docs/getting-started/security).

**3. Make your first charge.**

```bash
curl -X POST https://api.southbill.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_0001" \
  -d '{
    "amount": 2500,
    "currency": "eur",
    "customer_name":  "Jane Doe",
    "customer_email": "jane@example.com",
    "success_url": "https://example.com/thanks",
    "cancel_url":  "https://example.com/cart"
  }'
```

Redirect the buyer to the returned `checkout_url`. Use test card `4242 4242 4242 4242` with any future expiry and any CVC.

**4. Receive the webhook.** Add an endpoint at Dashboard → **Developers → Webhooks** and listen for `checkout.session.completed`. Always verify the signature — [instructions here](/docs/webhooks/signature-verification).

## Core concepts

- **Merchant account.** Your business on southbill. Owns your keys, products, transactions, payouts.
- **Session / Subscription / Invoice.** Three ways to collect money. Pick by use case.
- **`client_secret`.** Short-lived token used by the browser to confirm a payment. Never trust it as proof of payment — [details](/docs/api/client-secret).
- **Fees.** Per-plan, per-method, calculated in EUR and deducted per transaction. See [Fees](/docs/getting-started/fees-and-currency).
- **Payouts.** Automatic, on your configured schedule (daily/weekly), to your verified bank account.

## Environments

| Mode | Keys | Money | Payouts |
|---|---|---|---|
| **Test** | `sk_test_…` / `pk_test_…` | No | No |
| **Live** | `sk_live_…` / `pk_live_…` | Yes | Yes |

Both modes share the same base URL and endpoints. The key alone decides which environment you hit.

Test and live responses use the **identical object shape** — amounts are integers in the smallest currency unit, currencies are lowercase ISO codes, and every object carries `livemode` (`false` in test).

## Idempotency, errors, rate limits

- Send `Idempotency-Key: <your-key>` on every mutating request. Safe retries, no duplicate charges.
- Errors follow a stable shape: `{ "error": { "type": "…", "message": "…", "param": "…" } }`. See [Error reference](/docs/api/errors).
- Default limits per key, in fixed one-minute windows: **300 req/min** for reads, **120 req/min** for checkout creates, **60 req/min** for other writes. `429 rate_limited` includes a `Retry-After` header.

## Where to next

- [API keys & authentication](/docs/getting-started/api-keys)
- [Checkout Sessions](/docs/api/checkout-sessions) — the fastest way to accept a payment
- [How webhooks work](/docs/webhooks/overview)
- [Hosted Checkout](/docs/integrations/hosted-checkout) — no backend required