Lewati ke konten
Buat akun
 atau
Masuk
Logo Dokumen Stripe
/
Buat akun
Masuk

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
Tangkap pengecualianMemulihkan ketika panggilan API tidak dapat dilanjutkanSelalu
Pantau webhookBereaksi terhadap notifikasi dari StripeTerkadang
Dapatkan informasi tersimpan tentang kegagalanSelidiki masalah masa lalu dan dukung teknik lainnyaTerkadang

Tangkap pengecualian

Jika sebuah masalah langsung mencegah panggilan API untuk dilanjutkan, pustaka Ruby Stripe memunculkan sebuah pengecualian. Praktik terbaiknya adalah untuk menangkap dan menangani pengecualian.

Untuk menangkap pengecualian, gunakan kata kunci rescue Ruby. Tangkap Stripe::StripeError atau subkelasnya hanya untuk menangani pengecualian khusus Stripe. Setiap subkelas mewakili jenis pengecualian yang berbeda. Saat menangkap pengecualian, Anda dapat menggunakan kelasnya untuk memilih respons.

require 'stripe'

Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    puts "A payment error occurred: #{e.error.message}"
  rescue Stripe::InvalidRequestError => e
    puts "An invalid request occurred."
  rescue Stripe::StripeError => e
    puts "Another problem occurred, maybe unrelated to Stripe."
  else
    puts "No error."
  end
end

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

example_function(
  # The required parameter currency is missing,
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_visa'
,
)
console
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. Akses event.data.object untuk mengambil objek yang terpengaruh.
  2. Gunakan informasi tersimpan pada objek yang terpengaruh untuk mendapatkan konteks, termasuk objek kesalahan.
  3. Gunakan tipenya untuk memilih respons.
require 'stripe'
require 'sinatra'
post '/webhook' do
  payload = request.body.read
  data = JSON.parse(payload, symbolize_names: true)

  # Get the event object
  event = Stripe::Event.construct_from(data)

  # Use the event type to find out what happened
  case event.type
  when 'payment_intent.payment_failed'

    # Get the object affected
    payment_intent = event.data.object

    # Use stored information to get an error object
    e = payment_intent.last_payment_error

    # Use its type to choose a response
    case e.type
    when 'card_error'
      puts "A payment error occurred: #{e.message}"
    when 'invalid_request'
      puts "An invalid request occurred."
    else
      puts "Another problem occurred, maybe unrelated to Stripe."
    end
  end

  content_type 'application/json'
  {
    status: 'success'
  }.to_json
end

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.
require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


payment_intent = Stripe::PaymentIntent.retrieve(
'{{PAYMENT_INTENT_ID}}'
)
e = payment_intent.last_payment_error
if !e.nil?
  puts "PaymentIntent #{payment_intent.id} experienced a #{e.type}."
end

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:

Tipe kesalahan dan respons

Di pustaka Ruby Stripe, objek kesalahan dimiliki oleh stripe.error.StripeError dan subkelasnya. Gunakan dokumentasi bagi setiap kelas untuk saran dalam merespons.

Nama

Kelas

Keterangan
Kesalahan pembayaran

Stripe::CardError

Terjadi kesalahan selama pembayaran, yang melibatkan salah satu situasi berikut:
Kesalahan permintaan tidak valid

Stripe::InvalidRequestError

Anda melakukan panggilan API dengan parameter yang salah, dalam status yang salah, atau dengan cara yang tidak valid.

Kesalahan koneksi

Stripe::APIConnectionError

Ada masalah jaringan antara server Anda dan Stripe.
Kesalahan API

Stripe::APIError

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

Stripe::AuthenticationError

Stripe tidak dapat mengautentikasi Anda dengan informasi yang diberikan.
Kesalahan idempotensi

Stripe::IdempotencyError

You used an idempotency key for something unexpected, like replaying a request but passing different parameters.
Kesalahan izin

Stripe::PermissionError

Kunci API yang digunakan untuk permintaan ini tidak memiliki izin yang diperlukan.
Kesalahan batas tingkat

Stripe::RateLimitError

Anda melakukan panggilan API terlalu banyak dalam waktu terlalu singkat.
Kesalahan verifikasi tanda tangan

Stripe::SignatureVerificationError

You’re using webhook signature verification and couldn’t verify that a webhook event is authentic.

Kesalahan pembayaran

Kesalahan pembayaran—terkadang disebut sebagai “kesalahan kartu” karena alasan historis—mencakup beragam masalah umum. Kesalahan itu terbagi dalam tiga kategori:

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

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
    if charge.outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

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

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    if e.error.payment_intent.charges.data[0].outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

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.

example_function(
  currency: 'usd',
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_radarBlock'
,
)
console
Payment blocked for suspected fraud.

Pembayaran yang diblokir karena dugaan penipuan

Tipe

Stripe::CardError

Kode
charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
charge.outcome.type == 'blocked'
Kode

e.error.payment_intent.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:

Pelanggan Radar for Fraud Teams memiliki opsi tambahan berikut:

  • Untuk membebaskan pembayaran tertentu, tambahkan ke daftar izin Anda. Radar for Fraud Teams
  • To change your risk tolerance, adjust your risk settings. Radar for Fraud Teams
  • To change the criteria for blocking a payment, use custom rules. Radar for Fraud Teams

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.

Pembayaran yang ditolak oleh penerbit

Tipe

Stripe::CardError

Kode

e.error.code == "card_declined"

MasalahPenerbit kartu menolak pembayaran.

Solusi

This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action might 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

Stripe::CardError

MasalahTerjadi kesalahan pembayaran lain.
SolusiThis 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

Tipe

Stripe::InvalidRequestError

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.
  • Consult the error code documentation for details on the problem.
  • Demi kenyamanan, Anda dapat mengikuti tautan di untuk dokumentasi tentang kode kesalahan.
  • Jika kesalahan melibatkan parameter tertentu, gunakan untuk menentukan yang mana.

Kesalahan koneksi

Tipe

Stripe::APIConnectionError

MasalahAda masalah jaringan antara server Anda dan Stripe.

Solusi

Treat the result of the API call as indeterminate. That is, don’t assume that it succeeded or that it failed.

Untuk mengetahui apakah berhasil, Anda dapat:

  • Ambil objek yang relevan dari Stripe dan periksa statusnya.
  • Dengarkan notifikasi webhook apakah operasi telah berhasil atau gagal.

To help recover from connection errors, you can:

  • When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice. Repeat the request with the same idempotency key until you receive a clear success or failure. For advanced advice on this strategy, see Low-level error handling.
  • Aktifkan percobaan ulang otomatis. Kemudian, Stripe membuat kunci idempotensi serta mengulangi permintaan untuk Anda bila aman untuk melakukannya.

Kesalahan ini dapat menutupi yang lainnya. Bisa jadi bila kesalahan koneksi teratasi, beberapa kesalahan lain menjadi tampak. Periksa kesalahan dalam semua solusi ini sebagaimana yang Anda lakukan di permintaan semula.

Kesalahan API

Tipe

Stripe::APIError

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.

To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors.

Kesalahan autentikasi

Tipe

Stripe::AuthenticationError

MasalahStripe tidak dapat mengautentikasi Anda dengan informasi yang diberikan.
Solusi

Kesalahan idempotensi

Tipe

Stripe::IdempotencyError

MasalahYou used an idempotency key for something unexpected, like replaying a request but passing different parameters.
Solusi
  • Setelah Anda menggunakan kunci idempotensi, hanya gunakan kembali untuk panggilan API yang sama persis.
  • Gunakan kunci idempotensi di bawah batas 255 karakter.

Kesalahan izin

Tipe

Stripe::PermissionError

MasalahThe API key used for this request doesn’t have the necessary permissions.
Solusi
  • Make sure you aren’t using a restricted API key for a service it doesn’t have access to.
  • Don’t perform actions in the Dashboard while logged in as a user role that lacks permission.

Kesalahan batas tingkat

Tipe

Stripe::RateLimitError

MasalahAnda melakukan panggilan API terlalu banyak dalam waktu terlalu singkat.
Solusi
  • Jika satu panggilan API memicu kesalahan ini, tunggu dan coba lagi.
  • To handle rate-limiting automatically, retry the API call after a delay, and increase the delay exponentially if the error continues. See the documentation on rate limits for further advice.
  • Jika Anda mengantisipasi peningkatan lalu lintas yang besar dan ingin meminta peningkatan batas tingkat, hubungi Tim CS terlebih dahulu.

Kesalahan verifikasi tanda tangan

Tipe

Stripe::SignatureVerificationError

MasalahYou’re using webhook signature verification and couldn’t verify that a webhook event is authentic.

Solusi

Kesalahan ini dapat terjadi bila integrasi Anda berfungsi dengan benar. Jika Anda menggunakan verifikasi tanda tangan webhook dan pihak ketiga mencoba mengirimi Anda webhook palsu atau jahat, maka verifikasi akan gagal dan menghasilkan kesalahan ini. Tangkap dan respons dengan kode status 400 Bad Request.

If you receive this error when you shouldn’t—for instance, with webhooks that you know originate with Stripe—then see the documentation on checking webhook signatures for further advice. In particular, make sure you’re using the correct endpoint secret. This is different from your API key.

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