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

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

  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.