# Alad

> Verify Ethiopian bank/wallet payments at the source (one normalized JSON
> envelope across ~25 institutions), and run merchant checkout sessions so
> customers pay into your settlement accounts.

Base URL `https://pay.lubaak.com`. Authenticate with
`Authorization: Bearer <token>` from https://pay.lubaak.com/dashboard/tokens

## Integrating

- [Agent file](https://pay.lubaak.com/agents.md): drop-in instructions for coding agents - verify, checkout, webhooks, pitfalls. Start here.
- [API docs](https://pay.lubaak.com/docs): human docs with live playground.
- [Try verify](https://pay.lubaak.com/verify): browser verifier (IP-limited, no key).
- [Status](https://pay.lubaak.com/status): per-institution uptime.

## API (summary)

**Verify**

- `POST /api/v2/verify` (preferred) - `url` **or** `reference` + `bank`; sender field is `account_number`. Optional `settlement_account`, `expected_amount`, `phone` (CBE Birr).
- `GET /api/v2/verify` - same as query string.
- `POST|GET /api/v1/verify` - same behaviour; sender field is `suffix` (legacy).
- Same response shape for every bank. First successful uncached hit may use credits; repeats stay free when `cached: true`.

**Checkout** (merchant Sanctum key)

- `POST /api/v1/checkout/session` (aliases `/orders`, `/checkouts`) - requires `success_url` + `failure_url`; optional one `callback_url` webhook; settlement via saved accounts or `settlement_accounts`.
- Hosted pay page: `paymentUrl` → `/pay/{order_id}`
- Paid only after live receipt match on amount + settlement account.
- Optional session-token form API under `/api/v1/form/*` for custom UIs.

**Accounts**

- `GET|POST|PUT|DELETE /api/v1/accounts` - merchant settlement address book.

## Product notes

- `account_number` on verify = **sender**; settlement / callback matching = **your** account.
- Amounts in `data` are strings (`"100 ETB"`); use `amount_match` or parse.
- Checkout settlement methods: same institution codes as verify (all ~25 banks/wallets).
- CBE/BOA confirm may need payer `account_number`; CBE Birr needs `phone`.
- Health: `GET /up`. Component JSON: `GET /api/v1/status`. HTML outages: `/status`.