Pengantar API Stripe untuk Java

1. Ikhtisar

Stripe adalah layanan berbasis cloud yang memungkinkan bisnis dan individu menerima pembayaran melalui internet dan menawarkan perpustakaan sisi klien (JavaScript dan seluler asli) dan perpustakaan sisi server (Java, Ruby, Node.js, dll.).

Stripe menyediakan lapisan abstraksi yang mengurangi kerumitan dalam menerima pembayaran. Akibatnya, kami tidak perlu berurusan dengan detail kartu kredit secara langsung - sebagai gantinya, kami menangani token yang melambangkan otorisasi untuk menagih .

Dalam tutorial ini, kami akan membuat contoh proyek Spring Boot yang memungkinkan pengguna memasukkan kartu kredit dan kemudian akan menagih kartu tersebut untuk jumlah tertentu menggunakan API Stripe untuk Java.

2. Dependensi

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

 com.stripe stripe-java 4.2.0  

Kami dapat menemukan versi terbarunya di repositori Maven Central.

Untuk proyek sampel kami, kami akan memanfaatkan spring-boot-starter-parent :

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

Kami juga akan menggunakan Lombok untuk mengurangi kode boilerplate, dan Thymeleaf akan menjadi mesin template untuk menampilkan halaman web dinamis.

Karena kami menggunakan spring-boot-starter-parent untuk mengelola versi pustaka ini, kami tidak perlu menyertakan versinya di pom.xml :

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

Perhatikan bahwa jika Anda menggunakan NetBeans, Anda mungkin ingin menggunakan Lombok secara eksplisit dengan versi 1.16.16 , karena bug di versi Lombok yang disertakan dengan Spring Boot 1.5.2 menyebabkan NetBeans menghasilkan banyak kesalahan.

3. Kunci API

Sebelum kami dapat berkomunikasi dengan Stripe dan mengeksekusi tagihan kartu kredit, kami perlu mendaftarkan akun Stripe dan mendapatkan kunci API Stripe rahasia / publik .

Setelah mengonfirmasi akun, kami akan masuk untuk mengakses dasbor Stripe. Kami kemudian memilih "kunci API" di menu sisi kiri:

Akan ada dua pasang kunci rahasia / publik - satu untuk pengujian dan satu untuk live. Biarkan tab ini terbuka sehingga kita dapat menggunakan kunci ini nanti.

4. Arus Umum

Tagihan kartu kredit akan dilakukan dalam lima langkah sederhana, yang melibatkan front-end (dijalankan di browser), back-end (aplikasi Spring Boot kami), dan Stripe:

  1. Seorang pengguna pergi ke halaman pembayaran dan mengklik "Bayar dengan Kartu".
  2. Seorang pengguna disajikan dengan dialog hamparan Stripe Checkout, di mana mengisi detail kartu kredit.
  3. Seorang pengguna mengonfirmasi dengan "Bayar" yang akan:
    • Kirim kartu kredit ke Stripe
    • Dapatkan token dalam respons yang akan ditambahkan ke formulir yang ada
    • Kirimkan formulir itu dengan jumlah, kunci API publik, email, dan token ke back-end kami
  4. Kontak back-end kami, Stripe, dengan token, jumlah, dan kunci API rahasia.
  5. Pemeriksaan back-end Stripe respon dan memberikan pengguna dengan umpan balik operasi.

Kami akan membahas setiap langkah secara lebih rinci di bagian berikut.

5. Formulir Pembayaran

Stripe Checkout adalah widget yang dapat disesuaikan, siap seluler, dan dapat dilokalkan yang membuat formulir untuk memperkenalkan detail kartu kredit. Melalui penyertaan dan konfigurasi " checkout.js ", ini bertanggung jawab untuk:

  • Rendering tombol “Bayar dengan Kartu”

  • Rendering dialog pembayaran overlay (dipicu setelah mengklik "Bayar dengan Kartu")

  • Validasi kartu kredit
  • Fitur "Ingat saya" (mengaitkan kartu dengan nomor ponsel)
  • Mengirim kartu kredit ke Stripe dan menggantinya dengan token dalam formulir terlampir (dipicu setelah mengklik "Bayar")

Jika kita perlu melakukan lebih banyak kontrol atas formulir pembayaran daripada yang disediakan oleh Stripe Checkout, maka kita dapat menggunakan Elemen Strip.

Selanjutnya, kita akan menganalisis pengontrol yang menyiapkan formulir dan kemudian formulir itu sendiri.

5.1. Kontroler

Mari kita mulai dengan membuat pengontrol untuk menyiapkan model dengan informasi yang diperlukan yang dibutuhkan formulir checkout .

Pertama, kita perlu menyalin versi uji kunci publik kita dari dasbor Stripe dan menggunakannya untuk menentukan STRIPE_PUBLIC_KEY sebagai variabel lingkungan. Kami kemudian menggunakan nilai ini di bidang stripePublicKey .

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

Kemudian, kami akan mengirimkan ke tampilan pembayaran yang menyimpan formulir 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

Jika berhasil, pengguna akan melihat beberapa detail operasi pengisian daya:

Jika terjadi kesalahan, pengguna akan melihat pesan kesalahan seperti yang dikembalikan oleh Stripe:

8. Kesimpulan

Dalam tutorial ini, kami telah menunjukkan cara menggunakan API Java Stripe untuk menagih kartu kredit. Di masa mendatang, kami dapat menggunakan kembali kode sisi server kami untuk menyajikan aplikasi seluler asli.

Untuk menguji seluruh aliran tagihan, kami tidak perlu menggunakan kartu kredit asli (bahkan dalam mode uji). Sebagai gantinya, kami dapat mengandalkan kartu pengujian Stripe.

Operasi biaya adalah salah satu dari banyak kemungkinan yang ditawarkan oleh API Java Stripe. Referensi API resmi akan memandu kita melalui seluruh rangkaian operasi.

Kode sampel yang digunakan dalam tutorial ini dapat ditemukan di proyek GitHub.