Files
sorsfonalak/docs/fizetes.md
T
fecoandClaude Opus 5.5 e326095f3f
CI / test (push) Successful in 1m28s
CI / build (push) Successful in 5m29s
CI / deploy (push) Skipped
ÁSZF: terms page, consent on every purchase, confirmation e-mail
The new /aszf page holds the terms (a draft for legal review; the
company data come from lib/legal.ts). Stripe's payment page asks every
buyer to accept them and to ask for immediate delivery, giving up the
14-day withdrawal right; the time and the terms version are stored, and
a purchase_confirmation e-mail confirms it. Login, the landing footer,
the package cards and the sitemap link the terms.

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

89 lines
8.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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'`).
## ÁSZF és elállási jog
Minden vásárlásnál a Stripe fizetési oldalán kötelező bepipálni: „Elfogadom az ÁSZF-et, kérem a szolgáltatás azonnali megkezdését, és tudomásul veszem, hogy ezzel elveszítem a 14 napos elállási jogomat.” (`consent_collection[terms_of_service]=required` és `custom_text[terms_of_service_acceptance]`). Digitális tartalomnál így szűnik meg az elállási jog (45/2014. Korm. rendelet 29. §). Ehhez **a Stripe felületén meg kell adni az ÁSZF címét** (Settings → Business → Public details → Terms of service: `https://sorsfonalak.hu/aszf`), különben a Stripe nem indítja el a fizetést.
Az elfogadás idejét és az ÁSZF változatát (`TERMS_VERSION`, a frontend `TERMS_UPDATED`-jével együtt kell léptetni) a `stripe_checkouts` sor őrzi (`terms_accepted_at`, `terms_version`). Fizetés után a backend visszaigazoló e-mailt küld (`purchase_confirmation`): a csomag, az összeg, a dátum és a lemondás az elállási jogról; ez a rendelet szerinti visszaigazolás.
Az ÁSZF az `/aszf` oldalon van (`services/frontend/src/app/aszf/page.tsx`); a céges adatok a `lib/legal.ts`-ből jönnek. Megnyitás előtt jogásszal át kell nézetni.
## 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, végösszeg, nettó, áfa, áfakód). Az áfakód az `INVOICE_VAT` (a backend `.env`-je): alapból `AAM` (alanyi adómentes: nettó = végösszeg, áfa 0, a számla megjegyzésében „Alanyi adómentes.”), vagy egy kulcs, pl. `27%`. A tétel a törvény szerint azonosítja a szolgáltatást (Áfa tv. 169. § e): megnevezése pl. „Online tartalomszolgáltatás – Páros csomag”, egysége `csomag`, megjegyzése a tartalom („Hozzáférés a sorsfonalak.hu szoftveresen előállított, személyre szabott szöveges tartalmaihoz: 2 képletelemzés, … Digitális tartalom.”; `Package::invoice_item`). Szándékosan nem „asztrológiai”: a szolgáltatás egy weboldal programmal előállított tartalma, nem személyes szakmai tanácsadás. 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.
Minden igazolt fizetéshez készül számla, a teszt módúakhoz (`sk_test_…`) is: így a teljes folyamat próbálható egy teszt Billingo-fiókkal. Éles Billingo-fiók mellett ezért prodon már ne legyen teszt Stripe-kulcs (a kettőt megnyitáskor együtt kell élesre cserélni).
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.