Penanganan kesalahan
Tangkap dan berikan respons terhadap penolakan, data yang tidak valid, masalah jaringan, dan lainnya.
Stripe menawarkan berbagai jenis kesalahan. Jenis kesalahan tersebut dapat mencerminkan kejadian eksternal, seperti pembayaran yang ditolak dan gangguan jaringan, atau masalah kode, seperti panggilan API yang tidak valid.
Untuk menangani kesalahan, gunakan beberapa atau semua teknik dalam tabel di bawah ini. Apa pun teknik yang digunakan, Anda dapat menindaklanjutinya dengan respons yang direkomendasikan untuk setiap tipe kesalahan kami.
Teknik | Tujuan | Bila dibutuhkan |
---|---|---|
Gunakan nilai kesalahan | Memulihkan ketika panggilan API tidak dapat dilanjutkan | Selalu |
Pantau webhook | Bereaksi terhadap notifikasi dari Stripe | Terkadang |
Dapatkan informasi tersimpan tentang kegagalan | Selidiki masalah masa lalu dan dukung teknik lainnya | Terkadang |
Gunakan nilai kesalahan
Panggilan API di pustaka Stripe Go mengembalikan nilai hasil dan nilai kesalahan. Gunakan beberapa tugas untuk menangkap keduanya. Jika nilai kesalahan bukan nil
, berarti ada masalah nyata yang mencegah kelanjutan panggilan API.
Jika nilai kesalahan terkait dengan Stripe, Anda dapat mentransmisikannya ke objek stripe.
, yang memiliki bidang berisi keterangan masalah. Gunakan bidang Type untuk memilih respons. Dalam sejumlah kasus, Anda dapat memaksa properti Err
ke tipe kesalahan yang lebih spesifik dengan informasi tambahan.
Setelah menyiapkan penanganan pengecualian, coba pada berbagai data, termasuk kartu percobaan, untuk menyimulasikan hasil pembayaran yang berbeda.
Pantau webhook
Stripe memberi tahu Anda tentang berbagai macam masalah menggunakan webhook. Ini termasuk masalah yang tidak langsung muncul setelah panggilan API. Sebagai contoh:
- Anda kalah dalam sengketa.
- Pembayaran rutin gagal setelah berbulan-bulan keberhasilan.
- Frontend Anda mengkonfirmasi pembayaran, tetapi menjadi offline sebelum mengetahui bahwa pembayaran gagal. (Backend masih menerima notifikasi webhook, meskipun bukan yang melakukan panggilan API
Anda tidak perlu menangani setiap tipe event webhook. Bahkan, beberapa integrasi tidak menangani satu pun.
Di handler webhook Anda, mulai dengan langkah-langkah dasar dari pembangun webhook: dapatkan objek kejadian dan gunakan tipe kejadian untuk mengetahui apa yang terjadi. Kemudian, jika tipe kejadian mengindikasikan kesalahan, ikuti langkah-langkah ekstra ini:
- Dapatkan objek yang terpengaruh dengan membongkar data dari
event.
.Data. Raw - Gunakan informasi tersimpan pada objek yang terpengaruh untuk mendapatkan konteks, termasuk objek kesalahan.
- Gunakan tipenya untuk memilih respons.
Untuk mencoba cara integrasi menanggapi kejadian webhook, Anda dapat memicu kejadian webhook secara lokal. Setelah menyelesaikan langkah-langkah penyiapan di tautan itu, picu pembayaran yang gagal untuk melihat pesan kesalahan yang dihasilkan.
stripe trigger payment_intent.payment_failed
A payment error occurred: Your card was declined.
Dapatkan informasi tersimpan tentang kegagalan
Banyak objek menyimpan informasi tentang kegagalan. Artinya, jika terjadi kesalahan, Anda dapat mengambil objek dan memeriksanya untuk mempelajari lebih lanjut. Dalam banyak kasus, informasi yang disimpan dalam bentuk objek kesalahan, dan Anda dapat menggunakan tipenya untuk memilih respons.
Misalnya:
- Ambil tujuan pembayaran tertentu.
- Periksa apakah telah mengalami kesalahan pembayaran dengan menentukan apakah last_payment_error kosong.
- Jika demikian, catat kesalahannya, termasuk tipenya dan objek yang terpengaruh.
Berikut adalah objek umum yang menyimpan informasi tentang kegagalan.
Objek | Atribut | Nilai |
---|---|---|
Payment Intent | last_ | Objek kesalahan |
Setup Intent | last_ | Objek kesalahan |
Invoice | last_ | Objek kesalahan |
Upaya Penyiapan | setup_ | Objek kesalahan |
Payout | failure_ | Kode kegagalan payout |
Pengembalian dana | failure_ | Kode kegagalan pengembalian dana |
Untuk mencoba kode yang menggunakan informasi tersimpan tentang kegagalan, sering kali Anda perlu menyimulasikan transaksi yang gagal. Anda dapat sering melakukannya menggunakan kartu percobaan atau nomor bank percobaan. Misalnya:
- Simulasikan pembayaran yang ditolak, untuk membuat Charges, PaymentIntents, SetupIntents, dan sebagainya yang telah gagal.
- Simulasikan payout yang gagal.
- Simulasikan pengembalian dana yang gagal.
Tipe kesalahan dan respons
Di pustaka Stripe Go, setiap objek kesalahan memiliki atribut Type
. Gunakan dokumentasi untuk setiap jenis saran tentang cara merespons.
Nama | Tipe | Keterangan |
---|---|---|
Kesalahan pembayaran | Terjadi kesalahan selama pembayaran, yang melibatkan salah satu situasi berikut: | |
Kesalahan permintaan tidak valid | Anda melakukan panggilan API dengan cara yang saat ini tidak valid. Hal ini dapat termasuk: | |
Kesalahan API | Terjadi kesalahan di pihak Stripe. (Hal ini jarang terjadi.) | |
Kesalahan idempotensi | You used an idempotency key for something unexpected, like replaying a request but passing different parameters. |
Kesalahan kartu
Kesalahan pembayaran—terkadang disebut sebagai “kesalahan kartu” karena alasan historis—mencakup beragam masalah umum. Kesalahan itu terbagi dalam tiga kategori:
- Pembayaran yang diblokir karena dugaan penipuan
- Pembayaran yang ditolak oleh penerbit
- Kesalahan pembayaran lainnya
To distinguish these categories or get more information about how to respond, consult the error code, decline code, and charge outcome.
(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)
Users on API version 2022-08-01 or older:
(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)
Anda dapat memicu beberapa jenis kesalahan pembayaran yang umum dengan kartu percobaan. Lihat daftar ini untuk mengetahui opsinya:
Kode percobaan di bawah ini memperagakan beberapa kemungkinan.
Diblokir karena dugaan penipuan
Tipe |
|
Kode |
|
Kode |
|
Masalah | Sistem pencegahan penipuan Stripe, Radar, memblokir pembayaran |
Solusi | Kesalahan ini dapat terjadi bila integrasi Anda berfungsi dengan benar. Tangkap kesalahan dan minta agar pelanggan menggunakan metode pembayaran berbeda. Untuk meminimalkan pemblokiran pembayaran yang sah, cobalah ini:
Pelanggan Radar for Fraud Teams memiliki opsi tambahan berikut:
You can test your integration’s settings with test cards that simulate fraud. If you have custom Radar rules, follow the testing advice in the Radar documentation. |
Ditolak oleh penerbit
Tipe |
|
Kode |
|
Masalah | Penerbit kartu menolak pembayaran. |
Solusi | This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action may be legitimate. Use the decline code to determine what next steps are appropriate. See the documentation on decline codes for appropriate responses to each code. Anda juga dapat:
Test how your integration handles declines with test cards that simulate successful and declined payments. |
Kesalahan pembayaran lainnya
Tipe |
|
Masalah | Terjadi kesalahan pembayaran lain. |
Solusi | This error can occur when your integration is working correctly. Use the error code to determine what next steps are appropriate. See the documentation on error codes for appropriate responses to each code. |
Kesalahan permintaan tidak valid
Kesalahan permintaan yang tidak valid mencakup berbagai situasi. Yang paling umum adalah saat permintaan API memiliki parameter yang tidak valid atau tidak diizinkan dalam status integrasi Anda saat ini. Gunakan kode kesalahan (stripeErr.
) dan lihat dokumentasi kode kesalahan untuk menemukan solusi. Beberapa kode kesalahan memerlukan respons khusus:
rate_
danlimit lock_
mencerminkan kesalahan batas rasiotimeout secret_
mencerminkan kesalahan autentikasikey_ required - Kode kesalahan lainnya mencerminkan parameter atau status yang tidak valid
Kesalahan batas rasio
Tipe |
|
Kode | stripeErr. |
Masalah | Anda melakukan panggilan API terlalu banyak dalam waktu terlalu singkat. |
Solusi |
|
Kesalahan autentikasi
Tipe |
|
Kode | stripeErr. |
Masalah | Stripe tidak dapat mengautentikasi Anda dengan informasi yang diberikan. |
Solusi |
|
Parameter atau status yang tidak valid
Tipe |
|
Kode | stripeErr. |
Masalah | Anda melakukan panggilan API dengan parameter yang salah, dalam status yang salah, atau dengan cara yang tidak valid. |
Solusi | Dalam sebagian besar kasus, masalahnya ada pada permintaannya itu sendiri. Parameternya tidak valid atau tidak dapat dijalankan dalam status integrasi Anda saat ini.
|
Kesalahan API
Tipe |
|
Masalah | Terjadi kesalahan di pihak Stripe. (Hal ini jarang terjadi.) |
Solusi | Perlakukan hasil panggilan API sebagai tidak tentu. Artinya, jangan beranggapan apakah telah berhasil atau gagal. Andalkan webhook untuk informasi tentang hasilnya. Bila memungkinkan, Stripe mengaktifkan webhook untuk objek baru yang kami buat ketika memecahkan masalah. To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors. |
Kesalahan idempotensi
Tipe |
|
Masalah | You used an idempotency key for something unexpected, like replaying a request but passing different parameters. |
Solusi |
|