Stripe integráció

Mi az a Stripe?

A Stripe egy nemzetközi online fizetési platform. Bankkártyás és más online fizetési módokat, ismétlődő előfizetéseket és számlázást kezel. Jó választás nemzetközi vásárlókhoz és előfizetéses szolgáltatásokhoz.

Mire használhatod a Suarában?

Ha összekötöd a Stripe-ot, az appod online fizetést és előfizetést kezelhet. Néhány példa:

• Webshop: a vásárló a Stripe Checkout fizetőoldalán fizet, majd visszatér az oldaladra.

• Előfizetéses szolgáltatás: havi vagy éves előfizetés, amely automatikusan megújul.

• Termékkatalógus: az app a Stripe-ban felvett termékeket és árakat jeleníti meg.

• Fizetés utáni automatizmus: a sikeres fizetés után az app aktiválja a hozzáférést vagy a rendelést.

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

• Checkout-munkamenet létrehozása: elindítja az egyszeri vagy előfizetéses fizetést, és visszaad egy fizetőoldal-címet, ahová a vásárlót át kell irányítani.

• Termékek és árak lekérdezése és létrehozása: kilistázza a meglévő termékeket és árakat, és újat is felvehet.

• Ügyfél létrehozása: új ügyfelet vesz fel a Stripe-ban.

• Fizetés állapotának lekérdezése: megmutatja, hogy egy Checkout-munkamenet kifizetett-e.

Fizetési értesítések (webhook)

Ha a Suara Cloud be van kapcsolva, a Stripe webhook automatikusan regisztrálódik: neked nem kell a Stripe-ban webhookot beállítanod, és aláírókulcsot sem kell megadnod. Az appod így értesül a következőkről:

• sikeres vagy sikertelen fizetés (Checkout és közvetlen fizetés),

• lejárt Checkout-munkamenet,

• előfizetés létrejötte, módosulása és megszűnése,

• sikeres vagy sikertelen számlafizetés.

Az értesítés hitelességét a Suara ellenőrzi, az aláírókulcs a Suaránál marad.

Biztonság

A Stripe-kulcs 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 Stripe-ot, a gateway pedig a háttérben hozzáadja a kulcsot. 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.

Ajánlott korlátozott (restricted) kulcsot használni a teljes (secret) kulcs helyett, így a kulcs csak a szükséges műveletekhez fér hozzá.

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

1. Hozd létre a Stripe-kulcsot

1. Jelentkezz be a Stripe Dashboardra, vagy regisztrálj: https://dashboard.stripe.com

2. Nyisd meg a korlátozott kulcs létrehozó oldalt: https://dashboard.stripe.com/apikeys/create. Kézzel a Developers → API keys oldalon a Create restricted key gombbal éred el.

3. Ha a Stripe megkérdezi, mire használod a kulcsot, válaszd azt, hogy egy általad épített integrációt működtet (Powering an integration you built).

4. Adj a kulcsnak nevet (például „Suara”).

5. Állítsd az alábbi jogosultságokat Write értékre:

   • Webhook Endpoints

   • Checkout Sessions

   • Products

   • Prices

   • Customers

6. Hozd létre a kulcsot (Create key). A Stripe biztonsági okból e-mailes azonosítást kérhet.

7. Másold ki a kulcsot (rk_… kezdetű).

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 Stripe-ot. 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 „Stripe csatlakoztatása” ablak.

4. Illeszd be a másolt kulcsot a Restricted key mezőbe. A beillesztett érték a Kulcs megjelenítése ikonnal ellenőrizhető. A Hol találom? hivatkozás a Stripe kulcs-létrehozó 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 Stripe-fiókodba.

6. Kattints a Mentés és ellenőrzés gombra. A Suara lekérdezi a Stripe-fiókod webhook-végpontjait, és ha a kulcs érvényes, a kapcsolat Stripe néven megjelenik a Kapcsolataid között.

3. 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 „A kosár oldalon a Fizetés gombra induljon el a Stripe Checkout.” 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 Stripe 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 Stripe-hívásokat az app szerveroldali (edge function) részében generálja. A kulcs így nem kerül a kódba, és a kapcsolatot szükség esetén a projekt Kapcsolatok oldaláról bármikor leválaszthatod.

Tudnivalók a forintról

A Stripe a forintot (HUF) kéttizedes pénznemként kezeli. Emiatt egy 4 990 Ft-os ár a Stripe-ban 499000-ként szerepel. Az AI ezt automatikusan figyelembe veszi, de ha a Stripe Dashboardon vagy az API-ban az összegeket nézed, ne lepődj meg a két extra nullán.

Kapcsolat kezelése

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

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

• Kulcsok frissítése: új kulcs mentése, ha lecserélted vagy törölted a régit.

• 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 tudnak fizetést fogadni.

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 kulcs helyesen lett kimásolva (szóköz nélkül), és hogy a korlátozott kulcsnak megvan a Webhook Endpoints jogosultsága, mert a Suara ezen keresztül ellenőrzi a kapcsolatot.

• A kapcsolat „Hiba” vagy „Visszavonva” státuszú: A kulcsot törölték vagy lejárt. Hozz létre újat a Stripe-ban, és mentsd el a Kulcsok frissítése résznél.

• Az app nem indít fizetést: Ellenőrizd, hogy a kapcsolat be van-e kötve a projektbe, és hogy a Suara Cloud be van-e kapcsolva.

• Egy művelet jogosultsági hibával fut le: A korlátozott kulcsnak hiányzik a szükséges jogosultsága. Adj Write jogot a hiányzó erőforrásra a Stripe-ban, vagy kérd meg az AI-t, hogy mondja meg, melyikre van szükség.

• A webhook nem érkezik meg: A webhook automatikus regisztrációjához be kell kapcsolni a Suara Cloudot. Kapcsold be, majd kösd be újra a kapcsolatot a projektbe.

• A teszt és az éles adatok nem látszanak egymás mellett: A Stripe tesztmódja és éles módja külön termékeket, árakat és fizetéseket kezel. A Stripe-kulcs azt a módot használja, amelyben létrehoztad.