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
5.8 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, 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:
- 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.