Payment Intents API

Gunakan API Payment Intents untuk membangun integrasi yang dapat menangani alur pembayaran rumit dengan status yang berubah selama daur hidup PaymentIntent. API ini melacak pembayaran mulai dari pembuatan hingga checkout, dan memicu langkah-langkah autentikasi tambahan bila diperlukan.

Beberapa keuntungan menggunakan Payment Intents API termasuk:

• Penanganan autentikasi otomatis
• Tidak ada charge ganda
• Tidak ada masalah kunci idempotensi
• Dukungan untuk Autentikasi Pelanggan yang Kuat (SCA) dan perubahan regulasi serupa

Serangkaian API lengkap

Gunakan Payment Intents API bersama Setup Intents API dan Payment Methods API. API ini membantu Anda menangani pembayaran dinamis (misalnya, autentikasi tambahan seperti 3D Secure) serta membantu persiapan ekspansi ke negara lain sekaligus memungkinkan Anda mendukung regulasi baru dan metode pembayaran regional.

Pembuatan integrasi dengan Payment Intents API melibatkan dua tindakan: membuat dan mengonfirmasi sebuah PaymentIntent. Setiap PaymentIntent biasanya berkorelasi dengan satu keranjang belanja atau sesi pelanggan di aplikasi Anda. PaymentIntent merangkum detail transaksi, seperti metode pembayaran yang didukung, jumlah yang ditagih, dan mata uang yang diinginkan.

Membuat PaymentIntent

Untuk memulai, lihat panduan menerima pembayaran. Panduan ini menjelaskan cara membuat PaymentIntent pada server dan meneruskan client secret-nya ke client, bukan meneruskan seluruh objek PaymentIntent.

Bila Anda membuat PaymentIntent, Anda dapat menentukan opsi seperti jumlah dan mata uang:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd

Praktik terbaik

• Kami merekomendasikan pembuatan PaymentIntent segera setelah Anda mengetahui jumlahnya, seperti ketika pelanggan memulai proses checkout, untuk membantu melacak saluran pembelian. Jika jumlahnya berubah, Anda dapat memperbarui jumlahnya. Misalnya, jika mundur dari proses dan menambahkan barang baru ke keranjangnya, Anda mungkin perlu memperbarui jumlah ketika mereka memulai kembali proses checkout.

• Jika proses checkout terputus dan dilanjutkan di lain waktu, cobalah menggunakan kembali PaymentIntent yang sama, bukan membuat yang baru. Setiap PaymentIntent memiliki identifikasi unik yang dapat Anda gunakan untuk mengambilnya jika membutuhkannya lagi. Dalam model data aplikasi, Anda dapat menyimpan identifikasi PaymentIntent pada keranjang belanja atau sesi pelanggan untuk memfasilitasi pengambilan. Manfaat penggunaan kembali PaymentIntent adalah keadaan objek tersebut membantu melacak setiap upaya pembayaran yang gagal untuk keranjang atau sesi tertentu.

• Ingatlah untuk memberikan kunci idempotensi guna mencegah pembuatan duplikat PaymentIntents bagi pembelian yang sama. Kunci ini biasanya berdasarkan pada identifikasi yang dikaitkan dengan keranjang atau sesi pelanggan di aplikasi Anda.

Meneruskan client secret ke sisi client

PaymentIntent berisi client secret, satu kunci unik bagi suatu PaymentIntent. Di sisi client aplikasi Anda, client secret digunakan sebagai parameter ketika mengaktifkan fungsi Stripe.js (seperti stripe.confirmCardPayment atau stripe.handleCardAction) untuk menyelesaikan pembayaran.

Ambil client secret

PaymentIntent menyertakan client secret yang digunakan pada sisi client untuk menyelesaian proses pembayaran dengan aman. Anda dapat menggunakan pendekatan berbeda untuk meneruskan client secret ke sisi client.

get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Setelah pembayaran

Setelah client mengonfirmasikan pembayaran, praktik terbaiknya bagi server Anda adalah memonitor webhook untuk mendeteksi kapan pembayaran gagal atau berhasil diselesaikan.

Sebuah PaymentIntent dapat memiliki lebih dari satu objek Charge yang dikaitkan dengannya jika terdapat beberapa upaya pembayaran, sebagai contohnya percobaan ulang. Untuk setiap charge, Anda dapat memeriksa hasil dan detail metode pembayaran yang digunakan.

Mengoptimalkan metode pembayaran untuk pembayaran di masa mendatang

Parameter setup_future_usage menyimpan metode pembayaran untuk digunakan lagi di masa mendatang. Untuk kartu, parameter ini juga mengoptimalkan rasio otorisasi dengan mematuhi undang-undang regional dan aturan jaringan, seperti SCA. Untuk menentukan nilai yang akan digunakan, pertimbangkan cara yang Anda inginkan untuk menggunakan metode pembayaran ini di masa mendatang.

Anda masih dapat menerima pembayaran di-luar sesi dengan kartu disiapkan untuk pembayaran di-dalam sesi, tetapi bank lebih cenderung menolak pembayaran di luar sesi dan mengharuskan autentikasi dari pemegang kartu.

Contoh berikut menunjukkan cara membuat PaymentIntent dan menentukan setup_future_usage:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session

Keterangan rekening koran dinamis

Secara default, keterangan rekening koran akun Stripe Anda ditampilkan di rekening koran pelanggan setiap kali Anda men-charge kartu mereka. Untuk memberikan keterangan yang berbeda per pembayaran, sertakan parameter statement_descriptor.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d statement_descriptor="Custom descriptor"

Keterangan rekening koran dibatasi hingga 22 karakter, tidak boleh menggunakan karakter khusus <, >, ', ", atau *, dan tidak boleh hanya terdiri atas angka saja. Ketika menggunakan keterangan rekening koran dinamis, teks dinamis ditambahkan ke awalan keterangan rekening koran yang diatur di Dashboard Stripe. Tanda bintang (*) dan ruang kosong juga ditambahkan untuk memisahkan keterangan rekening koran default dari bagian dinamis. Dua karakter ini dihitung dalam batas 22 karakter.

Menyimpan informasi dalam metadata

Stripe mendukung penambahan metadata ke permintaan paling umum yang Anda buat, seperti pemrosesan pembayaran. Metadata tidak ditunjukkan kepada pelanggan atau diperhitungkan apakah pembayaran menjadi ditolak atau diblokir oleh sistem pencegahan penipuan kami.

Melalui metadata, Anda dapat mengaitkan informasi yang berarti dengan aktivitas Stripe.

Metadata yang Anda sertakan dapat dilihat di Dashboard (misalnya, saat melihat halaman untuk masing-masing pembayaran), dan juga tersedia dalam laporan umum. Misalnya, Anda dapat melampirkan identifikasi pesanan toko ke PaymentIntent yang digunakan untuk pesanan itu. Melakukan hal itu membuat Anda mudah merekonsiliasikan pembayaran di Stripe untuk pesanan di sistem.

Jika Anda menggunakan Radar for Fraud Teams, pertimbangkan penerusan informasi pelanggan tambahan dan informasi pesanan sebagai metadata. Kemudian Anda dapat menulis aturan Radar yang menggunakan atribut metadata serta memiliki ketersediaan informasi lebih banyak dalam Dashboard, yang dapat mempercepat proses tinjauan Anda.

Bila PaymentIntent membuat charge, PaymentIntent menyalin metadatanya ke charge. Pembaruan berikutnya pada metadata PaymentIntent tidak akan mengubah metadata charge yang sebelumnya dibuat oleh PaymentIntent.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d "metadata[order_id]"=6735