Bevezetés a Java Stripe API-ba
1. Áttekintés
A Stripe egy felhőalapú szolgáltatás, amely lehetővé teszi a vállalkozások és magánszemélyek számára, hogy az interneten keresztül fizetéseket kapjanak és mind kliensoldali könyvtárakat (JavaScript és natív mobil), mind szerveroldali könyvtárakat (Java, Ruby, Node.js stb.) kínál.
A csík egy olyan absztrakciós réteget biztosít, amely csökkenti a kifizetések fogadásának összetettségét. Ennek eredményeként nem kell közvetlenül a hitelkártya adataival foglalkoznunk - ehelyett egy tokennel foglalkozunk, amely a terhelés engedélyezését szimbolizálja.
Ebben az oktatóanyagban elkészítünk egy Spring Boot projektet, amely lehetővé teszi a felhasználók számára, hogy hitelkártyát adjanak meg, majd később egy bizonyos összeget felszámolnak a kártyán a Java Stripe API segítségével.
2. Függőségek
A Stripe API Java használatához a projektben hozzáadjuk a megfelelő függőséget pom.xml:
com.stripe stripe-java 4.2.0
Legfrissebb verzióját a Maven Central adattárban találjuk meg.
Mintaprojektünknél a tavasz-bakancs-induló-szülő:
org.springframework.boot spring-boot-starter-parent 2.2.6.KÖZLEMÉNY
A kazánlap kódjának csökkentésére a Lombokot is felhasználjuk, és a Thymeleaf lesz a sablon motor a dinamikus weboldalak kézbesítéséhez.
Mivel a tavasz-bakancs-induló-szülő e könyvtárak verzióinak kezeléséhez nem kell feltüntetnünk a verzióikat pom.xml:
org.springframework.boot spring-boot-starter-web org.springframework.boot spring-boot-starter-thymeleaf org.projectlombok lombok
Vegye figyelembe, hogy ha NetBeans-t használ, érdemes a Lombokot kifejezetten az 1.16.16-os verzióval használni, mivel a Lombok Spring Boot 1.5.2-vel ellátott verziójának hibája sok hibát generál a NetBeans számára.
3. API kulcsok
Mielőtt kommunikálni tudnánk a Stripe-lal és teljesítenénk a hitelkártya-díjakat, meg kell tennünk regisztráljon Stripe fiókot, és szerezzen be titkos / nyilvános Stripe API kulcsokat.
A fiók megerősítése után bejelentkezünk, hogy hozzáférjünk a Stripe műszerfalához. Ezután az „API kulcsok” lehetőséget választjuk a bal oldali menüben:
Két pár titkos / nyilvános kulcs lesz - egy tesztre és egy élő. Hagyjuk nyitva ezt a lapot, hogy később használhassuk ezeket a gombokat.
4. Általános áramlás
A hitelkártya felszámolása öt egyszerű lépésben történik, beleértve a kezelőfelületet (futtatható böngészőben), a háttéroldalt (a Spring Boot alkalmazásunkat) és a Csíkot:
- A felhasználó a fizetési oldalra lép és a „Fizetés kártyával” gombra kattint.
- A felhasználó számára megjelenik a Csíkos fizetés átfedés párbeszédpanel, ahol kitölti a hitelkártya adatait.
- A felhasználó a „Fizetéssel” megerősíti, amely:
- Küldje el a hitelkártyát a Stripe-nek
- Kapjon egy tokent a válaszban, amelyet a meglévő űrlaphoz csatolnak
- Küldje el ezt az űrlapot az összeggel, a nyilvános API-kulccsal, az e-mail címmel és a tokennel a háttérünkbe
- Háttér-kapcsolataink csíkkal látják el a tokent, az összeget és a titkos API kulcsot.
- Háttér-ellenőrzések Csík válasz és visszajelzést ad a felhasználónak a műveletről.
Minden lépést részletesebben a következő szakaszokban tárgyalunk.
5. Pénztár űrlap
A Stripe Checkout egy testreszabható, mobilkész és lokalizálható widget, amely űrlapot nyújt a hitelkártyaadatok megadásához. A „checkout.js„, Felelős a következőkért:
- A „Kártyával történő fizetés” gomb megjelenítése
- Fizetési fedvény párbeszédpanel-megjelenítés (a „Kártyával történő fizetés” gombra kattintás után aktiválódik)
- Hitelkártya érvényesítése
- „Emlékezzen rám” funkció (a kártyát egy mobilszámhoz társítja)
- A hitelkártya elküldése a Stripe-nek, és helyettesítése egy tokennel a mellékelt űrlapon (a „Fizetés” gombra kattintás után vált ki)
Ha nagyobb ellenőrzést kell gyakorolnunk a fizetési űrlap felett, mint amit a Stripe Checkout biztosít, akkor használhatjuk a Stripe Elements elemeket.
Ezután elemezzük az űrlapot előkészítő vezérlőt, majd magát az űrlapot.
5.1. Vezérlő
Kezdjük azzal, hogy létrehozunk egy vezérlőt a készítse el a modellt a pénztárhoz szükséges információkkal.
Először is meg kell másolja a nyilvános kulcs teszt verzióját a Stripe irányítópultról és használja a STRIPE_PUBLIC_KEY mint környezeti változó meghatározását. Ezután ezt az értéket használjuk a stripePublicKey terület.
Mi is beállítunk valuta és összeg (centben kifejezve) itt manuálisan, pusztán demonstrációs célokra, de egy valós alkalmazásban beállíthatunk egy termék / értékesítési azonosítót, amely felhasználható a tényleges értékek lekérésére.
Ezután elküldjük a pénztár nézetbe, amely a fizetési űrlapot tartalmazza:
@Controller public class CheckoutController {@Value ("$ {STRIPE_PUBLIC_KEY}") private String stripePublicKey; @RequestMapping ("/ checkout") public String checkout (Model model) {model.addAttribute ("összeg", 50 * 100); // centben model.addAttribute ("stripePublicKey", stripePublicKey); model.addAttribute ("valuta", ChargeRequest.Currency.EUR); return "pénztár"; }}
A Stripe API kulcsokkal kapcsolatban meghatározhatja őket környezeti változóként alkalmazásonként (teszt vs. élő).
Mint minden jelszó vagy bizalmas információ esetén, a legjobb, ha a titkos kulcsot nem tartalmazza a verziókezelő rendszer.
5.2. Forma
A „Fizetés kártyával” gomb és a fizetési párbeszédablak hozzáadhatók egy űrlappal, benne szkriptel, helyesen konfigurálva adatattribútumokkal:
Ár:
A "checkout.js”Parancsfájl közvetlenül a beküldés előtt automatikusan elindít egy kérést a csíkról, amely aztán a rejtett mezőként csatolja a csík tokent és a csík felhasználói e-mailt.csíkToken”És„stripeEmail“.
Ezeket a többi űrlapmezővel együtt beküldjük a háttérünkbe. A szkript adatattribútumai nincsenek elküldve.
A Thymeleaf-et használjuk az „adatkulcs“, “adatmennyiség"És"adat-pénznem“.
A mennyiség ("adatmennyiség„) Csak megjelenítési célokra használható (a„adat-pénznem“). Egysége a felhasznált pénznem centje, ezért a megjelenítéséhez elosztjuk 100-zal.
A Stripe nyilvános kulcsot továbbítják a Stripe-nek, miután a felhasználó fizetést kér. Ne használja itt a titkos kulcsot, mert azt elküldi a böngészőnek.
6. Töltési művelet
A kiszolgálóoldali feldolgozáshoz meg kell határoznunk a pénztár űrlap által használt POST kérés kezelőt. Vessünk egy pillantást azokra az osztályokra, amelyekre szükségünk lesz a töltési művelethez.
6.1. ChargeRequest entitás
Határozzuk meg a ChargeRequest POJO, amelyet üzleti egységként fogunk használni a töltési művelet során:
@Data nyilvános osztály ChargeRequest {public enum Pénznem {EUR, USD; } privát karakterlánc leírása; magán int összeg; privát pénznem; privát karakterlánc csíkEmail; privát karakterlánc csíkToken; }
6.2. Szolgáltatás
Írjunk egy StripeService osztályba közölje a tényleges töltési műveletet a csíkkal:
@Service public class StripeService {@Value ("$ {STRIPE_SECRET_KEY}") private String secretKey; @PostConstruct public void init () {Stripe.apiKey = secretKey; } public Charge charge (ChargeRequest chargeRequest) dobja az AuthenticationException, InvalidRequestException, APIConnectionException, CardException, APIException {Map chargeParams = new HashMap (); chargeParams.put ("összeg", chargeRequest.getAmount ()); chargeParams.put ("valuta", chargeRequest.getCurrency ()); chargeParams.put ("leírás", chargeRequest.getDescription ()); chargeParams.put ("forrás", chargeRequest.getStripeToken ()); return Charge.create (chargeParams); }}
Amint az a CheckoutController, a titkos kulcs mezőt a STRIPE_SECRET_KEY környezeti változó tölti ki, amelyet a Stripe irányítópultról másoltunk.
A szolgáltatás inicializálása után ezt a kulcsot minden későbbi Csík művelet során felhasználjuk.
A Stripe könyvtár által visszaadott objektum a töltési műveletet reprezentálja, és hasznos adatokat tartalmaz, például a művelet azonosítóját.
6.3. Vezérlő
Végül írjuk meg a vezérlő, amely megkapja a fizetési űrlap által küldött POST kérést, és benyújtja a díjat a Stripe-hez a mi StripeService.
Vegye figyelembe, hogy aChargeRequest”Paraméter automatikusan inicializálódik a„összeg“, “stripeEmail"És"csíkToken”Formában:
@Controller public class ChargeController {@Autowired private StripeService paymentsService; @PostMapping ("/ charge") public String töltés (ChargeRequest chargeRequest, Model model) dobja a StripeException {chargeRequest.setDescription ("Példa töltés"); chargeRequest.setCurrency (Currency.EUR); Díjdíj = paymentsService.charge (chargeRequest); model.addAttribute ("id", charge.getId ()); model.addAttribute ("status", charge.getStatus ()); model.addAttribute ("chargeId", charge.getId ()); model.addAttribute ("egyenleg_tranzakció", charge.getBalanceTransaction ()); return "eredmény"; } @ExceptionHandler (StripeException.class) public String handleError (Model model, StripeException ex) {model.addAttribute ("hiba", ex.getMessage ()); return "eredmény"; }}
A sikerhez hozzáadjuk az állapotot, a művelet azonosítóját, a terhelés azonosítóját és az egyenleg tranzakció azonosítóját a modellhez, hogy később később megmutathassuk a felhasználónak (7. szakasz). Ez a töltési objektum néhány tartalmának szemléltetésére szolgál.
A mi ExceptionHandler típusú kivételekkel fog foglalkozni StripeException amelyeket a töltési művelet során dobnak el.
Ha részletesebb hibakezelésre van szükségünk, külön kezelőket adhatunk a StripeException, mint például CardException, RateLimitException, vagy AuthenticationException.
A "eredmény”Nézet a töltési művelet eredményét adja.
7. Az eredmény megjelenítése
Az eredmény megjelenítéséhez használt HTML egy alap Thymeleaf sablon, amely megjeleníti a töltési művelet eredményét. A felhasználót ide küldte a ChargeController hogy a töltési művelet sikeres volt-e vagy sem:
Eredmény Siker!
Id .: Állapot: Díj azonosító: Egyenleg tranzakció azonosító: Pénztár ismét
A siker után a felhasználó meglátja a töltési művelet néhány részletét:
Hiba esetén a felhasználónak megjelenik a Csík által visszaadott hibaüzenet:
8. Következtetés
Ebben az oktatóanyagban bemutattuk, hogyan lehet a Stripe Java API-t használni hitelkártya terheléséhez. A jövőben újból felhasználhatnánk szerveroldali kódunkat natív mobilalkalmazás kiszolgálására.
A teljes terhelés teszteléséhez nincs szükségünk valódi hitelkártyára (még teszt üzemmódban is). A Stripe tesztkártyákra támaszkodhatunk.
A töltési művelet egyike a Stripe Java API által kínált számos lehetőségnek. A hivatalos API referencia végigvezeti a műveleteket.
Az oktatóanyagban használt mintakód a GitHub projektben található.