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 | Anda menggunakan kunci idempotensi untuk suatu hal yang tak terduga, seperti memutar ulang permintaan, tetapi meneruskan parameter yang berbeda. |
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
Untuk membedakan kategori ini atau mendapatkan informasi selengkapnya tentang cara merespons, periksa kode kesalahan, kode penolakan, dan hasil charge.
(Untuk menemukan hasil charge dari objek kesalahan, dapatkan terlebih dahulu Payment Intent yang terlibat dan Charge terbaru yang dibuatnya. Lihat contoh di bawah untuk demonstrasi.)
Pengguna pada versi API 2022-08-01 atau lebih lama:
(Untuk menemukan hasil charge dari objek kesalahan, dapatkan terlebih dahulu Payment Intent yang terlibat dan Charge terbaru yang dibuatnya. Lihat contoh di bawah untuk demonstrasi.)
Anda dapat memicu beberapa jenis kesalahan pembayaran yang umum dengan kartu percobaan. Lihat daftar ini untuk mengetahui opsinya:
- Menyimulasikan pembayaran yang diblokir karena risiko penipuan
- Menyimulasikan pembayaran yang ditolak dan kesalahan kartu lainnya
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:
Anda dapat mencoba pengaturan integrasi dengan kartu percobaan yang menyimulasikan penipuan. Jika Anda memiliki aturan Radar custom, ikuti saran percobaan dalam dokumentasi Radar. |
Ditolak oleh penerbit
Tipe |
|
Kode |
|
Masalah | Penerbit kartu menolak pembayaran. |
Solusi | Kesalahan ini dapat terjadi bila integrasi Anda berfungsi dengan benar. Ini mencerminkan suatu tindakan oleh penerbit, dan tindakan itu mungkin sah. Gunakan kode penolakan untuk menentukan langkah berikutnya yang sesuai. Lihat dokumentasi tentang kode penolakan untuk respons yang sesuai terhadap setiap kode. Anda juga dapat:
Coba cara integrasi Anda menangani penolakan dengan kartu percobaan yang menyimulasikan pembayaran yang berhasil dan ditolak. |
Kesalahan pembayaran lainnya
Tipe |
|
Masalah | Terjadi kesalahan pembayaran lain. |
Solusi | Kesalahan ini dapat terjadi bila integrasi Anda berfungsi dengan benar. Gunakan kode kesalahan untuk menentukan langkah selanjutnya yang sesuai. Lihat dokumentasi tentang kode kesalahan untuk respons yang sesuai terhadap setiap kode. |
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. Untuk menyiapkan integrasi Anda demi ketahanan maksimum dalam situasi yang tidak biasa, lihat diskusi lanjutan tentang kesalahan server ini. |
Kesalahan idempotensi
Tipe |
|
Masalah | Anda menggunakan kunci idempotensi untuk suatu hal yang tak terduga, seperti memutar ulang permintaan, tetapi meneruskan parameter yang berbeda. |
Solusi |
|