Praktik terbaik menggunakan SourcesTidak lagi digunakan

Fleksibilitas Sources API membantu Anda meminimalkan perubahan yang diperlukan untuk mendukung metode pembayaran tambahan saat Anda menambahkannya.

Alur umum untuk pembayaran kartu

Dalam alur checkout umum untuk pembayaran kartu (tidak termasuk 3D Secure), integrasi Anda mengumpulkan informasi kartu dan membuat sumber, serta menggunakannya untuk membuat permintaan charge. Karena tidak memerlukan tindakan tambahan dari pelanggan dan pembayaran kartu memberikan konfirmasi sinkron, kami dapat segera mengonfirmasi jika pembayaran berhasil dan dana dijamin—tidak perlu menggunakan webhook.

Penggunaan webhook yang diperlukan

Metode pembayaran lain mungkin mengharuskan pelanggan Anda untuk melakukan tindakan tambahan (misalnya, pengalihan) sebelum sumber menjadi chargeable dan dapat digunakan untuk membuat permintaan charge (misalnya, iDEAL). Transisi ini umumnya terjadi secara asinkron dan bahkan dapat terjadi setelah pelanggan meninggalkan situs Anda. Karena alasan ini, integrasi Anda harus mengandalkan webhook untuk menentukan kapan sumber dapat di-charge sebelum membuat charge.

Stripe mengirimkan kejadian webhook berikut untuk memberi tahu Anda tentang perubahan status sumber:

Demikian pula saat membuat charge, metode pembayaran asinkron tertentu mungkin perlu waktu beberapa hari untuk mengonfirmasi dana dan agar charge berhasil, sehingga mengharuskan webhook untuk mengetahui kapan harus mengonfirmasi dan selanjutnya memenuhi pesanan Anda.

Stripe mengirimkan kejadian webhook berikut untuk memberi tahu Anda tentang perubahan status charge:

Membangun integrasi yang fleksibel

Untuk memastikan proses checkout Anda fleksibel dan siap mendukung beberapa metode pembayaran, kami merekomendasikan pendekatan berikut:

Pembuatan sumber

Saat membuat Source, catat identifikasi sumber pada representasi pesanan internal sehingga Anda dapat mengambil pesanan bila menerima dan memproses webhook source.chargeable. Pastikan mengindeks objek pesanan berdasarkan atribut source ini agar lookup efisien.

Pembuatan charge

Pengiriman webhook source.chargeable akan men-charge Source. Saat menerima webhook, ambil representasi pesanan internal Anda dengan mencari berdasarkan identifikasi sumber yang diterima dan verifikasikan bahwa pesanan sedang menunggu pembayaran.

Saat membuat permintaan charge, gunakan identifikasi pesanan internal Anda sebagai kunci idempotensi untuk menghindari kemungkinan kondisi berlomba. Selain itu, jika sumber dapat digunakan kembali dan Anda ingin menggunakannya kembali, pastikan melampirkannya ke Customer sebelum men-charge-nya. Lihat panduan Sekali-pakai atau dapat-digunakan-kembali dan Source & Customer untuk mempelajari selengkapnya tentang cara menangani Source sekali-pakai dan dapat-digunakan-kembali dan cara interaksinya dengan Pelanggan.

Sama seperti pembuatan sumber, catat identifikasi charge pada representasi pesanan internal sehingga Anda dapat mengambil pesanan bila menerima dan memproses webhook charge.succeeded.

Halaman konfirmasi

Setelah pelanggan Anda mengambil tindakan yang diperlukan untuk mengotorisasi pembayaran (misalnya, mereka telah mengikuti pengalihan), Anda harus menampilkan halaman konfirmasi yang menampilkan status pesanan. Anda dapat melakukannya dengan menjajaki pesanan secara internal.

Karena latensi pengiriman webhook tidak dijamin, jika ingin lebih mengefisienkan halaman konfirmasi, Anda dapat menjajaki status Source terkait di kode sisi client. Bila Anda mendeteksi bahwa Source telah chargeable, Anda dapat memulai pembuatan Charge menggunakan Source tersebut tanpa menunggu webhook source.chargeable tiba.

Perhatikan, beberapa tipe Source perlu waktu beberapa menit (atau bahkan berhari-hari) untuk menjadi chargeable. Jika Anda memutuskan untuk menjajaki Source, kami merekomendasikan Anda untuk time-out di beberapa titik dan memberi tahu pelanggan bahwa pesanan mereka sedang menunggu konfirmasi pembayaran, kemudian mengirimi mereka email konfirmasi pembayaran secara asinkron. Anda dapat melihat pengiriman pesan yang dilihat pelanggan yang kami rekomendasikan untuk setiap status Source dalam tabel di bawah ini.

Penjajakan sisi client akan berhenti jika pelanggan meninggalkan halaman Anda. Ini berarti Anda juga harus berintegrasi dengan webhook source.chargeable untuk memastikan Anda tidak kehilangan jejak pesanan pelanggan.

Jika menggunakan Stripe.js, Anda dapat menggunakan stripe.retrieveSource() untuk mengimplementasikan sendiri penjajakan tersebut:

// In order-confirmation-page.js

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// After some amount of time, we should stop trying to resolve the order synchronously:
const MAX_POLL_COUNT = 10;
let pollCount = 0;

const pollForSourceStatus = async () => {
  const {source} = await stripe.retrieveSource({id: SOURCE_ID, client_secret: CLIENT_SECRET})
  if (source.status === 'chargeable') {
    // Make a request to your server to charge the Source.
    // Depending on the Charge status, show your customer the relevant message.
  } else if (source.status === 'pending' && pollCount < MAX_POLL_COUNT) {
    // Try again in a second, if the Source is still `pending`:
    pollCount += 1;
    setTimeout(pollForSourceStatus, 1000);
  } else {
    // Depending on the Source status, show your customer the relevant message.
  }
};

pollForSourceStatus();

Tabel di bawah ini berisi rekomendasi bakal pesan yang dilihat pelanggan yang dapat Anda tampilkan berdasarkan status Source.

Setelah Anda membuat Charge (dan jika pengguna masih berada di halaman konfirmasi), Anda dapat menampilkan pesan berikut berdasarkan status Charge:

Konfirmasi pesanan

Hanya konfirmasikan pesanan setelah Anda menerima webhook charge.succeeded (ini mungkin terjadi secara instan, tetapi mungkin juga tidak). Kirim email ke pelanggan pada tahap ini karena konfirmasi pembayaran dapat memakan waktu berhari-hari untuk pembayaran asinkron.

Pembatalan dan kegagalan

Dengarkan webhook source.canceled dan source.failed dan pastikan membatalkan pesanan yang terkait dengan sumber bersangkutan. Jika mengikuti praktik terbaik di atas, Anda tidak akan menerima webhook source.canceled untuk sumber yang sebelumnya chargeable (karena handler source.chargeable seharusnya membuat tagihan segera, sehingga mencegah sumber dibatalkan). Anda akan tetap menerima webhook source.canceled untuk sumber yang tidak pernah chargeable dan tetap pending, umumnya merupakan indikasi bahwa pelanggan Anda meninggalkan alur pembayaran lebih cepat. Anda juga dapat menerima webhook source.failed setiap kali Customer menolak pembayaran atau terjadi kegagalan teknis di tingkat skema pembayaran.

Anda juga harus mendengarkan webhook charge.failed untuk memastikan sebelum membatalkan pesanan yang terkait dengan charge yang diterima.

Untuk setiap kejadian ini, sebaiknya Anda memberi tahu pelanggan bahwa pesanan mereka gagal dan mengundang mereka untuk terlibat kembali dalam alur pembayaran Anda, jika diinginkan.