Transisi ke Payment Intents API dan Payment Methods API
Payment Methods API menggantikan Tokens API dan Sources API yang ada sebagai cara integrasi yang direkomendasikan untuk mengumpulkan serta menyimpan informasi pembayaran. Ini bekerja sama Payment Intents API guna melakukan pembayaran bagi berbagai metode pembayaran.
Kami berencana menonaktifkan dukungan Sources API bagi metode pembayaran lokal. Jika saat ini Anda menangani metode pembayaran lokal menggunakan Sources API, Anda harus memigrasikannya ke Payment Methods API. Kami akan mengirimkan komunikasi email dengan informasi selengkapnya tentang akhir dukungan ini.
Meski kami tidak berencana menonaktifkan dukungan metode pembayaran kartu, kami tetap merekomendasikan Anda memigrasikannya ke Payment Methods API dan Pembayaran Intents API. Untuk informasi selengkapnya tentang melakukan migrasi metode pembayaran kartu, lihat Memigrasikan ke Payment Intents API.
Lakukan migrasi metode pembayaran lokal dari Sources API ke Payment Intents API
Guna melakukan migrasi integrasi metode pembayaran lokal, perbarui server dan frontend untuk menggunakan PaymentIntents API. Terdapat tiga pilihan integrasi pada umumnya:
- Alihkan ke Stripe Checkout untuk alur pembayaran Anda.
- Gunakan Payment Element Stripe di halaman pembayaran Anda sendiri.
- Bangun formulir Anda sendiri dan gunakan Stripe JS SDK untuk menyelesaikan pembayaran.
Jika menggunakan Stripe Checkout atau Payment Element, Anda dapat menambahkan dan mengelola sebagian besar metode pembayaran dari Dashboard Stripe tanpa melakukan perubahan kode.
Untuk informasi spesifik tentang pengintegrasian metode pembayaran lokal menggunakan Payment Methods API, lihat instruksi bagi metode pembayaran tersebut di dokumentasi metode pembayaran. Tabel berikut menyediakan perbandingan level tinggi dari tipe pembayaran yang berbeda.
Integrasi lama | Stripe Checkout | Payment Element | Formulir tersendiri |
---|---|---|---|
Kompleksitas rendah | Kompleksitas sedang | Kompleksitas tinggi | |
Buat Sumber pada frontend atau pada server | Buat Sesi Checkout pada server | Buat PaymentIntent pada server | Buat PaymentIntent pada server |
Otorisasikan pembayaran dengan memuat widget atau pengalihan ke pihak ketiga | Tidak dibutuhkan | Teruskan client secret ke frontend dan gunakan Stripe JS SDK untuk menampilkan Payment Element guna menyelesaikan pembayaran | Teruskan client secret ke frontend, gunakan formulir Anda sendiri untuk mengumpulkan detail dari pelanggan, dan selesaikan pembayaran sesuai dengan metode pembayaran |
Konfirmasikan apakah sumber dapat di-charge dan kenakan charge Sumber | Tidak dibutuhkan | Tidak dibutuhkan | Tidak dibutuhkan |
Konfirmasikan Charge berhasil secara asinkron dengan webhook charge.succeeded | Konfirmasikan sesi Checkout yang berhasil dengan webhook payment_intent.succeeded | Konfirmasikan PaymentIntent yang berhasil dengan webhook payment_intent.succeeded | Konfirmasikan PaymentIntent yang berhasil dengan webhook payment_intent.succeeded |
Peringatan
Objek PaymentIntent mewakili pembayaran dalam integrasi baru, dan akan membuat Charge bila Anda mengonfirmasikan pembayaran pada frontend. Jika sebelumnya menyimpan referensi ke Charge, Anda dapat terus melakukannya dengan mengambil Identifikasi Charge dari PaymentIntent setelah pelanggan menyelesaikan pembayaran. Namun, kami merekomendasikan agar Anda menyimpan Identifikasi PaymentIntent.
Bidang pemetaan
Jika menggunakan Payment Element atau formulir sendiri, Anda harus memetakan ulang bidang Sumber ke bidang PaymentIntent. Bidang tertentu bergantung pada metode pembayaran.
Memeriksa status pembayaran
Sebelumnya, integrasi Anda seharusnya telah memeriksa status Sumber maupun status Charge setelah setiap panggilan API. Anda tidak perlu lagi memeriksa dua status—Anda hanya perlu memeriksa status PaymentIntent atau Sesi Checkout setelah mengonfirmasikannya pada frontend.
payment_intent.status | Arti | Catatan |
---|---|---|
succeeded | Pembayaran berhasil. | |
requires_payment_method | Pembayaran gagal. | |
requires_action | Pelanggan belum menyelesaikan otorisasi pembayaran. | Jika pelanggan tidak menyelesaikan pembayaran dalam waktu 48 jam, maka akan terjadi transisi PaymentIntent ke requires_payment_method dan Anda dapat mencoba ulang konfirmasi. |
Selalu konfirmasikan status PaymentIntent dengan mengambilnya pada server atau mendengarkan webhook pada server Anda. Jangan hanya mengandalkan pengguna yang kembali ke return_url
yang diberikan saat Anda mengonfirmasikan PaymentIntent.
Pengembalian dana
Anda dapat terus memanggil Refunds API dengan Charge yang dibuat oleh PaymentIntent. Identifikasi Charge dapat diakses pada parameter latest_charge
.
Atau, Anda dapat memberikan Identifikasi PaymentIntent ke Refunds API dan bukan ke Charge.
Penanganan kesalahan
Sebelumnya, Anda harus menangani kesalahan pada Sources. Dengan PaymentsIntents, sebagai ganti memeriksa kesalahan pada Source, Anda memeriksa kesalahan pada PaymentIntent bila dibuat dan setelah pelanggan mengotorisasi pembayaran. Sebagian besar kesalahan pada PaymentIntent bertipe invalid_request_error
, yang dikembalikan dalam permintaan tak valid.
Ketika memigrasikan integrasi, ingatlah bahwa kode kesalahan PaymentIntent dapat berbeda dari kode kesalahan yang bersangkutan untuk Sources.
Webhook
Jika sebelumnya mendengarkan kejadian Sumber, Anda mungkin perlu memperbarui integrasi untuk mendengarkan tipe kejadian baru. Tabel berikut ini menunjukkan sejumlah contoh.
Webhook lama | Webhook baru pada Checkout | Webhook baru pada PaymentsIntents | Catatan |
---|---|---|---|
source.chargeable | Tidak berlaku | Tidak berlaku | |
source.failed | Tidak berlaku | Tidak berlaku | |
source.canceled | Tidak berlaku | Tidak berlaku | |
charge.succeeded | checkout.session.completed | payment_intent.succeeded | Webhook charge.succeeded juga dikirim, jadi Anda tidak perlu memperbarui integrasi untuk mendengarkan webhook baru. |
charge.failed | Tidak berlaku - Pelanggan dapat mencoba ulang pembayaran pada Sesi Checkout yang sama sampai kedaluwarsa, saat di mana Anda menerima kejadian checkout.session.expired . | payment_intent.payment_failed | Webhook charge.failed juga dikirim, jadi Anda tidak perlu memperbarui integrasi untuk mendengarkan webhook baru. |
charge.dispute.created | charge.dispute.created | charge.dispute.created |
Bertransisi ke Payment Methods API
Perbedaan utama antara Payment Methods API dan Sources API adalah Sources menjelaskan status transaksi melalui properti status. Itu berarti transisi setiap objek Source
harus dilakukan ke status dapat di-charge agar dapat digunakan untuk pembayaran. Sedangkan PaymentMethod
bersifat stateless, bergantung pada objek PaymentIntent guna mewakili status pembayaran.
Catatan
Tabel berikut ini bukan daftar metode pembayaran yang komprehensif. Jika Anda mengintegrasikan metode pembayaran lain dengan Sources API, lakukan juga migrasi ke Payment Methods API.
Alur | Integrasikan Metode Pembayaran dengan Payment Intents API | Tokens atau Sources dengan Charges API |
---|---|---|
Kartu | Pembayaran kartu | Didukung di Tokens; Tidak direkomendasikan di Sources |
Debit Langsung ACH | Debit langsung rekening bank AS | Didukung di Tokens Tidak direkomendasikan di Sources |
Alipay | Pembayaran Alipay | Tidak lagi digunakan |
Bancontact | Pembayaran Bancontact | Tidak lagi digunakan |
EPS | Pembayaran EPS | Tidak lagi digunakan |
giropay | Pembayaran giropay | Tidak lagi digunakan |
iDEAL | Pembayaran iDEAL | Tidak lagi digunakan |
Klarna | Pembayaran Klarna | Tidak lagi digunakan |
Multibanco | Terencana | Beta yang Tidak Lagi Digunakan |
Przelewy24 | Pembayaran Przelewy24 | Tidak lagi digunakan |
Debit Langsung SEPA | Debit langsung Single Euro Payments Area | Tidak lagi digunakan |
Sofort | Pembayaran Sofort | Tidak lagi digunakan |
WeChat Pay | Pembayaran WeChat Pay | Tidak lagi digunakan |
Setelah Anda memilih API yang akan diintegrasikan, panduan metode pembayaran kami dapat membantu Anda menentukan tipe metode pembayaran yang tepat yang akan didukung untuk pelanggan.
Panduan ini menyertakan keterangan mendetail dari setiap metode pembayaran dan menjelaskan perbedaannya dalam alur yang dilihat pelanggan, bersama wilayah geografis yang paling relevan dengan mereka. Anda dapat mengaktifkan metode pembayaran yang tersedia di Dashboard. Aktivasi biasanya terjadi seketika dan tidak memerlukan kontrak tambahan maupun menyertakan proses yang panjang.
Kompatibilitas dengan metode pembayaran yang dapat digunakan kembali terdahulu
Jika sebelumnya Anda memproses salah satu metode pembayaran yang dapat digunakan kembali berikut menggunakan Sources, migrasi sumber tersimpan yang ada tidak dilakukan secara otomatis. Guna mempertahankan metode pembayaran tersimpan dari pelanggan yang ada, Anda harus mengonversi sumber tersebut ke metode pembayaran menggunakan alat migrasi data di Dashboard Stripe. Untuk cara mengonversinya, lihat halaman dukungan.
- Alipay
- Debit Langsung Bacs
- Debit Langsung SEPA
Kompatibilitas dengan objek kartu terdahulu
Jika sebelumnya Anda mengumpulkan detail pembayaran kartu pelanggan dengan Stripe menggunakan kartu atau Sumber, Anda dapat langsung mulai menggunakan Payment Methods API tanpa memindahkan informasi pembayaran.
Instrumen pembayaran kompatibel yang disimpan ke Pelanggan dapat digunakan di API yang menerima objek PaymentMethod. Misalnya, Anda dapat menggunakan kartu yang disimpan sebagai PaymentMethod saat membuat PaymentIntent:
Jangan lupa memberikan identifikasi pelanggan tempat menyimpan instrumen pembayaran Anda yang kompatibel saat melampirkan objek ke PaymentIntent.
Anda dapat mengambil semua instrumen pembayaran tersimpan yang kompatibel melalui Payment Methods API.
Perhatikan, dengan kompatibilitas ini, tidak ada objek baru yang dibuat; Payment Methods API memberikan tampilan berbeda dari objek dasar yang sama. Misalnya, pembaruan pada instrumen pembayaran yang kompatibel melalui Payment Methods API akan terlihat melalui Sources API dan sebaliknya.