bober-bbq-bot/docs/PAYMENTS.md

# Payment providers

Bober BBQ can take card payments through more than one provider. This
document is the map of how that's wired, and the checklist for adding
another one.

## Files

- `bober_bbq/payments/base.py` — the shared contract every provider module
  follows (documented as a `Protocol` for type-checkers; nothing enforces
  it at runtime, matching the rest of this codebase's plain-module style).
  Also hosts `ProviderNotConfigured`/`ProviderError` (the two exceptions
  every provider's own exceptions must subclass) and `claim_order_paid`
  (the atomic "mark this order paid, exactly once" transition shared by
  every provider and every call site).
- `bober_bbq/payments/monobank.py` — Monobank Merchant Acquiring API.
  The original/reference implementation.
- `bober_bbq/payments/liqpay.py` — LiqPay Checkout (CNB) API.
- `bober_bbq/payments/registry.py` — picks the active provider
  (`Setting.get("payment_provider")`, admin-configurable) and dispatches
  an existing `Order` to whichever provider actually created its invoice
  (`Order.payment_provider`), so switching the active provider never
  disturbs orders already in flight on the old one.
- `bober_bbq/api/payments.py` — the Monobank webhook route
  (`POST /api/payments/monobank/webhook`) plus `notify_order_paid()` /
  `notify_order_payment_failed()`, the provider-agnostic "just got
  paid/failed" side effects (customer + staff Telegram messages,
  fiscalization) shared by every provider's webhook.
- `bober_bbq/api/payments_liqpay.py` — LiqPay's webhook
  (`POST /api/payments/liqpay/webhook`, form-encoded `data`+`signature`,
  NOT JSON — see below) and the checkout-redirect bridge page
  (`GET /api/payments/liqpay/redirect/<order_id>`) that LiqPay needs and
  Monobank doesn't.
- Call sites that create/poll a payment, all going through
  `registry.py` rather than a hardcoded provider:
  - `bober_bbq/api/checkout.py` — `_offer_card_payment()` (new order from
    the Mini App checkout form) and `GET /api/checkout/payment-status/<id>`
    (the Mini App's own "Перевірити оплату" poll button).
  - `bober_bbq/api/orders.py` — `POST /orders/<id>/pay` (retry payment on
    an existing order).
  - `bober_bbq/utils/reconciliation.py` — `reconcile_pending_payments()`,
    the periodic APScheduler job that catches missed webhooks for
    whichever provider each pending order actually used.

## The race-safety guarantee

The same "card payment just cleared" event can be observed from three
independent places racing each other, for either provider: that
provider's webhook, the Mini App's own poll, and the reconciliation job.
`claim_order_paid(order)` in `base.py` is a single
`UPDATE ... WHERE payment_status != 'paid'` — it returns `True` for
whichever caller actually won the transition, `False` for every other
racing caller, so paid-order side effects (notification, fiscalization)
fire exactly once no matter which path (or which provider) got there
first. Every call site checks this return value before firing side
effects; never skip that check when wiring up a new provider or a new
call site.

## Adding a third provider (e.g. Fondy)

Fondy is **not implemented** — this is the checklist for whoever adds it
(or another provider) later, written against `liqpay.py` as the concrete
template to copy from (it's the more recently added, more heavily
commented of the two existing modules).

1. **New module** `bober_bbq/payments/fondy.py`. Define, matching the
   shape documented in `base.py`:
   - `NAME = "fondy"`
   - `FondyNotConfigured(ProviderNotConfigured)`, `FondyError(ProviderError)`
   - `create_invoice(order) -> dict` returning at least
     `{"invoiceId": ..., "pageUrl": ...}`
   - `get_invoice_status(invoice_id) -> dict` returning at least
     `{"status": ...}` in Fondy's own status vocabulary
   - `verify_webhook_signature(...)` for whatever shape Fondy's webhook
     actually posts (check Fondy's current docs — like LiqPay vs.
     Monobank, don't assume it matches either existing shape)
   - `verify_token(...)` — a credentials smoke-test, ideally against a
     real no-op endpoint if Fondy has one (Monobank does; LiqPay didn't,
     see the honesty note in `liqpay.py`'s own `verify_token()` docstring)
   - `PAID_STATUSES` / `FAILED_STATUSES` — Fondy's own status strings
   - Re-export `claim_order_paid` from `base.py` (`from
     bober_bbq.payments.base import claim_order_paid`) rather than
     reimplementing it.
2. **Register it** in `bober_bbq/payments/registry.py`'s `PROVIDERS` dict:
   `fondy.NAME: fondy`. Also extend `get_order_invoice_id` /
   `set_order_invoice` / `get_order_page_url` with a Fondy branch if it
   needs its own id/url columns (see next step) — right now those three
   functions are a simple `if provider is liqpay: ... else: monobank-shaped
   columns`, which stops being adequate once there's a third shape; switch
   that to an `if/elif/else` per provider at that point.
3. **New `Order` columns** if Fondy's invoice reference doesn't fit the
   existing ones: add `fondy_invoice_id` / `fondy_page_url` (or whatever
   Fondy actually calls them) to `bober_bbq/models.py`'s `Order` class,
   and a matching `_add_column_if_missing(...)` pair in
   `bober_bbq/migrate.py` (this project has no Alembic — see that file's
   own docstring). Do **not** reuse Monobank's or LiqPay's id/url columns
   for a different provider's identifiers.
4. **Webhook route.** If Fondy's webhook body shape differs from both
   existing ones (form vs. JSON, different field names), give it its own
   file `bober_bbq/api/payments_fondy.py` mirroring
   `payments_liqpay.py` — import `payments_bp`,
   `notify_order_paid`/`notify_order_payment_failed` from
   `bober_bbq.api.payments`, define `@payments_bp.post("/fondy/webhook")`,
   and import that new module at the bottom of `api/payments.py` (same
   pattern already used for `payments_liqpay`) so its routes register.
5. **Settings**: add `fondy_...` keys to `DEFAULT_SETTINGS` in
   `models.py` (credentials + any provider-specific toggle, e.g. a
   sandbox flag if Fondy has one), add a `"fondy"` `<option>` to the
   `payment_provider` `<select>` in
   `bober_bbq/templates/admin/settings.html`, a new `<h3>Fondy</h3>`
   fields block following the LiqPay block's shape, wire any checkbox
   setting into `CHECKBOX_SETTINGS` in `bober_bbq/admin/routes.py`, and
   (optionally) a `settings_test_fondy` route mirroring
   `settings_test_liqpay`.
6. **Config fallback**: add `FONDY_...` env vars to `config.py`
   following the `LIQPAY_...` / `MONOBANK_...` precedent (Setting wins,
   env var is only the pre-first-admin-visit fallback).
7. **Reconciliation**: extend the `or_(...)` filter in
   `reconcile_pending_payments()` (`bober_bbq/utils/reconciliation.py`)
   to also match Fondy's new invoice-id column, and optionally add a
   `check_fondy_token_health()` mirroring `check_liqpay_token_health()`,
   wired into `run_web.py`'s scheduler the same way.
8. **Test it** the same way this session's LiqPay work was tested (no
   live Fondy sandbox was available for LiqPay either): monkeypatch
   `fondy.requests.post`/`.get` and re-run the payment-race regression
   test, extended to also create a Fondy-provider order and race it the
   same way the Monobank/LiqPay ones are raced. Get a real Fondy sandbox
   test before taking real money through it — mocked-HTTP unit coverage
   is a structural safety net, not a substitute for hitting the real API
   at least once.

## What's genuinely uncertain about the LiqPay implementation

Flagged here (and inline in `liqpay.py`) because this was built without
access to live LiqPay credentials or a sandbox:

- The stable, well-documented parts (verified against LiqPay's public
  documentation, though not against a live server): the
  `base64(JSON)` + `base64(sha1(private_key + data + private_key))`
  signing scheme, the checkout endpoint
  (`https://www.liqpay.ua/api/3/checkout`), the fact that its webhook
  posts `data`+`signature` as form fields rather than JSON, and the
  status-check endpoint (`https://www.liqpay.ua/api/request`,
  `action: "status"`).
- Genuinely guessed, not confirmed: the exact `err_code` values LiqPay
  returns for "bad public/private key" vs. "no such order" (used by
  `liqpay.verify_token()`'s heuristic — see its docstring), and the
  complete set of possible `status` values beyond the well-known
  `success` / `failure` / `error` / `reversed` / `expired` / `sandbox`.
- Before this goes live: get a real LiqPay sandbox account, run one real
  payment through it, and confirm `verify_token()`'s "keys look valid"
  heuristic actually distinguishes bad keys from a nonexistent order the
  way it's designed to.