Transisi ke Payment Intents API dan Payment Methods API

Pelajari cara bertransisi dari Sources dan Token API ke 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 untuk mematikan dukungan Sources API untuk metode pembayaran lokal. Jika saat ini Anda menangani metode pembayaran lokal menggunakan Sources API, Anda harus memigrasikannya ke Payment Method API. Kami akan mengirimkan komunikasi email dengan informasi selengkapnya tentang akhir dukungan untuk Token dan Sources API.

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.

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	Instruksi khusus
`succeeded`	Pembayaran berhasil.	Tidak berlaku
`requires_payment_method`	Pembayaran gagal.	Tidak berlaku
`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	Instruksi khusus
`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 sebelum dapat Anda gunakan 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	Pembayaran Multibanco	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 memilih API yang akan diintegrasikan, gunakan panduan metode pembayaran untuk membantu menentukan jenis metode pembayaran yang tepat yang perlu Anda dukung.

Panduan ini mencakup penjelasan mendetail tentang setiap metode pembayaran dan menjelaskan perbedaan arus yang dihadapi pelanggan, bersama dengan wilayah geografis yang paling relevan. Anda dapat mengaktifkan metode pembayaran yang tersedia di Dashboard. Aktivasi umumnya instan dan tidak memerlukan kontrak tambahan.

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.

Alipay
Debit Langsung Bacs
Debit Langsung SEPA

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.

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.

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "card",
  "address_city": "San Francisco",
  "address_country": "US",
  "address_line1": "1234 Fake Street",
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Fake Street",
      "line2": null,
      "postal_code": null,

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.