Files
sorsfonalak/docs/fizetes.md
T
fecoandClaude Opus 5.5 2a0830fda0
CI / test (push) Successful in 1m29s
CI / build (push) Successful in 9m7s
CI / deploy (push) Skipped
Invoices: issued in Billingo by the worker, downloadable on Számláim
A paid checkout queues an invoice row with every invoice detail (buyer,
tax type and number, item, net, VAT, gross). The worker's new 'invoices'
task creates the Billingo partner and the paid card invoice and e-mails
it (API v3), saving each step so a retry never issues a second invoice,
and keeps Billingo's whole answer; the PDF is fetched from Billingo when
the user downloads it from the new Számláim page (in the menu once there
is an invoice). Payments and invoices outlive a deleted account.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
2026-11-20 07:52:34 +00:00

79 lines
5.8 KiB
Markdown

# Fizetés (Stripe)
A csomagokat a Stripe Checkout fizetési oldalán lehet megvenni. A csomagok neve, tartalma és ára a `services/backend/src/packages.rs`-ben van; minden fizetés ezekkel indul, a Stripe-ban nem kell termékeket felvenni.
## Menete
1. A „Megveszem” gomb a `POST /v1/payments/checkout` végpontot hívja (`package`, `return_path`: az oldal, ahonnan indult).
2. A backend létrehoz egy Checkout Sessiont (bruttó ár forintban, a csomag neve, a felhasználó e-mail-címe, kötelező számlázási cím), elmenti a `stripe_checkouts` táblába, és visszaadja a fizetési oldal címét.
3. Fizetés után a Stripe visszaküld ugyanarra az oldalra `?fizetes=<session id>` paraméterrel (megszakításkor `?fizetes=megszakitva`). A `PaymentReturn` komponens a `GET /v1/payments/checkout/{id}` végpontot kérdezi, amíg a fizetés be nem igazolódik.
4. A csomagot a backend akkor adja meg, amikor a Stripe igazolja a fizetést:
- a webhook (`POST /api/v1/payments/stripe/webhook`, aláírással ellenőrizve), vagy
- ha a webhook még nem jött meg (vagy helyben nincs beállítva), a visszatérő oldal kérdésére a backend maga kérdezi meg a Stripe-ot.
A session id miatt egy fizetés csak egyszer ír jóvá (`package_orders.source = 'stripe'`).
## Mit tárolunk
Bankkártyaadatot soha: a vásárló a Stripe oldalán adja meg, hozzánk nem jut el. A `stripe_checkouts` sorban a fizetés igazolásakor eltároljuk:
- a Stripe fizetés azonosítóját (`payment_intent`) és a ténylegesen fizetett összeget (`amount_huf`; ha eltér az ártól, hibát naplózunk),
- a vevő számlázási adatait (`customer`: a Stripe `customer_details` objektuma: név, e-mail, cím, céges vásárlásnál `business_name` és `tax_ids`, pl. `hu_tin` / `eu_vat`).
A fizetési oldal kötelezően bekéri a számlázási címet, és felkínálja a céges vásárlást (cégnév, adószám; `tax_id_collection`).
A sorok a fiók törlése után is megmaradnak (`user_id` → NULL), mert a számviteli törvény 8 évig megőrzést ír elő; ilyenkor csomag már nem jár, de a számla elkészül.
## Számla
Fizetéskor a backend egy `invoices` sort is létrehoz a számla minden adatával: a vevő (név, e-mail, ország, irányítószám, város, cím, Billingo-adótípus: `HAS_TAX_NUMBER` / `NO_TAX_NUMBER` / `FOREIGN`, adószám) és a tétel (név, bruttó, nettó, áfa, 27%). Cégnél a `business_name` és a magyar adószám (`hu_tin`, ennek híján `eu_vat`) kerül a számlára.
A worker `invoices` feladata (`WORKER_TASKS`, prodon a `worker` konténerben) a Billingo API v3-mal:
1. létrehozza a partnert (`POST /partners`),
2. kiállítja a számlát (`POST /documents`: `type=invoice`, `paid=true`, `electronic=true`, `payment_method=online_bankcard`, bruttó egységár, teljesítés = a fizetés napja magyar idő szerint),
3. e-mailben elküldi a vevőnek (`POST /documents/{id}/send`).
Minden lépés eredményét elmenti a következő előtt, így újrapróbáláskor ott folytatja, ahol abbamaradt, és nem állít ki két számlát. A Billingo teljes válasza a `document` oszlopba kerül (a PDF nem: azt letöltéskor a backend kéri le, `GET /documents/{id}/download`). Hibánál növekvő várakozással újrapróbál (`MAX_INVOICE_ATTEMPTS`, alapból 10, kb. egy nap), utána `failed` lesz, és a `last_error` mondja meg, mi a baj.
A felhasználó a **Számláim** oldalon (`/szamlak`; a menüpont az első számlával jelenik meg) töltheti le a számláit.
Beállítás (`.env.secrets`, a backend és a worker is olvassa):
```
BILLINGO_API_KEY=...
```
A számlatömb alapból a fiók első számlatömbje; másikhoz `BILLINGO_BLOCK_ID` a `.env`-ben vagy a `.env.secrets`-ben.
## Beállítás
A kulcsok a `.env.secrets` fájlba kerülnek (helyben a repó gyökerében, a szerveren a `/opt/sorsfonalak` mappában), git-be soha:
```
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
```
- **A megnyitásig csak az adminok vásárolhatnak** (`PURCHASES_OPEN=false`, az alapértelmezés), a többieknek a gombok „Hamarosan” feliratúak; így senki nem ad meg valódi kártyát egy teszt- vagy félkész beállításnál.
- Teszt kulccsal (`sk_test_…`) `PURCHASES_OPEN=true` mellett is csak adminok vásárolhatnak (a Stripe tesztkártyáival senki nem jut csomaghoz). Tesztkártya: `4242 4242 4242 4242`, bármilyen jövőbeli lejárat és CVC.
- Élő kulccsal és `PURCHASES_OPEN=true` mellett mindenki vásárolhat (megnyitáskor, a `.env`-ben).
- Kulcs nélkül nincs vásárlás (helyben a `MOCK_PAYMENTS=true` próbafizetés működik; a Stripe-kulcs ezt felülírja).
A Stripe felületén:
1. **Developers → API keys**: a Secret key → `STRIPE_SECRET_KEY`.
2. **Developers → Webhooks → Add endpoint**: `https://sorsfonalak.hu/api/v1/payments/stripe/webhook`, események: `checkout.session.completed` és `checkout.session.async_payment_succeeded`. A Signing secret → `STRIPE_WEBHOOK_SECRET`. Teszt és élő módban külön végpontot kell felvenni, külön titokkal.
3. **Settings → Branding**: logó, színek (a fizetési oldal kinézete).
4. **Settings → Payment methods**: bankkártya, Apple Pay, Google Pay.
A kulcsok módosítása után a backendet újra kell indítani (`docker compose up -d backend`).
Helyben a webhook nem ér el a géphez; nem is kell, mert a visszatérő oldal a Stripe-tól kérdezi le a fizetést. Ha mégis próbálni kell: `stripe listen --forward-to localhost:3001/api/v1/payments/stripe/webhook`.
## Megnyitás előtt
- A Stripe-fiók aktiválása (céges adatok, bankszámla), élő kulcsok és élő webhook.
- Az első éles számlát nézd át a Billingóban (vevő, adószám, áfa, teljesítési dátum). A Stripe nyugtája nem magyar számla: a Stripe felületén a Customer emails → Successful payments legyen kikapcsolva.
- Visszatérítés: egyelőre a Stripe felületén, a csomagot pedig az admin oldalon kell kézzel csökkenteni.