SZÉP kártya 2.0 a webshop checkouton: mi változik 2026-ban

A SZÉP kártya 2026 ban átalakul. Az új konstrukció (a sajtóban 'SZÉP 2.0' ként emlegetik) megtartja a három bank kibocsátót (OTP, MKB, K&H), de a zseb kategóriák és az elköltési szabályok változnak. A jogi részletet az ügyvéded elolvassa, neked mint webshop fejlesztőnek 7 dolog érint.

1. Új zseb kategóriák · a régi 3 helyett kettő plusz egy közös

A klasszikus 'Szálláshely / Vendéglátás / Szabadidő' tagolás 2026 ban megváltozik. Az új modellben két fő zseb (egyszerűsített elköltés) plusz egy közös 'aktív magyar' zseb lesz, ami csak meghatározott kategóriákra költhető. A te kódodban a zseb azonosítója (`pocket_code`) változik, a régi `accommodation/catering/leisure` enum legacy lesz, az új API ban kapsz egy bővített listát.

type SzepPocket =
  | "main_a"      // 2026 új főzseb · korábban szálláshely
  | "main_b"      // 2026 új főzseb · korábban vendéglátás
  | "active_hu"   // új közös 'aktív magyar' zseb
  | "legacy_acc"  // 2025 ig kibocsátott, lejárattal
  | "legacy_cat"
  | "legacy_lei";

export function isPocketEligible(
  pocket: SzepPocket,
  productCategory: string
): boolean {
  // Az MNB / NGM által közzétett MCC + product mapping.
  return SZEP_2_MAPPING[pocket]?.includes(productCategory) ?? false;
}

2. Tranzakció payload új mezői

Az online tranzakció payload három új kötelező mezőt kap a 2026 os specifikációban (a három bank szinte azonos formátumot ad, de a mezőnevek picit különböznek):

• `merchant_category_v2` · az NGM által közzétett új kategória kód (4 számjegyű, MCC szerű, de saját kódrendszer).
• `pocket_intent` · a vásárló szándéka, melyik zsebből szeretne fizetni. Ha nincs megadva, a kártya alapértelmezett zsebéből megy.
• `split_allowed` · boolean. Engedi e a vevő, hogy a tranzakció több zseb között oszoljon meg, ha az egyikben nem elég a fedezet.

3. UX hook · zseb választó a checkouton

A régi kódbázisban valószínűleg egy 'SZÉP kártyával fizetek' rádiógomb volt. 2026 ban ez kibővül egy zseb választóval. Két megközelítés van, mindkettőt láttuk élesben:

• Egyszerű: csak akkor jelenítsd meg a zseb választót, ha a kosárban olyan termék van, ami több zsebből is fizethető. Ez a default.
• Részletes: minden esetben mutasd a zseb listát + kártya egyenleget. Ehhez balance lekérdezés kell előre, ami plusz API hívást jelent. Csak akkor jó, ha a kosárméret nagyobb 30 ezer Ft nál.

4. Split payment · a régóta hiányzó funkció

2026 ban végre engedélyezett a split payment SZÉP kártya és más fizetési mód között (pl. SZÉP + bankkártya). Ez új sztori a checkoutban: ha a SZÉP kártyán kevesebb fedezet van, mint a kosár értéke, a maradékot bankkártyával vagy átutalással fizetheted. A te kódodnak ezt kezelnie kell · két párhuzamos tranzakció, ha az egyik bukik, az egészet rollback elni.

async function processSplitPayment(
  cart: Cart,
  szepAmount: number,
  cardAmount: number
) {
  const szep = await szepClient.charge({ amount: szepAmount, ... });
  if (!szep.ok) return { ok: false, reason: "szep_failed" };

  const card = await cardGateway.charge({ amount: cardAmount, ... });
  if (!card.ok) {
    await szepClient.refund(szep.tx_id);
    return { ok: false, reason: "card_failed_szep_refunded" };
  }
  return { ok: true, txs: [szep.tx_id, card.tx_id] };
}

5. Validáció · termékkategória mapping kötelező

A webshop minden termékénél el kell tárolnod, melyik új SZÉP kategóriába esik. Ezt nem kerülheted ki, mert a tranzakció payloadban benne kell lennie. A migrációt egy egyszeri scripttel megoldod: végigmész a termékeken, és az NGM mapping táblából kitöltöd. Ezt a táblát ősszel teszi közzé az NGM, addig a sandboxban dolgozunk a banki teszt mappinggel.

6. Hibaüzenetek · a vevő érti meg

A bankok visszadnak hibakódot, de a felhasználónak nem szól semmit, hogy 'POCKET_BALANCE_INSUFFICIENT'. Csinálj fordító réteget. Egy 15 hibakód → 8 magyar nyelvű üzenet mapping bőven elég. A 'kártyán nincs elég pénz, válassz másik zsebet' és a 'a termék ezzel a zsebbel nem fizethető' a két leggyakoribb.

7. Webhook · POS és online szinkron

Ha van fizikai pénztárad is, a 2026 os spec megkívánja, hogy az online és a POS tranzakciók egységes ledgerben legyenek. Webhook érkezik mind a két oldalról, neked uniform tranzakció modellt kell tartanod. A bankok mindegyike `POST /webhook` ot küld, három különböző formátummal · normalizáld be egy rétegben.

Mikor kezdj neki

A bankok a sandbox környezetet általában 4-5 hónappal a hivatalos indulás előtt elérhetővé teszik. Ha a hivatalos indulás 2026. szeptember, akkor május júniusban már kell sandbox integrációt csinálni. Mi a sajátunkat áprilisban kezdtük, ősszel megyünk élesbe.