Pengenalan API Stripe untuk Java

1. Gambaran keseluruhan

Stripe adalah perkhidmatan berasaskan awan yang membolehkan perniagaan dan individu menerima pembayaran melalui internet dan menawarkan perpustakaan sisi pelanggan (JavaScript dan mudah alih asli) dan perpustakaan sisi pelayan (Java, Ruby, Node.js, dll.).

Stripe memberikan lapisan abstraksi yang mengurangkan kerumitan penerimaan pembayaran. Akibatnya, kami tidak perlu mengurus butiran kad kredit secara langsung - sebaliknya, kami berurusan dengan token yang melambangkan kebenaran untuk mengenakan bayaran .

Dalam tutorial ini, kami akan membuat contoh projek Spring Boot yang membolehkan pengguna memasukkan kad kredit dan kemudian akan mengenakan kad untuk jumlah tertentu menggunakan Stripe API untuk Java.

2. Kebergantungan

Untuk memanfaatkan Stripe API untuk Java dalam proyek, kami menambahkan ketergantungan yang sesuai ke pom.xml kami :

 com.stripe stripe-java 4.2.0  

Kita boleh mendapatkan versi terbarunya di repositori Maven Central.

Untuk projek sampel kami, kami akan memanfaatkan ibu bapa spring-boot-starter :

 org.springframework.boot spring-boot-starter-parent 2.2.6.RELEASE 

Kami juga akan menggunakan Lombok untuk mengurangkan kod plat boiler, dan Thymeleaf akan menjadi mesin templat untuk menyampaikan laman web yang dinamis.

Oleh kerana kami menggunakan induk spring-boot-starter untuk menguruskan versi perpustakaan ini, kami tidak perlu memasukkan versi mereka dalam pom.xml :

 org.springframework.boot spring-boot-starter-web   org.springframework.boot spring-boot-starter-thymeleaf   org.projectlombok lombok 

Perhatikan bahawa jika anda menggunakan NetBeans, anda mungkin ingin menggunakan Lombok secara eksplisit dengan versi 1.16.16 , kerana bug dalam versi Lombok yang disertakan dengan Spring Boot 1.5.2 menyebabkan NetBeans menghasilkan banyak kesalahan.

3. Kekunci API

Sebelum kita dapat berkomunikasi dengan Stripe dan melaksanakan caj kad kredit, kita perlu mendaftarkan akaun Stripe dan mendapatkan kunci Stripe API rahsia / awam .

Setelah mengesahkan akaun, kami akan log masuk untuk mengakses papan pemuka Stripe. Kami kemudian memilih "kekunci API" di menu sebelah kiri:

Terdapat dua pasang kunci rahsia / awam - satu untuk ujian dan satu untuk siaran langsung. Biarkan tab ini terbuka agar kita dapat menggunakan kekunci ini kemudian.

4. Aliran Am

Bayaran kad kredit akan dilakukan dalam lima langkah mudah, merangkumi bahagian depan (dijalankan di penyemak imbas), bahagian belakang (aplikasi Spring Boot kami), dan Stripe:

  1. Seorang pengguna pergi ke halaman pembayaran dan mengklik "Bayar dengan Kad".
  2. Seorang pengguna disajikan dengan dialog overlay Stripe Checkout, di mana mengisi butiran kad kredit.
  3. Pengguna mengesahkan dengan "Bayar" yang akan:
    • Hantarkan kad kredit ke Stripe
    • Dapatkan token sebagai jawapan yang akan dilampirkan ke borang yang ada
    • Hantarkan borang itu dengan jumlah, kunci API awam, e-mel, dan token ke bahagian belakang kami
  4. Bahagian belakang kami menghubungi Stripe dengan token, jumlah, dan kunci API rahsia.
  5. Bahagian belakang memeriksa tindak balas Stripe dan memberi maklum balas operasi kepada pengguna.

Kami akan membahas setiap langkah dengan lebih terperinci di bahagian berikut.

5. Borang Pemeriksaan

Stripe Checkout adalah widget disesuaikan, siap bergerak, dan dapat dilokalkan yang memberikan borang untuk memperkenalkan perincian kad kredit. Melalui penyertaan dan konfigurasi " checkout.js ", pihak bertanggungjawab untuk:

  • Rendering butang "Bayar dengan Kad"

  • Perenderan dialog overlay pembayaran (dicetuskan setelah mengklik "Bayar dengan Kad")

  • Pengesahan kad kredit
  • Ciri "Ingat saya" (mengaitkan kad dengan nombor telefon bimbit)
  • Menghantar kad kredit ke Stripe dan menggantinya dengan token dalam borang lampiran (dicetuskan setelah mengklik "Bayar")

Sekiranya kita perlu menggunakan lebih banyak kawalan ke atas borang pembayaran daripada yang disediakan oleh Stripe Checkout, maka kita dapat menggunakan Stripe Elements.

Seterusnya, kami akan menganalisis pengawal yang menyediakan borang dan kemudian bentuk itu sendiri.

5.1. Pengawal

Mari mulakan dengan membuat pengawal untuk menyiapkan model dengan maklumat yang diperlukan yang diperlukan oleh borang pembayaran .

Pertama, kita perlu menyalin versi ujian kunci awam kami dari papan pemuka Stripe dan menggunakannya untuk menentukan STRIPE_PUBLIC_KEY sebagai pemboleh ubah persekitaran. Kami kemudian menggunakan nilai ini di medan stripePublicKey .

Kami juga menetapkan mata wang dan jumlah (dinyatakan dalam sen) secara manual di sini hanya untuk tujuan demonstrasi, tetapi dalam aplikasi sebenar, kami mungkin menetapkan id produk / penjualan yang dapat digunakan untuk mengambil nilai sebenarnya.

Kemudian, kami akan menghantar ke paparan pembayaran yang memegang borang pembayaran:

@Controller public class CheckoutController { @Value("${STRIPE_PUBLIC_KEY}") private String stripePublicKey; @RequestMapping("/checkout") public String checkout(Model model) { model.addAttribute("amount", 50 * 100); // in cents model.addAttribute("stripePublicKey", stripePublicKey); model.addAttribute("currency", ChargeRequest.Currency.EUR); return "checkout"; } }

Regarding the Stripe API keys, you can define them as environment variables per application (test vs. live).

As is the case with any password or sensitive information, it is best to keep the secret key out of your version control system.

5.2. Form

The “Pay with Card” button and the checkout dialog are included by adding a form with a script inside, correctly configured with data attributes:

  Price:    

The “checkout.js” script automatically triggers a request to Stripe right before the submit, which then appends the Stripe token and the Stripe user email as the hidden fields “stripeToken” and “stripeEmail“.

These will be submitted to our back-end along with the other form fields. The script data attributes are not submitted.

We use Thymeleaf to render the attributes “data-key“, “data-amount“, and “data-currency“.

The amount (“data-amount“) is used only for display purposes (along with “data-currency“). Its unit is cents of the used currency, so we divide it by 100 to display it.

The Stripe public key is passed to Stripe after the user asks to pay. Do not use the secret key here, as this is sent to the browser.

6. Charge Operation

For server-side processing, we need to define the POST request handler used by the checkout form. Let's take a look at the classes we will need for the charge operation.

6.1. ChargeRequest Entity

Let's define the ChargeRequest POJO that we will use as a business entity during the charge operation:

@Data public class ChargeRequest { public enum Currency { EUR, USD; } private String description; private int amount; private Currency currency; private String stripeEmail; private String stripeToken; }

6.2. Service

Let's write a StripeService class to communicate the actual charge operation to Stripe:

@Service public class StripeService { @Value("${STRIPE_SECRET_KEY}") private String secretKey; @PostConstruct public void init() { Stripe.apiKey = secretKey; } public Charge charge(ChargeRequest chargeRequest) throws AuthenticationException, InvalidRequestException, APIConnectionException, CardException, APIException { Map chargeParams = new HashMap(); chargeParams.put("amount", chargeRequest.getAmount()); chargeParams.put("currency", chargeRequest.getCurrency()); chargeParams.put("description", chargeRequest.getDescription()); chargeParams.put("source", chargeRequest.getStripeToken()); return Charge.create(chargeParams); } }

As was shown in the CheckoutController, the secretKey field is populated from the STRIPE_SECRET_KEY environment variable that we copied from the Stripe dashboard.

Once the service has been initialized, this key is used in all subsequent Stripe operations.

The object returned by the Stripe library represents the charge operation and contains useful data like the operation id.

6.3. Controller

Finally, let's write the controller that will receive the POST request made by the checkout form and submit the charge to Stripe via our StripeService.

Note that the “ChargeRequest” parameter is automatically initialized with the request parameters “amount“, “stripeEmail“, and “stripeToken” included in the form:

@Controller public class ChargeController { @Autowired private StripeService paymentsService; @PostMapping("/charge") public String charge(ChargeRequest chargeRequest, Model model) throws StripeException { chargeRequest.setDescription("Example charge"); chargeRequest.setCurrency(Currency.EUR); Charge charge = paymentsService.charge(chargeRequest); model.addAttribute("id", charge.getId()); model.addAttribute("status", charge.getStatus()); model.addAttribute("chargeId", charge.getId()); model.addAttribute("balance_transaction", charge.getBalanceTransaction()); return "result"; } @ExceptionHandler(StripeException.class) public String handleError(Model model, StripeException ex) { model.addAttribute("error", ex.getMessage()); return "result"; } }

On success, we add the status, the operation id, the charge id, and the balance transaction id to the model so that we can show them later to the user (Section 7). This is done to illustrate some of the contents of the charge object.

Our ExceptionHandler will deal with exceptions of type StripeException that are thrown during the charge operation.

If we need more fine-grained error handling, we can add separate handlers for the subclasses of StripeException, such as CardException, RateLimitException, or AuthenticationException.

The “result” view renders the result of the charge operation.

7. Showing the Result

The HTML used to display the result is a basic Thymeleaf template that displays the outcome of a charge operation. The user is sent here by the ChargeController whether the charge operation was successful or not:

   Result   

Success!

Id.: Status: Charge id.: Balance transaction id.: Checkout again

Setelah berjaya, pengguna akan melihat beberapa butiran operasi caj:

Pada kesilapan, pengguna akan diberikan mesej ralat seperti yang dikembalikan oleh Stripe:

8. Kesimpulannya

Dalam tutorial ini, kami telah menunjukkan cara memanfaatkan API Java Stripe untuk mengenakan kad kredit. Pada masa akan datang, kami dapat menggunakan semula kod sisi pelayan kami untuk melayani aplikasi mudah alih asli.

Untuk menguji keseluruhan aliran caj, kami tidak perlu menggunakan kad kredit sebenar (walaupun dalam mod ujian). Kita boleh bergantung pada kad ujian Stripe sebagai gantinya.

Operasi caj adalah salah satu daripada banyak kemungkinan yang ditawarkan oleh Stripe Java API. Rujukan API rasmi akan membimbing kami melalui keseluruhan rangkaian operasi.

Contoh kod yang digunakan dalam tutorial ini boleh didapati di projek GitHub.