IPN (Egyszerű kifizetési értesítés)
Az IPN részletes leírása elérhető a Számlázz.hu tudástárban.
💵 Bizonylatok kifizetettségének visszajelzése
Lehetőség van arra, hogy bizonylatok (számla, díjbekérő) kifizetettségéről értesítést - IPN (Instant Payment Notification) - kapjon a webáruház (vagy egyéb üzleti alkalmazás).
Ezt az üzenetet a Számlázz.hu küldi egy meghatározott webcímre HTTP POST kérésként. Az URL megadható a számlázási fiókban a Fiók beállítások / Számlázás alapadatok oldal alján lévő beviteli mezőben.
⏰ Mikor küldi a rendszer az IPN üzenetet?
Az IPN üzenet akkor jön létre, amikor:
- Egy bizonylat (számla vagy díjbekérő) kifizetett összege megváltozik (például részleges vagy teljes kifizetés történik)
- A változás a bizonylat kiállítója (kibocsátó) oldaláról történik
- A cég rendelkezik beállított IPN URL-lel
Díjbekérő kifizetése
- Ha a „Díjbekérő automatikus számlázása” beállítás be van kapcsolva, a kifizetett díjbekérőből számla készül, a kifizetés a számlára kerül, és az IPN a számláról megy. Ilyenkor a
szlahu_szamlaszama számla sorszáma, aszlahu_dijbekero_szamaa díjbekérő sorszáma, aszlahu_rendelesszampedig a díjbekérőtől örökölt rendelésszám. - Ha a beállítás ki van kapcsolva, vagy a díjbekérőre kézzel a teljes összegnél kisebb banki tranzakciót párosítanak, nem készül számla, és az IPN a díjbekérőről megy. Ilyenkor a
szlahu_szamlaszama díjbekérő sorszáma, aszlahu_dijbekero_szamapedig üres.
📋 IPN üzenet paraméterei
Az IPN üzenet a következő paramétereket tartalmazza:
| Paraméter | Leírás | Példa |
|---|---|---|
szlahu_szamlaszam | A bizonylat (számla vagy díjbekérő) sorszáma | E-2020-123 |
szlahu_dijbekero_szama | Díjbekérőből készült számlánál a díjbekérő sorszáma, egyébként üres | DB-2020-456 |
szlahu_rendelesszam | Rendelésszám (ha szerepel a bizonylaton) | RND1234 |
szlahu_bruttovegosszeg | A bizonylat bruttó végösszege | 10000 |
szlahu_kifizetettbrutto | A bizonylatra addig kifizetett teljes összeg (nem az utolsó befizetés) | 10000 |
szlahu_fizetesmod | A kifizetés módja | kp, bankkártya, átutalás |
szlahu_kifizdat | A kifizetés dátuma (ÉÉÉÉ-HH-NN) | 2025-05-14 |
A szlahu_kifizdat IPN üzenet küldése alapértelmezetten nem elérhető. Amennyiben szeretnéd használni ezt a funkciót, ügyfélszolgálatunk készséggel segít annak aktiválásában. Kérjük, lépj kapcsolatba ügyfélszolgálatunkkal, és kérj hozzáférést!
💻 Technikai implementáció
IPN üzenet formátuma
FONTOS: Az IPN üzenet adatai a HTTP POST kérés body-jában kerülnek átküldésre. Az üzenet application/x-www-form-urlencoded content type-tal érkezik.
Válasz követelménye
A fogadó rendszernek HTTP 200 OK választ kell küldenie, hogy jelezze a sikeres feldolgozást. A válasz törzsének tartalma nem releváns, csak a HTTP státuszkód számít.
Az IPN a bizonylat állapotát küldi, nem egy eseményt
Az IPN a bizonylat küldéskori állapotát tartalmazza: a szlahu_kifizetettbrutto az addigi kifizetések együttes összege, nem az utolsó befizetés. Ezért a fogadó oldalon az értékeket írd felül, ne add hozzá a korábbiakhoz. Így egy késve vagy ismételten érkező IPN sem okoz eltérést.
Hitelesítés
Az IPN kérés nem tartalmaz aláírást vagy más hitelesítő adatot. Az IP-szűrés mellett ezért javasoljuk, hogy az IPN URL-be tegyél egy csak általad ismert titkos tokent (HTTPS-en), és beérkezéskor kérd le a bizonylatot az action-szamla_agent_xml hívással, hogy az adatokat ellenőrizd.
⚠️ Fontos megjegyzések
Újrapróbálási mechanizmus
Az IPN üzenetek nem azonnal kerülnek elküldésre: a rendszer 3 percenként küldi ki a várakozó kifizetettségi információkat. Hogy egy sikertelen küldést újrapróbál-e, az attól függ, kapott-e HTTP választ a fogadó szervertől:
- Érkezik HTTP válasz, de nem 200-as (például 301, 403, 404, 500, 503): a küldés lezárul, a rendszer a kapott státuszkódot rögzíti, és az IPN-t nem küldi újra.
- Nem érkezik HTTP válasz (időtúllépés, elutasított kapcsolat, DNS-hiba, megszakadt kapcsolat): a rendszer újrapróbálja a küldést. Összesen legfeljebb 11 próbálkozás történik (1 küldés és 10 újrapróbálkozás), utána az IPN-t eldobja.
Hiba esetén se adj vissza 200-tól eltérő HTTP kódot abban a hitben, hogy az IPN-t később újra megkapod, mert a rendszer ilyenkor nem küldi újra. Ha nálad sikertelen a feldolgozás, a bizonylat aktuális állapotát az action-szamla_agent_xml hívással kérheted le.
IPN üzenetek felhalmozódása
A küldő rendszerben (Számlázz.hu) feltorlódhatnak az IPN kérések, különösen nagy forgalom esetén. Ezek az üzenetek idővel automatikusan kiküldésre kerülnek a fogadó rendszer felé. A rendszer csak azokat az IPN-eket veszi elő, amelyeket az elmúlt 5 napban hozott létre vagy próbált elküldeni, a régebbieket már nem küldi ki.
Duplikált üzenetek kezelése
A rendszer biztosítja, hogy ugyanahhoz a bizonylathoz csak egy aktív IPN üzenet legyen egyszerre. Ha egy bizonylathoz több IPN rekord tartozik, csak a legfrissebb kerül elküldésre, a többi automatikusan törlődik.
🌐 IP címek és hálózati beállítások
Az IPN üzenetek a következő IP címekről érkeznek:
3.73.214.98
3.76.149.232
18.153.156.51
Ha IP-alapú szűrést használsz, ezeket a címeket add hozzá a whitelist-hez.
A korábbi IP címek (18.153.1.171, 3.73.114.72, 52.59.28.5) 2025. augusztus 1-től már nem használatosak.
Részletes információ: Technológiai változások 2025