Barion Integráció - Technikai Áttekintés

Platform Áttekintés

A Bookinda egy SaaS alapú időpontfoglalási és szalonkezelő platform szalonok, klinikák és szolgáltató vállalkozások számára. A Barion két különálló fizetési kontextusban van integrálva:

Mindkét kontextus a Barion Smart Gateway-t használja (/v2/Payment/Start).

Kettős felhasználási modell

1. Platform szintű fizetés: A Bookinda mint szolgáltató a Barion-t használja az előfizetési rendszerdíjak beszedésére. A tenantok (szalonok, klinikák) havonta vagy évente fizetnek a platformhasználatért. A pénz a Bookinda Barion tárcájába érkezik. Ismétlődő token fizetés (MerchantInitiatedPayment) segítségével az előfizetés automatikusan megújul.

2. Tenant szintű fizetés (Barion Connect): A tenantok saját Barion fiókjukat csatlakoztathatják a platformhoz. Így az ő ügyfeleik az online foglalás során közvetlenül a tenant Barion tárcájába fizetik az előleget. A Bookinda csak közvetítő - a pénz közvetlenül a vállalkozáshoz jut.

Barion Pixel Implementáció

Betöltési stratégia

A Barion Pixel minden marketing és publikus foglalási oldalon betöltődik egy dedikált React komponensen keresztül.

Betöltési sorrend (3 lépés):

1. Inline stub (beforeInteractive script) - létrehozza a window.bp parancs-sort mielőtt a bp.js betöltődne
2. bp.js aszinkron betöltés (afterInteractive script) - betöltődik a https://pixel.barion.com/bp.js címről
3. Pixel inicializálás + consent - inicializálás a Pixel ID-vel, majd a tárolt cookie consent alapján grantConsent / rejectConsent hívás

NoScript fallback: Egy láthatatlan 1x1 követőpixel (pixel.barion.com/a.gif) biztosítja a követést JavaScript nélküli böngészőkben is.

Implementált Pixel Események

Az identitás események (setEncryptedEmail, setEncryptedPhone) mellőzik a consent-et - mindig futnak csalás megelőzési célból.

Cookie Consent és GDPR

Consent Kategóriák

Integrációs folyamat

1. A felhasználó elfogadja vagy elutasítja a sütiket a consent banneren
2. A consent beállítások mentődnek a localStorage-ba
3. Egy cookie-consent-update custom event kerül kiküldésre
4. A Barion Pixel komponens figyeli és meghívja a bp('consent', 'grantConsent') vagy bp('consent', 'rejectConsent') függvényt a marketing consent érték alapján

A consent banner 1,5 másodperces késleltetéssel jelenik meg. A felhasználók a láblécben található "Cookie beállítások" linkre kattintva módosíthatják beállításaikat.

Visszavonás: Ha a felhasználó később visszavonja a marketing consent-et, azonnal rejectConsent hívás történik, és a Full Pixel események leállnak.

Pixel Esemény Tölcsér - Foglalási Fizetési Folyamat

A teljes vásárlási tölcsér az ügyfél előlegfizetéshez:

0. LÉPÉS - Oldal betöltés
   ├─ setEncryptedEmail(customerEmail)    [mindig, consent nélkül]
   └─ trackContentView({ contentType: 'Page', id: 'booking-payment-{slug}' })

1. LÉPÉS - Ügyfél rákattint a "Fizetés Barionnal" gombra
   ├─ trackInitiateCheckout({ contents, step: 1, revenue })
   ├─ trackInitiatePurchase({ contents, step: 2, revenue })
   └─ trackAddPaymentInfo({ contents, paymentMethod: 'Barion', step: 3 })
   → Átirányítás a Barion Smart Gateway-re

2. LÉPÉS - Ügyfél visszatér a fizetés után
   ├─ verifyBarionPayment(paymentId) - státusz ellenőrzés
   └─ HA státusz === "Succeeded":
      └─ trackPurchase({ contents, step: 4, revenue, orderNumber: paymentId })
   → Átirányítás a Foglalás Megerősítés oldalra

Duplikáció védelem

Több szintű védelem a dupla eseményküldés ellen:

• useRef alapú flag-ek mindkét oldalon (pixelFired a fizetési lépésnél, hasStarted a visszatérési oldalon) - oldal újratöltés nem küld dupla eventet
• A sessionStorage checkout adat törlődik a sikeres purchase event után
• A paymentId mint orderNumber biztosítja az egyedi azonosítást

ProductItem struktúra az összes eseményben:

{
  contentType: 'Product',
  id: 'deposit-{tenantSlug}',
  name: 'Előleg - {tenantSlug}',
  unitPrice: fizetendőÖsszeg,
  quantity: 1,
  currency: 'HUF',    // vagy 'EUR'
  unit: 'db',
  totalItemPrice: fizetendőÖsszeg
}

Barion Smart Gateway - Ügyfél Előlegfizetés

Amikor egy végfelhasználó időpontot foglal, a tenant (vállalkozás) előlegfizetést kérhet. A pénz közvetlenül a tenant saját Barion tárcájába érkezik.

Payment/Start Kérés

POST /v2/Payment/Start

{
  "PaymentType": "Immediate",
  "GuestCheckout": true,
  "FundingSources": ["All"],
  "Currency": "HUF",
  "Locale": "hu-HU",
  "RedirectUrl": "https://bookinda.hu/{slug}/book/barion-return?token=...",
  "CallbackUrl": "https://api.bookinda.hu/api/barion/customer-ipn",

  "Transactions": [{
    "Payee": "[email protected]",
    "Total": 5000,
    "Currency": "HUF",
    "Comment": "Előleg: Hajvágás + Festés",
    "Items": [{
      "Name": "Hajvágás + Festés",
      "Description": "Előleg - Hajvágás + Festés",
      "Quantity": 1,
      "Unit": "db",
      "UnitPrice": 5000,
      "ItemTotal": 5000
    }]
  }]
}

Fontos részletek:

• A pénz közvetlenül a tenant Barion tárcájába érkezik (Payee = tenant email) - a Bookinda nem érint pénzt
• GuestCheckout: true - az ügyfeleknek nem kell Barion fiókkal rendelkezniük
• FundingSources: ['All'] - minden fizetési mód engedélyezve, beleértve az Apple Pay-t és Google Pay-t
• Nincs ismétlődő/token regisztráció az ügyfél előlegeknél

Ellenőrzés és Véglegesítés

1. A frontend meghívja a GET /verify-barion-payment?paymentId=... végpontot → a backend lekéri a /v2/Payment/GetPaymentState-et
2. Ha status === "Succeeded" → a frontend meghívja a POST /complete-with-payment végpontot
3. A backend az időpontot depositStatus: PAID-ra állítja

Barion Smart Gateway - Platform Előfizetés (Rendszerdíj)

A tenantok (vállalkozás tulajdonosok) a Bookinda előfizetési díjukat Barion-on keresztül fizetik. A pénz a Bookinda platform Barion tárcájába érkezik.

Payment/Start Kérés (Első Előfizetés)

POST /v2/Payment/Start

{
  "PaymentType": "Immediate",
  "GuestCheckout": true,
  "FundingSources": ["All"],
  "Currency": "HUF",
  "Locale": "hu-HU",

  "InitiateRecurrence": true,
  "RecurrenceId": "{base64url-random-token}",
  "RecurrenceType": "MerchantInitiatedPayment",

  "RedirectUrl": "https://bookinda.hu/t/{slug}/account/subscription?success=true",
  "CallbackUrl": "https://api.bookinda.hu/api/barion/ipn",

  "Transactions": [{
    "Payee": "[email protected]",
    "Total": 9990,
    "Currency": "HUF",
    "Comment": "Pro csomag - Havi előfizetés",
    "Items": [{
      "Name": "Pro csomag - Havi",
      "Description": "Bookinda Pro előfizetés",
      "Quantity": 1,
      "Unit": "hónap",
      "UnitPrice": 9990,
      "ItemTotal": 9990,
      "SKU": "TIER-pro-monthly"
    }]
  }]
}

• InitiateRecurrence: true - regisztrálja a kártyát jövőbeli ismétlődő terhelésekhez
• RecurrenceId - a bolt által generált egyedi token (azonnal mentve az adatbázisba)
• RecurrenceType: MerchantInitiatedPayment - változó összegű előfizetésekhez
• A pénz a Bookinda platform Barion tárcájába érkezik

Ismétlődő Token Fizetések (Előfizetés Megújítás)

Az első fizetés regisztrálja a kártya tokent, a következő megújítások a tárolt RecurrenceId-t használják.

Ismétlődő Payment/Start Kérés

POST /v2/Payment/Start

{
  "PaymentType": "Immediate",
  "GuestCheckout": true,
  "FundingSources": ["All"],
  "Currency": "HUF",

  "RecurrenceId": "{ugyanaz-a-token-az-első-fizetésből}",
  "RecurrenceType": "MerchantInitiatedPayment",
  "ChallengePreference": "NoChallengeNeeded",
  "TraceId": "{kártya-kibocsátó-trace-id}",

  "CallbackUrl": "https://api.bookinda.hu/api/barion/ipn",

  "Transactions": [{
    "Payee": "[email protected]",
    "Total": 9990,
    "Currency": "HUF",
    "Comment": "Pro csomag - Havi megújítás",
    "Items": [{
      "Name": "Pro csomag megújítás",
      "Description": "Bookinda Pro automatikus megújítás",
      "Quantity": 1,
      "Unit": "hónap",
      "UnitPrice": 9990,
      "ItemTotal": 9990,
      "SKU": "TIER-pro-monthly-recurring"
    }]
  }]
}

Token Életciklus

ELSŐ FIZETÉS                          ISMÉTLŐDŐ FIZETÉS
────────────                          ───────────────────
Payment/Start                         Payment/Start
  InitiateRecurrence: true              RecurrenceId: {ugyanaz a token}
  RecurrenceId: {bolt által generált}   TraceId: {előző sikerből}
  RecurrenceType: MerchantInitiated     ChallengePreference: NoChallengeNeeded
       │                                       │
       ▼                                       ▼
GetPaymentState                       GetPaymentState
  RecurrenceResult: "Successful"        Status: "Succeeded"
  TraceId: {kibocsátó trace}            TraceId: {frissített trace}
       │                                       │
       ▼                                       ▼
Mentés az adatbázisba:                Mentés az adatbázisba:
 - barionRecurrenceId (bolt token)    - barionTraceId (frissítve)
 - barionTraceId (kibocsátó trace)    - currentPeriodEnd (meghosszabbítva)
 - barionPaymentLast4                 - status: ACTIVE
 - barionPaymentBrand

RecurrenceId vs TraceId:

• RecurrenceId - A bolt által generált egyedi token. Egyszer jön létre az első fizetéskor, ugyanaz használódik az összes későbbi terheléshez.
• TraceId - A kártyakibocsátó trace azonosítója. A Barion adja vissza minden sikeres fizetés után. A következő fizetésekben használjuk a 3D Secure mentesség érdekében.

Automatikus Megújítási Ütemezés

Lemondás

A barionRecurrenceIdtörlése az adatbázisból hatékonyan leállítja az ismétlődő terheléseket - a Barionnak nincs külön "előfizetés lemondás" API végpontja.

IPN / Webhook Kezelés

Platform Előfizetés IPN

POST https://api.bookinda.hu/api/barion/ipn?PaymentId=...

Kezelési folyamat:

1. PaymentId kinyerése a query stringből vagy POST body-ból
2. GET /v2/Payment/GetPaymentState meghívása
3. Előfizetés rekord azonosítása
4. Succeeded esetén: előfizetés aktiválása, periódus meghosszabbítása, TraceId mentése, kártyaadatok kinyerése, számla létrehozása, tier kreditek jóváírása
5. Failed/Expired esetén: hibaszámláló növelése, türelmi idő beállítása, 3+ hiba után PAST_DUE státusz

Mindig HTTP 200-at ad vissza a fogadás nyugtázására.

Ügyfél Előleg IPN

POST https://api.bookinda.hu/api/barion/customer-ipn?PaymentId=...

Siker esetén: az időpont depositStatus: PAID-ra frissül.

Fizetési Módok és FundingSources

Minden Barion fizetés FundingSources: ['All']-t használ, ami engedélyezi:

• Bankkártyák - Visa, Mastercard, Maestro, Amex
• Apple Pay - automatikusan működik a Barion Smart Gateway-en
• Google Pay - automatikusan működik a Barion Smart Gateway-en
• Barion tárca - közvetlen egyenleg fizetés

A fizetési mód kiválasztását teljes egészében a Barion Smart Gateway hosted checkout oldala kezeli. Nincs szükség egyedi Apple Pay vagy Google Pay integrációra.

Hibakezelés és Türelmi Idők

Sikertelen Előfizetési Fizetés - Türelmi Idők

Minden Barion API válasz ellenőrzésre kerül az Errors tömbre, a hibák teljes címmel és leírással naplózódnak.

Használt Barion API Végpontok

Teszt vs Éles környezet

Megfelelőségi Ellenőrzőlista

Az alábbi ellenőrzőlista összefoglalja a Barion integráció megfelelőségi szempontjait és azok megvalósítását:

Adatkezelés és Tájékoztatás

A Barion Pixel integrációhoz a következő adatvédelmi intézkedések vannak érvényben:

• Adatkezelési tájékoztató - a Barion Pixel külön szekcióban szerepel az Adatkezelési Tájékoztató oldalon
• Cookie banner - 3 kategória (Szükséges / Statisztikai / Marketing), naplózott hozzájárulással
• Cookie szabályzat - részletes leírás a használt sütikről a Cookie Szabályzat oldalon
• Consent visszavonhatóság - a felhasználó bármikor módosíthatja a cookie beállításait a láblécben