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
Alat bantu pengembang
Gambaran Umum
Pembuatan versi
Log perubahan
Tingkatkan versi API Anda
Upgrade versi SDK Anda
Alat bantu pengembang
SDK
API
    API v2
    Kunci API
    Header Stripe-Context
    Log perubahan harian
    Batas tingkat
    Percobaan otomatis
    Metadata
    Memperluas respons
    Penomoran halaman
    Domain dan alamat IP
    Cari
    Pelokalan
    Penanganan kesalahan
      Penanganan kesalahan lanjutan
    Kode kesalahan
Pengujian
Workbench
Tujuan Kejadian
Alur kerja
Stripe CLI
Stripe Shell
Dashboard Pengembang
Toolkit agen
Bangun dengan LLMStripe untuk Visual Studio CodePeringatan kesehatan StripePengunggahan file
Keamanan dan privasi
Keamanan
Privasi
Perluas Stripe
Stripe Apps
Stripe Connector
Mitra
Ekosistem mitra
Sertifikasi mitra
BerandaAlat bantu pengembangAPI

Penanganan kesalahan

Tangkap dan berikan respons terhadap penolakan, data yang tidak valid, masalah jaringan, dan lainnya.

Salin halaman

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.

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.

Buka
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 { 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.

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

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

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

Go
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
Go
1749848100 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