Praktik terbaik menggunakan SourcesTidak lagi digunakan

Praktik terbaik untuk menerima berbagai metode pembayaran melalui integrasi tunggal.

Peringatan

We deprecated the Sources API and plan to remove support for local payment methods. If you currently handle any local payment methods using the Sources API, you must migrate them to the Payment Methods API.

While we don’t plan to remove support for card payments, we recommend replacing any use of the Sources API with the PaymentMethods API, which provides access to our latest features and payment method types.

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

Alur umum untuk pembayaran kartu

In a typical checkout flow for card payments (excluding 3D Secure), your integration collects the card information and creates a source, and uses it to make a charge request. Because it requires no additional action from the customer and card payments provide synchronous confirmation, we can immediately confirm if the payment is successful and that the funds are guaranteed—using webhooks isn’t necessary.

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:

Kejadian	Keterangan	Tindakan yang disarankan
`source.chargeable`	Objek Source menjadi `chargeable` setelah pelanggan mengautentikasi dan memverifikasi pembayaran.	Buat Charge.
`source.failed`	Objek Source menjadi dapat di-charge karena pelanggan Anda menolak mengautentikasi pembayaran.	Batalkan pesanan dan (secara opsional) libatkan kembali pelanggan dalam alur pembayaran Anda.
`source.canceled`	Objek Source kedaluwarsa dan Anda tidak dapat menggunakannya untuk membuat charge.	Batalkan pesanan dan (secara opsional) libatkan kembali pelanggan dalam alur pembayaran Anda.

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:

Kejadian	Keterangan	Tindakan yang disarankan
`charge.pending`	Charge menunggu (hanya pembayaran asinkron).	Tidak diperlukan tindakan.
`charge.succeeded`	Charge berhasil dan pembayaran selesai.	Selesaikan pesanan dan kirim konfirmasi ke pelanggan melalui email.
`charge.failed`	Charge gagal dan pembayaran tidak dapat diselesaikan.	Batalkan pesanan dan (secara opsional) libatkan kembali pelanggan dalam alur pembayaran Anda.

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.

Status	Pesan yang dilihat pelanggan
Source telah `chargeable`	Pesanan Anda telah diterima dan menunggu konfirmasi pembayaran.
Source telah `canceled`	Pembayaran gagal dan pesanan Anda tidak dapat diproses.
Source telah `failed`	Pembayaran gagal dan pesanan Anda tidak dapat diproses.
Source masih `pending` setelah menjajaki sebentar	Pesanan Anda telah diterima dan menunggu konfirmasi pembayaran.

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

Status	Pesan yang dilihat pelanggan
Charge masih `pending`	Pesanan Anda telah diterima dan menunggu konfirmasi pembayaran.
Charge telah `failed`	Pembayaran gagal dan pesanan Anda tidak dapat diproses.
Charge telah `succeeded`	Pembayaran telah dikonfirmasi dan pesanan Anda selesai.

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.