Getting started

Quickstart

Create a checkout session for a plan, send your buyer to it, and pay with Apple Pay. You'll get back a tax invoice issued by Hlawula as seller of record.

The API

Every request goes to Hlawula's API over HTTPS. The examples use this base URL:

Terminal

export HLAWULA_URL=https://hlawula.co.za

Check it's reachable:

bash

curl $HLAWULA_URL/api/health

Take your first payment

Pick a plan
Plans are the products your customers subscribe to. Prices are in cents, excluding tax.
bash
```
curl $HLAWULA_URL/api/plans
```
Create a checkout session
Tell us the plan, the buyer's email and their country. The country decides the tax line.
bash
```
curl -X POST $HLAWULA_URL/api/checkout/sessions \
  -H "Content-Type: application/json" \
  -d '{"planId":"plan_pro","email":"thandi@example.co.za","country":"ZA"}'
```
The response has an id like cs_live_0015a4a0ff9d, the subtotal, a VAT line of R 149.85 and a total of R 1,148.85.
Send the buyer to the hosted checkout
Open /checkout?s=<session id>. The buyer sees your product, the tax and the eight payment methods. You can also try it with no session at /checkout.

Or pay from your own UI

Pass the device token you get from Apple Pay to the pay endpoint:

bash

curl -X POST $HLAWULA_URL/api/checkout/sessions/cs_live_0015a4a0ff9d/pay \
  -H "Content-Type: application/json" \
  -d '{"method":"apple_pay","walletToken":"<token from the device>"}'

You get back outcome: "paid", the transaction, and the tax invoice numbered INV-2026-….

See it in the dashboard
The payment appears in recent transactions on the dashboard and counts towards your next payout.

No authentication yet

The demo API is open, so anyone who can reach it can create sessions and run payouts. Secret API keys per merchant are planned; until then, keep the container off the public internet or behind your own proxy.