# Web SDK (southbill.js)

Drop-in JavaScript library — like Stripe.js. Redirect customers to hosted checkout from any website.


## Overview

`southbill.js` is a lightweight (~5 KB) browser library. You load it from our CDN, initialise it with a **Publishable Key (`pk_`)**, and call `.checkout()` to redirect the customer to the hosted checkout on `payments.southbill.com`.

No server code required. Works with plain HTML, React, Vue, Svelte, or any framework.

## 1. Create a Publishable Key

Go to **Dashboard → Developers**, click **New API key**, choose **Publishable (`pk_`)**, and whitelist the domains that are allowed to use it (e.g. `mystore.com, *.mystore.com, localhost`).

Publishable keys are safe to expose in your frontend — they can only start checkouts for prices that already exist in your catalogue.

## 2. Add the script

```html
<script src="https://payments.southbill.com/southbill.js"></script>
```

## 3. Start a checkout

```html
<button id="buy">Pay 25.00 EUR</button>
<script>
  document.getElementById('buy').addEventListener('click', () => {
    southbill('pk_live_XXX').checkout({
      line_items: [{ price: 'price_XXXXXXXX', quantity: 1 }],
      customer_email: 'customer@example.com',
      customer_name: 'Jane Doe',
      success_url: window.location.origin + '/thanks',
      cancel_url:  window.location.href,
    });
  });
</script>
```

The customer is redirected to `https://payments.southbill.com/c/…` where they complete the payment. On success they land on your `success_url` with `?session_id=cs_…` appended.

## React example

```tsx
import { useEffect } from "react";

export function BuyButton({ pk, priceId }: { pk: string; priceId: string }) {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = "https://payments.southbill.com/southbill.js";
    s.async = true;
    document.body.appendChild(s);
    return () => { s.remove(); };
  }, []);

  return (
    <button onClick={() => (window as any).southbill(pk).checkout({
      line_items: [{ price: priceId, quantity: 1 }],
      customer_email: "customer@example.com",
      customer_name: "Jane Doe",
    })}>Pay</button>
  );
}
```

## API reference

### `southbill(publishableKey)`
Returns a client instance. Cache it if you use it multiple times.

### `.checkout(params)`
| Field | Required | Description |
| --- | --- | --- |
| `line_items` | yes | Array of `{ price: 'price_…', quantity: number }`. Prices must exist in your catalogue. |
| `customer_email` | yes | End-customer email. Used for the receipt. |
| `customer_name` | yes | End-customer full name. |
| `success_url` | no | URL to redirect to after payment. Defaults to your Checkout Builder setting. |
| `cancel_url` | no | URL to redirect to if the customer aborts. |
| `metadata` | no | Object of string key/value pairs stored on the transaction. |

Returns a Promise that resolves once the redirect is issued.

## Security

- Publishable keys only accept requests from your whitelisted origins.
- They cannot create refunds, list transactions, or read customer data.
- They cannot set arbitrary amounts — every line item must reference a `price_…` in your catalogue.
- For server-side actions (refunds, listing payments, webhooks) use a **Secret Key (`sk_`)** from your backend.

## Testing

Create a key in **Test** mode from Developers. Test-mode keys route to Stripe test cards (`4242 4242 4242 4242`).