INVOICE_VAT picks the VAT of the invoices: AAM (no VAT, net = gross, the invoice says so) or a rate like 27% once the exemption limit is passed. The packages page tells which. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
6.0 KiB
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
-
A „Megveszem” gomb a
POST /v1/payments/checkoutvégpontot hívja (package,return_path: az oldal, ahonnan indult). -
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_checkoutstáblába, és visszaadja a fizetési oldal címét. -
Fizetés után a Stripe visszaküld ugyanarra az oldalra
?fizetes=<session id>paraméterrel (megszakításkor?fizetes=megszakitva). APaymentReturnkomponens aGET /v1/payments/checkout/{id}végpontot kérdezi, amíg a fizetés be nem igazolódik. -
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'). - a webhook (
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 Stripecustomer_detailsobjektuma: név, e-mail, cím, céges vásárlásnálbusiness_nameéstax_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%. 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:
- létrehozza a partnert (
POST /partners), - 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), - 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=truemellett 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=truemellett mindenki vásárolhat (megnyitáskor, a.env-ben). - Kulcs nélkül nincs vásárlás (helyben a
MOCK_PAYMENTS=truepróbafizetés működik; a Stripe-kulcs ezt felülírja).
A Stripe felületén:
- Developers → API keys: a Secret key →
STRIPE_SECRET_KEY. - Developers → Webhooks → Add endpoint:
https://sorsfonalak.hu/api/v1/payments/stripe/webhook, események:checkout.session.completedéscheckout.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. - Settings → Branding: logó, színek (a fizetési oldal kinézete).
- 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.