Lewati ke konten
Buat akun
atau
Masuk
Logo Dokumen Stripe
/
Tanya AI
Buat akun
Masuk
Mulai
Pembayaran
Pendapatan
Platform dan situs belanja online
Manajemen uang
Sumber daya pengembang
Gambaran Umum
Pembuatan versi
Log perubahan
Tingkatkan versi API Anda
Upgrade versi SDK Anda
Essentials
SDK
API
    API v2
    Kunci API
    Header Stripe-Context
    Batas tingkat
    Percobaan otomatis
    Metadata
    Memperluas respons
    Penomoran halaman
    Domain dan alamat IP
    Cari
    Pelokalan
    Penanganan kesalahan
      Penanganan kesalahan lanjutan
    Kode kesalahan
Pengujian
Stripe CLI
Proyek sampel
Alat
Workbench
Dashboard Pengembang
Stripe Shell
Stripe untuk Visual Studio Code
Fitur
Alur kerja
Tujuan Kejadian
Peringatan kesehatan StripePengunggahan file
Solusi AI
Toolkit agen
Protokol Konteks Model
Keamanan dan privasi
Keamanan
Privasi
Perluas Stripe
Membangun aplikasi Stripe
Gunakan aplikasi dari Stripe
Mitra
Ekosistem mitra
Sertifikasi mitra
BerandaSumber daya pengembangAPI

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.

Uraikan data kesalahan

Bila Stripe mengembalikan kesalahan ke permintaan API, Anda menerima detail tentang kesalahan yang membantu Anda memahami cara menerapkan saran penanganan dalam panduan ini. Detail ini juga membantu Anda memberikan informasi penting ke dukungan Stripe, jika dibutuhkan.

PropertiDeskripsi
codeKode kesalahan.
doc_urlTautan ke dokumentasi Stripe untuk kode kesalahan spesifik.
messageKeterangan alasan kesalahan.
paramParameter permintaan yang menyebabkan kesalahan.
request_log_urlTautan ke Dashboard Stripe tempat Anda dapat melihat log mendetail tentang permintaan asal dan kesalahannya.
Identifikasi permintaanPengidentifikasi unik untuk permintaan asal yang mengalami kesalahan. Header respons kesalahan menyertakan nilai ini (string yang dimulai dengan req), tetapi Anda dapat menentukan cetakan dalam permintaan, seperti yang diperlihatkan dalam sampel kode di panduan ini.
typeReferensi ke kategori kesalahan yang dimiliki kesalahan ini.

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.

TeknikTujuanBila dibutuhkan
Gunakan nilai kesalahanMemulihkan ketika panggilan API tidak dapat dilanjutkanSelalu
Pantau webhookBereaksi terhadap notifikasi dari StripeTerkadang
Dapatkan informasi tersimpan tentang kegagalanSelidiki masalah masa lalu dan dukung teknik lainnyaTerkadang

Gunakan nilai kesalahan

Kesalahan dan HTTP

Dengan pustaka ini, Anda tidak perlu memeriksa respons HTTP non-200. Pustaka ini menerjemahkannya menjadi nilai kesalahan.

Dalam kejadian langka, Anda membutuhkan detail HTTP, lihat Penanganan pengecualian tingkat rendah dan objek 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.Error, 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.

Ruby
Python
PHP
Java
Node
Buka
.NET
No results
package main import ( "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/paymentintent" "log" ) func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { log.Fatalf("request id: %s", stripeErr.RequestID) switch stripeErr.Type { case stripe.ErrorTypeCard: log.Println("A payment error occurred:", stripeErr.Msg) case stripe.ErrorTypeInvalidRequest: log.Println("An invalid request occurred.") default: log.Println("Another Stripe error occurred.") } } else { log.Println("An error occurred that was unrelated to Stripe.") } } }

Setelah menyiapkan penanganan pengecualian, coba pada berbagai data, termasuk kartu percobaan, untuk menyimulasikan hasil pembayaran yang berbeda.

Ruby
Python
PHP
Java
Node
Buka
.NET
No results
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), // The required parameter currency is missing Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_visa"
), } example_function(params)
console
Ruby
Python
PHP
Java
Node
Buka
.NET
No results
1754136548 An invalid request occurred.

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:

  1. Dapatkan objek yang terpengaruh dengan membongkar data dari event.Data.Raw.
  2. Gunakan informasi tersimpan pada objek yang terpengaruh untuk mendapatkan konteks, termasuk objek kesalahan.
  3. Gunakan tipenya untuk memilih respons.
Ruby
Python
PHP
Java
Node.js
Buka
.NET
No results
package main import ( "encoding/json" "io/ioutil" "log" "net/http" "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/webhook" ) func main() { http.HandleFunc("/webhook", handleWebhook) addr := "localhost:4242" log.Printf("Listening on %s", addr) log.Fatal(http.ListenAndServe(addr, nil)) } func handleWebhook(w http.ResponseWriter, req *http.Request) { const MaxBodyBytes = int64(65536) req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes) payload, err := ioutil.ReadAll(req.Body) if err != nil { log.Printf("Error reading request body: %v\n", err) w.WriteHeader(http.StatusServiceUnavailable) return } // Replace this endpoint secret with your endpoint's unique secret // If you are testing with the CLI, find the secret by running 'stripe listen' // If you are using an endpoint defined with the API or dashboard, look in your webhook settings // at https://dashboard.stripe.com/webhooks endpointSecret := "whsec_..." signatureHeader := req.Header.Get("Stripe-Signature") // Get an event object event, err := webhook.ConstructEvent(payload, signatureHeader, endpointSecret) if err != nil { log.Printf("⚠️ Webhook signature verification failed. %v\n", err) w.WriteHeader(http.StatusBadRequest) // Return a 400 error on a bad signature return } // Use its type to find out what happened switch event.Type { case "payment_intent.payment_failed": // Get the object affected by unmarshalling event data into // the appropriate struct for the event type var paymentIntent stripe.PaymentIntent err := json.Unmarshal(event.Data.Raw, &paymentIntent) if err != nil { log.Printf("Error parsing webhook JSON: %v\n", err) w.WriteHeader(http.StatusBadRequest) return } // Use stored data to get an error object e := paymentIntent.LastPaymentError // Use its type to choose a response switch e.Type { case "card_error": log.Println("A payment error occurred: ", e.Msg) case "invalid_request": log.Println("An invalid request occurred.") default: log.Println("Another problem occurred, maybe unrelated to Stripe.") } default: log.Println("Unhandled event type: ", event.Type) } w.WriteHeader(http.StatusOK) }

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.

Command Line
stripe trigger payment_intent.payment_failed
Output
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:

  1. Ambil tujuan pembayaran tertentu.
  2. Periksa apakah telah mengalami kesalahan pembayaran dengan menentukan apakah last_payment_error kosong.
  3. Jika demikian, catat kesalahannya, termasuk tipenya dan objek yang terpengaruh.
Ruby
Python
PHP
Java
Node.js
Buka
.NET
No results
stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
pi, _ := paymentintent.Get(
"{{PAYMENT_INTENT_ID}}"
, nil, ) paymentErr := pi.LastPaymentError if paymentErr != nil { log.Printf("PaymentIntent %s experienced a %s error.", pi.ID, paymentErr.Type) }

Berikut adalah objek umum yang menyimpan informasi tentang kegagalan.

ObjekAtributNilai
Payment Intentlast_payment_errorObjek kesalahan
Setup Intentlast_setup_errorObjek kesalahan
Invoicelast_finalization_errorObjek kesalahan
Upaya Penyiapansetup_errorObjek kesalahan
Payoutfailure_codeKode kegagalan payout
Pengembalian danafailure_reasonKode 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

stripe.ErrorTypeCard

Terjadi kesalahan selama pembayaran, yang melibatkan salah satu situasi berikut:
  • Pembayaran yang diblokir karena dugaan penipuan
  • Pembayaran yang ditolak oleh penerbit.
  • Kesalahan pembayaran lainnya.
Kesalahan permintaan tidak valid

stripe.ErrorTypeInvalidRequest

Anda melakukan panggilan API dengan cara yang saat ini tidak valid. Hal ini dapat termasuk:

  • Kesalahan pembatasan rasio
  • Kesalahan autentikasi
  • Parameter atau status yang tidak valid
Kesalahan API

stripe.ErrorTypeAPI

Terjadi kesalahan di pihak Stripe. (Hal ini jarang terjadi.)
Kesalahan idempotensi

stripe.ErrorTypeIdempotency

Anda menggunakan kunci idempotensi untuk suatu hal yang tak terduga, seperti memutar ulang permintaan, tetapi meneruskan parameter yang berbeda.

Kesalahan kartu

Kesalahan pembayaran nonkartu

Segala sesuatu di bagian ini juga berlaku untuk pembayaran nonkartu. Karena alasan historis, kesalahan pembayaran memiliki tipe stripe.ErrorTypeCard. Namun pada kenyataannya, tipe tersebut dapat mewakili masalah pada pembayaran, apa pun metode pembayarannya.

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.)

Ruby
Python
PHP
Java
Node
Go
.NET
No results
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) if charge.Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

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.)

Ruby
Python
PHP
Java
Node
Go
.NET
No results
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { if stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

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.

Ruby
Python
PHP
Java
Node
Go
.NET
No results
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), Currency: stripe.String(string(stripe.CurrencyUSD)), Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_radarBlock"
), } example_function(params)
console
Ruby
Python
PHP
Java
Node
Go
.NET
No results
1754136548 Payment blocked for suspected fraud.

Diblokir karena dugaan penipuan

Tipe

stripe.ErrorTypeCard

Kode
charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) charge.Outcome.Type == "blocked"
Kode

stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"

MasalahSistem 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:

  • Optimalkan integrasi Radar Anda untuk mengumpulkan informasi lebih mendetail.
  • Gunakan Payment Links, Checkout, atau Stripe Elements untuk elemen formulir siap-rakit yang dioptimalkan.

Pelanggan Radar for Fraud Teams memiliki opsi tambahan berikut:

  • Untuk membebaskan pembayaran tertentu, tambahkan ke daftar izin Anda. Radar for Fraud Teams
  • Untuk mengubah toleransi risiko, sesuaikan pengaturan risiko Anda. Radar for Fraud Teams
  • Untuk mengubah kriteria pemblokiran pembayaran, gunakan aturan custom. Radar for Fraud Teams

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

stripe.ErrorTypeCard

Kode

cardErr.Error.Code == stripe.ErrorCodeCardDeclined

MasalahPenerbit 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:

  • Ikuti rekomendasi untuk mengurangi penolakan penerbit.
  • Gunakan Payment Links, Checkout, atau Stripe Elements untuk elemen formulir siap-rakit yang mengimplementasikan rekomendasi tersebut.

Coba cara integrasi Anda menangani penolakan dengan kartu percobaan yang menyimulasikan pembayaran yang berhasil dan ditolak.

Kesalahan pembayaran lainnya

Tipe

stripe.ErrorTypeCard

MasalahTerjadi kesalahan pembayaran lain.
SolusiKesalahan 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.Code) dan lihat dokumentasi kode kesalahan untuk menemukan solusi. Beberapa kode kesalahan memerlukan respons khusus:

  • rate_limit dan lock_timeout mencerminkan kesalahan batas rasio
  • secret_key_required mencerminkan kesalahan autentikasi
  • Kode kesalahan lainnya mencerminkan parameter atau status yang tidak valid

Kesalahan batas rasio

Tipe

stripe.ErrorTypeInvalidRequest

KodestripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout
MasalahAnda melakukan panggilan API terlalu banyak dalam waktu terlalu singkat.
Solusi
  • Jika satu panggilan API memicu kesalahan ini, tunggu dan coba lagi.
  • Untuk menangani pembatasan rasio secara otomatis, coba ulang panggilan API setelah penundaan, dan tingkatkan penundaan secara eksponensial jika kesalahan berlanjut. Lihat dokumentasi tentang batas rasio untuk saran lebih lanjut.
  • Jika Anda mengantisipasi peningkatan lalu lintas yang besar dan ingin meminta peningkatan batas tingkat, hubungi Tim CS terlebih dahulu.

Kesalahan autentikasi

Tipe

stripe.ErrorTypeInvalidRequest

KodestripeErr.Code == stripe.ErrorCodeSecretKeyRequired
MasalahStripe tidak dapat mengautentikasi Anda dengan informasi yang diberikan.
Solusi
  • Gunakan kunci API yang benar.
  • Pastikan Anda tidak menggunakan kunci yang Anda “rotasikan” atau cabut.

Parameter atau status yang tidak valid

Tipe

stripe.ErrorTypeInvalidRequest

KodestripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired
MasalahAnda melakukan panggilan API dengan parameter yang salah, dalam status yang salah, atau dengan cara yang tidak valid.
SolusiDalam sebagian besar kasus, masalahnya ada pada permintaannya itu sendiri. Parameternya tidak valid atau tidak dapat dijalankan dalam status integrasi Anda saat ini.
  • Baca dokumentasi kode kesalahan untuk mendapatkan detail tentang masalah.
  • Demi kenyamanan, Anda dapat mengikuti tautan di stripeErr.DocURL untuk dokumentasi tentang kode kesalahan.
  • Jika kesalahan melibatkan parameter tertentu, gunakan stripeErr.Param untuk menentukan yang mana.

Kesalahan API

Tipe

stripe.ErrorTypeAPI

MasalahTerjadi 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

stripe.ErrorTypeIdempotency

MasalahAnda menggunakan kunci idempotensi untuk suatu hal yang tak terduga, seperti memutar ulang permintaan, tetapi meneruskan parameter yang berbeda.
Solusi
  • Setelah Anda menggunakan kunci idempotensi, hanya gunakan kembali untuk panggilan API yang sama persis.
  • Gunakan kunci idempotensi di bawah batas 255 karakter.
Apakah halaman ini membantu?
YaTidak
  • Butuh bantuan? Hubungi Tim CS.
  • Bergabunglah dengan program akses awal kami.
  • Lihat log perubahan kami.
  • Ada pertanyaan? Hubungi Bagian Penjualan.
  • LLM? Baca llms.txt.
  • Dijalankan oleh Markdoc