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:

  1. A felhasználó a fizetési oldalra lép és a „Fizetés kártyával” gombra kattint.
  2. A felhasználó számára megjelenik a Csíkos fizetés átfedés párbeszédpanel, ahol kitölti a hitelkártya adatait.
  3. 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
  4. Háttér-kapcsolataink csíkkal látják el a tokent, az összeget és a titkos API kulcsot.
  5. 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ó.