SimplePay integráció

Mi a SimplePay?

Az OTP SimplePay egy magyar online bankkártyás fizetési szolgáltatás. A vásárló a SimplePay biztonságos fizetőoldalán fizet, a pénz a te kereskedői fiókodba érkezik.

Mire használhatod a Suarában?

Ha összekötöd a SimplePay-t, az appod bankkártyás fizetést fogadhat. Néhány példa:

• Webshop: a kosár tartalmáért a vásárló a SimplePay fizetőoldalán fizet, majd visszatér az oldaladra.

• Foglalás előleggel: a vendég a foglalás véglegesítése előtt kifizeti az előleget.

• Szolgáltatás- vagy jegyeladás: az app a sikeres fizetés után aktiválja a hozzáférést vagy elküldi a jegyet.

• Visszatérítés: egy lemondott rendelés összegét az app visszautalja.

Az AI az alábbi műveleteket használja:

• Fizetés indítása: létrehozza a fizetést, és visszaad egy fizetőoldal-címet, ahová a vásárlót át kell irányítani.

• Fizetés állapotának lekérdezése: megmutatja, hogy a fizetés sikeres, függőben lévő, megszakított, lejárt, sikertelen vagy visszatérített.

• Visszatérítés: egy sikeres fizetés összegét részben vagy egészben visszautalja.

• IPN-értesítés feldolgozása: a SimplePay szerverről szerverre jelzi, ha egy fizetés állapota változott. A Suara fogadja és ellenőrzi az értesítést, de csak akkor, ha a SimplePay adminban beállítottad az IPN URL-t (lásd lent). Ha a Suara Cloud be van kapcsolva, az appodat is értesíti.

Teszt és éles környezet

A SimplePay két külön környezetet kínál, és a kapcsolat mentésekor ki kell választanod, melyiket használod:

• Sandbox: a SimplePay tesztkörnyezete. Itt valódi pénz nélkül kipróbálhatod az egész fizetési folyamatot. Az alapértelmezett környezet ez.

• Éles: valódi fizetések, valódi pénz.

Biztonság

A kereskedői titkos kulcs (SECRET_KEY) titkosítva, a Suara szerverén marad. A generált app sosem látja, és a böngészőbe sem kerül. Az app a Suara gatewayen keresztül hívja a SimplePay-t, a gateway pedig a háttérben hozzáadja a hitelesítő adatokat. A kapcsolatot a láthatóság beállításával korlátozhatod: Csak én, Csak kiválasztott tagok vagy Az egész munkaterület.

Jóváhagyás: mivel pénzmozgásról van szó, a fizetési művelet (fizetés indítása, visszatérítés) a chatben minden alkalommal a jóváhagyásodat kéri. Ehhez a kapcsolathoz nincs „mindig engedélyezem” beállítás. Az állapot-lekérdezés jóváhagyás nélkül fut.

Beállítás lépésről lépésre

1. Szerezd meg a kereskedői azonosítót és a titkos kulcsot a SimplePayben

1. Jelentkezz be a SimplePay adminfelületére: éleshez a SimplePay éles adminja, teszthez a sandbox admin https://sandbox.simplepay.hu/admin/.

2. Nyisd meg a Fiók → Technikai adatok oldalt.

3. Másold ki a MERCHANT (kereskedői azonosító) és a SECRET_KEY (titkos kulcs) értékét.

2. Kösd be a Suarában

1. A Suara oldalsávjában nyisd meg az Integrációk oldalt.

2. A Katalógusban keresd meg a SimplePay-t. A Fizetés kategóriában találod, vagy használhatod a keresőt (Integráció keresése…).

3. Kattints a Csatlakoztatás gombra. Megnyílik a „SimplePay csatlakoztatása” ablak.

4. Töltsd ki a mezőket:

   • Környezet: Sandbox vagy Éles. Az alapértelmezett a Sandbox. A kulcsoknak ahhoz a környezethez kell tartozniuk, amelyet kiválasztasz.

   • Kereskedői azonosító (MERCHANT): a másolt MERCHANT azonosító.

   • Titkos kulcs (SECRET_KEY): a másolt titkos kulcs.

   A beillesztett titkos érték a Kulcs megjelenítése ikonnal ellenőrizhető. A Hol találom? hivatkozás a szolgáltatás megfelelő oldalára visz.

5. Válaszd ki, ki használhatja a kapcsolatot (Csak én vagy Az egész munkaterület). Ha a teljes munkaterületnek engedélyezed, a Suara figyelmeztet, hogy minden tag használhatja a kapcsolatot a saját projektjeiben. Ennél az integrációnál ez azt jelenti, hogy az ő appjaik is fogadhatnak fizetést a te SimplePay-fiókodba.

6. Kattints a Mentés és ellenőrzés gombra. A Suara ellenőrzi az adatokat a SimplePaynél, és ha érvényesek, a kapcsolat SimplePay · {kereskedői azonosító} néven megjelenik a Kapcsolataid között.

3. Állítsd be az IPN URL-t a SimplePay adminban

A Barionnal és a Stripe-pal ellentétben a SimplePay nem kapja meg automatikusan a Suara értesítési címét, ezt egyszer be kell másolnod:

1. Mentés után nyisd meg az Integrációk → Kapcsolataid alatt a SimplePay kapcsolatot, és másold ki a Callback URL-t.

2. Illeszd be a SimplePay adminban a Beállítások → IPN URL mezőbe.

3. Ezt kapcsolatonként egyszer kell megtenni, a sandbox és az éles adminban külön.

4. Használd a projektedben

Három módon használhatod a kapcsolatot:

• A chatben kérve: írd le az AI-nak, mit szeretnél, például „Építs egy webshop-kosarat, amelyben a vásárló bankkártyával fizet a SimplePayjel, és a sikeres fizetés után a rendelés állapota Fizetve lesz.” Ha még nincs kapcsolat, az AI felkínálja a csatlakoztatást.

• Az Integrációk oldalról: a Kapcsolataid között a SimplePay mellett a Bekötés az appba gombbal kötheted be a kapcsolatot egy projektbe.

• A projekt Kapcsolatok oldaláról: nyisd meg a projekt Kapcsolatok részét, és kattints a Kapcsolat gombra. Ott a Munkaterület kapcsolatai közül választhatsz egy meglévőt, vagy az Új bekötése gombbal újat hozhatsz létre.

A bekötés után az AI a SimplePay-hívásokat (fizetés indítása, állapot, visszatérítés) az app szerveroldali (edge function) részében generálja. A hitelesítő adatok így nem kerülnek a kódba, és a kapcsolatot szükség esetén a projekt Kapcsolatok oldaláról bármikor leválaszthatod.

Kapcsolat kezelése

Az Integrációk → Kapcsolataid alatt a SimplePay kapcsolatra kattintva elérhető:

• Alapadatok: az elnevezés és a láthatóság módosítása.

• Kulcsok frissítése: új kereskedői azonosító, titkos kulcs vagy környezet mentése.

• Kapcsolt projektek: itt látod, mely projektek használják a kapcsolatot.

• Utolsó hívások: itt látod a legutóbbi hívásokat (metódus, útvonal, státusz, időtartam, forrás: alkalmazás vagy chat).

• Leválasztás (Veszélyzóna): megszünteti a kapcsolatot. A hozzá kötött projektek ezután nem érik el a SimplePay-t.

A státusz lehet Aktív, Hiba vagy Visszavonva. Ha Újracsatlakozás szükséges üzenetet látsz, mentsd újra a kulcsot.

Hibaelhárítás

• „Mentés és ellenőrzés” hibával áll meg: Ellenőrizd, hogy a MERCHANT és a SECRET_KEY helyesen lett kimásolva (szóköz nélkül), és hogy a kiválasztott Környezet megegyezik azzal, ahonnan a kulcsot vetted.

• A kapcsolat „Hiba” vagy „Visszavonva” státuszú: A kulcsot lecserélték vagy letiltották. Kérj újat a SimplePay adminban, és mentsd el a Kulcsok frissítése résznél.

• Az app nem éri el a SimplePay-t: Ellenőrizd, hogy a kapcsolat be van-e kötve a projektbe, és hogy a Suara Cloud be van-e kapcsolva.

• Nem jön értesítés (IPN): Ellenőrizd, hogy a Callback URL be van-e másolva a SimplePay admin IPN URL mezőjébe, a megfelelő (sandbox vagy éles) adminban.

• Sikeres fizetés, de a rendelés nem frissül: Az appnak a SimplePay szerverről kapott állapotot kell használnia, nem a vásárló böngészőjének visszatérését. Kérd meg az AI-t, hogy az állapotot a SimplePay lekérdezésével és az IPN-értesítéssel állapítsa meg.

• A chat jóváhagyást kér: Pénzmozgásnál (fizetés indítása, visszatérítés) a chat minden alkalommal a jóváhagyásodat kéri. Ez szándékos.