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.

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
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 masalah nyata mencegah kelanjutan panggilan API, pustaka Stripe PHP akan memunculkan pengecualian. Merupakan praktik terbaik untuk menangkap dan menangani pengecualian.

Untuk menangkap pengecualian, gunakan sintaks try/catch PHP. Stripe menyediakan beberapa kelas pengecualian yang bisa Anda tangkap. Masing-masing mewakili jenis kesalahan yang berbeda. Saat Anda menangkap pengecualian, Anda dapat menggunakan kelasnya untuk memilih respons.

Ruby
Python
PHP
Java
Node
Buka
.NET
No results
<?php
require 'vendor/autoload.php';
\Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

function example_function($args) {
  try {
    $stripe->paymentIntents->create($args);
    error_log("No error.");
  } catch(\Stripe\Exception\CardException $e) {
    error_log("A payment error occurred: {$e->getError()->message}. (request id: {$e->getRequestId()})");
  } catch (\Stripe\Exception\InvalidRequestException $e) {
    error_log("An invalid request occurred. (request id: {$e->getRequestId()})");
  } catch (Exception $e) {
    error_log("Another problem occurred, maybe 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
example_function([
  // The required parameter currency is missing
  'amount' => 2000,
  'confirm' => True,
  'payment_method' => 
'pm_card_visa'
,
]);
console
Ruby
Python
PHP
Java
Node
Buka
.NET
No results
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.
Ruby
Python
PHP
Java
Node.js
Buka
.NET
No results
<?php
require 'vendor/autoload.php';
\Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

$payload = @file_get_contents('php://input');
$event = null;

// Get the event object
try {
  $event = \Stripe\Event::constructFrom(
    json_decode($payload, true)
  );
} catch(\UnexpectedValueException $e) {
  echo '⚠️  Webhook error while parsing basic request.';
  http_response_code(400);
  exit();
}

// Use the event type to find out what happened
if ($event->type == 'payment_intent.payment_failed') {

  // Get the object affected
  $paymentIntent = $event->data->object;

  // Use stored information to get an error object
  $e = $paymentIntent->last_payment_error;

  // Use its type to choose a response
  switch ($e->type) {
    case \Stripe\Exception\CardException:
      error_log("A payment error occurred: {$e->getError()->message}");
      break;
    case \Stripe\Exception\InvalidRequestException:
      error_log("An invalid request occurred.");
      if (isset($e->getError()->param)) {
        error_log("The parameter {$e->getError()->param} is invalid or missing.");
      }
      break;
    default:
      error_log("Another problem occurred, maybe unrelated to Stripe.");
  }
}

http_response_code(200);

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
<?php
  require 'vendor/autoload.php';

  \Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

  payment_intent = $stripe->paymentIntents->retrieve(% identifier type="paymentIntent" /%});

  e = payment_intent->last_payment_error
  if isset(e) {
    error_log("PaymentIntent {$payment_intent->id} experienced a {$e->getError()->type} error.")
  }

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 Stripe PHP, setiap jenis kesalahan memiliki kelasnya sendiri. Gunakan dokumentasi untuk setiap kelas untuk saran tentang cara merespons.

Nama

Kelas

Keterangan
Kesalahan pembayaran

Stripe\Exception\CardException

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

Stripe\Exception\InvalidRequestException

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

Kesalahan koneksi

Stripe\Exception\ApiConnectionException

Ada masalah jaringan antara server Anda dan Stripe.
Kesalahan API

Stripe\Exception\ApiErrorException

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

Stripe\Exception\AuthenticationException

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

Stripe\Exception\IdempotencyException

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

Stripe\Exception\PermissionException

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

Stripe\Exception\RateLimitException

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

Stripe\Exception\SignatureVerificationException

Anda menggunakan verifikasi tanda tangan webhook dan tidak dapat memverifikasi jika kejadian webhook bersifat autentik.

Kesalahan pembayaran

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

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
<?php
  require 'vendor/autoload.php';
  \Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

  function example_function($args) {
    try {
      $stripe->paymentIntents->create($args);
    } catch(\Stripe\Exception\CardException $e) {
      $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge);
      if ($charge->outcome->type == 'blocked') {
        error_log('Blocked for suspected fraud.');
      } elseif ($e->getError()->code == 'expired_card') {
        error_log('Card expired.');
      } elseif ($e->getError()->code == 'card_declined') {
        error_log('Declined by the issuer.');
      } else {
        error_log('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
<?php
  require 'vendor/autoload.php';
  \Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

  function example_function($args) {
    try {
      $stripe->paymentIntents->create($args);
    } catch(\Stripe\Exception\CardException $e) {
      if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') {
        error_log('Blocked for suspected fraud.');
      } elseif ($e->getError()->code == 'expired_card') {
        error_log('Card expired.');
      } elseif ($e->getError()->code == 'card_declined') {
        error_log('Declined by the issuer.');
      } else {
        error_log('Other card error.');
      }
    }
  }

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.

Ruby
Python
PHP
Java
Node
Go
.NET
No results
example_function([
  'currency' => 'usd',
  'amount' => 2000,
  'confirm' => True,
  'payment_method' => 
'pm_card_radarBlock'
,
]);
console
Ruby
Python
PHP
Java
Node
Go
.NET
No results
Payment blocked for suspected fraud.

Pembayaran yang diblokir karena dugaan penipuan

Tipe

Stripe\Exception\CardException

Kode
$charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge);
charge->outcome->type == 'blocked'
Kode

$e->getError()->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
  • 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.

Pembayaran yang ditolak oleh penerbit

Tipe

Stripe\Exception\CardException

Kode

$e->getError()->code == "card_declined"

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:

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

Kesalahan pembayaran lainnya

Tipe

Stripe\Exception\CardException

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

Tipe

Stripe\Exception\InvalidRequestException

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 e->getError()->doc_url untuk dokumentasi tentang kode kesalahan.
  • Jika kesalahan melibatkan parameter tertentu, gunakan e->getError()->param untuk menentukan yang mana.

Kesalahan koneksi

Tipe

Stripe\Exception\ApiConnectionException

MasalahAda masalah jaringan antara server Anda dan Stripe.

Solusi

Perlakukan hasil panggilan API sebagai tidak tentu. Artinya, jangan menganggapnya berhasil atau gagal.

Untuk mengetahui apakah berhasil, Anda dapat:

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

Untuk membantu memulihkan dari kesalahan koneksi, Anda dapat:

  • Saat membuat atau memperbarui objek, gunakan kunci idempotensi. Kemudian, jika terjadi kesalahan koneksi, Anda dapat mengulangi permintaan dengan aman tanpa risiko membuat objek kedua atau melakukan pembaruan dua kali. Ulangi permintaan dengan kunci idempotensi yang sama sampai Anda menerima keberhasilan atau kegagalan yang jelas. Untuk saran lanjutan tentang strategi ini, lihat Penanganan kesalahan tingkat rendah.
  • 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\Exception\APIException

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 autentikasi

Tipe

Stripe\Exception\AuthenticationException

MasalahStripe tidak dapat mengautentikasi Anda dengan informasi yang diberikan.
Solusi

Kesalahan idempotensi

Tipe

Stripe\Exception\IdempotencyException

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.

Kesalahan izin

Tipe

Stripe\Exception\PermissionException

MasalahKunci API yang digunakan untuk permintaan ini tidak memiliki izin yang diperlukan.
Solusi
  • Pastikan Anda tidak menggunakan kunci API yang dibatasi untuk layanan yang aksesnya tidak dimilikinya.
  • Jangan melakukan tindakan di Dashboard saat masuk sebagai peran pengguna yang tidak memiliki izin.

Kesalahan batas tingkat

Tipe

Stripe\Exception\RateLimitException

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 verifikasi tanda tangan

Tipe

Stripe\Exception\SignatureVerificationException

MasalahAnda menggunakan verifikasi tanda tangan webhook dan tidak dapat memverifikasi jika kejadian webhook bersifat autentik.

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.

Jika Anda menerima kesalahan ini, padahal seharusnya tidak—misalnya, dengan webhook yang Anda ketahui berasal dari Stripe—maka lihat dokumentasi di memeriksa tanda tangan webhook untuk saran lebih lanjut. Secara khusus, pastikan Anda menggunakan rahasia endpoint yang benar. Ini berbeda dengan kunci API Anda.

Apakah halaman ini membantu?
YaTidak