Lewati ke konten
Buat akun
 atau
Masuk
Logo Dokumen Stripe
/
Buat akun
Masuk
Gambaran UmumUpgrade integrasi Anda
Pembayaran online
Gambaran umumTemukan contoh penggunaan AndaPembayaran Terkelola
Metode Pembayaran
Antarmuka pembayaran
Skenario pembayaran
Pembayaran di tempat
Produk Stripe lainnya

Log perubahan Elements dengan Checkout Sessions API beta

Terus lacak perubahan pada integrasi Elements dengan Checkout Sessions API beta.

Salin halaman

Peringatan

Dokumen ini berisi log perubahan yang terkait dengan versi beta Elements dengan Checkout Sessions API.

Jika Anda sudah menggunakan rilis Basil dari Elements dengan Checkout Sessions API, dokumen ini tidak berlaku untuk Anda.

Bermigrasi ke Basil

Perubahan

  • Breaking Metode asinkron, seperti confirm atau applyPromotionCode, diselesaikan dengan skema yang berbeda:
    • Jika berhasil, status sesi yang diperbarui diisi di bawah kunci session. Sebelumnya, ini berada di bawah kunci success.
  • Breaking Kesalahan sekarang muncul saat meneruskan returnUrl pada confirm bila return_url sudah diatur pada Sesi Checkout.
  • Breaking URL kembali yang dialihkan setelah konfirmasi berhasil sebelumnya memiliki parameter query yang tidak konsisten. Parameter tambahan sekarang dihapus dan URL hanya berisi hal yang disediakan di returnUrl pada confirm atau return_url pada Sesi Checkout.
  • Breaking Meningkatkan latensi pada Checkout Sessions API untuk Sesi mode langganan dan memperbaiki bug yang mencegah pelanggan Anda memperbarui Sesi setelah upaya pembayaran pertama
    • Perubahan membuat langganan setelah pengguna menyelesaikan pembayaran, jadi checkout_session.invoice dan checkout_session.subscription adalah nol hingga Sesi Checkout selesai.
    • Jika saat ini Anda mengandalkan bidang payment_intent.invoice yang tidak lagi digunakan, kami merekomendasikan penggunaan webhook checkout_session.completed, yang memastikan adanya invoice, dan checkout_session.invoice atau Daftar Pembayaran Invoice untuk menemukan invoice terkait.
    • Untuk mempelajari selengkapnya, baca log perubahan API.
  • Menambahkan percentOff ke discountAmounts sebagai opsi untuk menampilkan diskon.

Upgrade

Sebelum bermigrasi ke Basil, pertama-tama perbarui integrasi Anda ke custom_checkout_beta_6.

  • Jika Anda menggunakan paket Stripe NPM, Anda harus terlebih dahulu meningkatkan @stripe/stripe-js ke minimal 7.0.0 dan @stripe/react-stripe-js ke minimal 3.6.0.
  • Jika Anda memuat Stripe.js melalui tag skrip, perbarui tag skrip untuk menggunakan Stripe.js berversi dengan mengganti tag sebagai berikut:
checkout.html
<head>
 <title>Checkout</title>
 <script src="https://js.stripe.com/v3"></script>
 <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>
  • Hapus header beta Stripe.js ketika menginisialisasi Stripe.js.
checkout.js
const stripe = Stripe(
  
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_beta_6'],
  }
);
  • Hapus header beta versi API dan tentukan versi API menjadi setidaknya 2025-03-31.basil pada integrasi back-end Anda.
Sebelum
Setelah
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-05-28.basil; custom_checkout_beta=v1' as any,
});
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-03-31.basil' as any,
});

Log perubahan beta

Elements dengan Checkout Sessions API beta menggunakan dua jenis versi beta:

  • Header beta Stripe.js (misalnya, custom_checkout_beta_6), yang diatur pada integrasi front-end Anda.
  • Header beta versi API (mis., custom_checkout_beta=v1), yang diatur pada integrasi backend Anda.

Versi beta front-end

Tentukan versi beta front-end ketika menginisialisasi Stripe.js.

custom_checkout_beta_6

Jika menggunakan paket Stripe NPM, Anda harus terlebih dahulu melakukan upgrade @stripe/stripe-js ke minimal 6.1.0 dan @stripe/react-stripe-js ke minimal 3.5.0.

  • Breaking Tanda total.appliedBalance telah dibalik. Angka positif kini meningkatkan jumlah yang harus dibayar, dan angka negatif mengurangi jumlah yang harus dibayar.
  • Breaking Mengganti clientSecret dengan fetchClientSecret. Perbarui integrasi Anda untuk meneruskan fungsi asinkron yang diselesaikan ke client secret, bukan meneruskan nilai statis.
  • Breaking Metode Elements telah diganti namanya.
    • Jika menggunakan React Stripe.js, Anda tidak perlu melakukan apa-apa kecuali upgrade @stripe/react-stripe-js.
    • Jika Anda menggunakan HTML/JS:
      • Gunakan createPaymentElement() sebagai ganti createElement('payment').
      • Gunakan createBillingAddressElement() sebagai ganti createElement('address', {mode: 'billing'}).
      • Gunakan createShippingAddressElement() sebagai ganti createElement('address', {mode: 'shipping'}).
      • Gunakan createExpressCheckoutElement() sebagai ganti createElement('expressCheckout').
      • Gunakan getPaymentElement() sebagai ganti getElement('payment').
      • Gunakan getBillingAddressElement() sebagai ganti getElement('address', {mode: 'billing'}).
      • Gunakan getShippingAddressElement() sebagai ganti getElement('address', {mode: 'shipping'}).
      • Gunakan getExpressCheckoutElement() sebagai ganti getElement('expressCheckout').
  • Breaking Memperbarui bidang yang terkait dengan konfirmasi agar mencerminkan status sesi secara lebih akurat.
    • canConfirm kini merespons Billing Address Element atau Shipping Address Element yang terpasang.
    • canConfirm kini menjadi false jika ada konfirmasi yang sedang diproses.
    • Menghapus confirmationRequirements.
  • Breaking updateEmail kini menampilkan kesalahan jika customer_email diberikan ketika membuat Sesi Checkout. Jika Anda bermaksud mengisi otomatis email yang dapat diperbarui pelanggan, panggil updateEmail segera setelah halaman dimuat, bukan meneruskan customer_email.
  • Breaking returnUrl harus berupa URL absolut (misalnya, dimulai dengan https:// dan bukan URL relatif, seperti /success).
  • Breaking Bidang skema biaya yang diperbarui ke objek bersarang untuk kemudahan rendering.
    • Mengganti nilai numerik dengan objek yang berisi amount (string mata uang berformat, seperti $10.00) dan minorUnitsAmount, bilangan bulat yang mewakili nilai dalam unit terkecil mata uang. Jika Anda sudah membaca jumlahnya, baca dari minorUnitsAmount sebagai gantinya.
    • Anda harus membaca total.total.amount atau masing-masing dari total.total.minorUnitsAmount dan currency serta minorUnitsAmountDivisor dari objek checkout dan tampilan di UI, jika tidak maka akan terjadi kesalahan. Hal ini membantu menjaga agar halaman checkout Anda tetap sinkron seiring dengan pembaruan CheckoutSession, termasuk menambahkan fitur Stripe mendatang, dengan sedikit perubahan kode UI.
  • ID pajak pelanggan kini dapat dikumpulkan. Pelajari cara mengumpulkan ID pajak.
  • Asisten khusus mode percobaan kini tersedia di bagian bawah halaman checkout, yang menawarkan panduan untuk integrasi Anda dan pintasan untuk skenario percobaan umum.

custom_checkout_beta_5

  • Breaking Fungsi initCustomCheckout telah diganti namanya menjadi initCheckout
    • Dalam React Stripe.js, CustomCheckoutProvider telah diubah namanya menjadi CheckoutProvider dan useCustomCheckout telah diubah namanya menjadi useCheckout.
  • Breaking Untuk mengonfirmasikan Express Checkout Element, panggil confirm, sehingga meneruskan confirm event sebagai expressCheckoutConfirmEvent
    • Sebelumnya, Express Checkout Element dikonfirmasikan dengan memanggil event.confirm().
  • Breaking Bila confirm dipanggil, Payment Element dan Address Element akan memvalidasi input formulir serta menampilkan kesalahan.
  • Breaking Pesan kesalahan telah distandardisasi dan ditingkatkan.
    • Kesalahan yang dikembalikan/diselesaikan oleh fungsi mewakili skenario yang diketahui seperti detail pembayaran yang tidak valid atau dana yang tidak mencukupi. Ini adalah masalah yang dapat diprediksi dan dapat dikomunikasikan kepada pelanggan Anda dengan menampilkan message pada halaman checkout.
    • Kesalahan yang dilemparkan/ditolak oleh fungsi mewakili kesalahan dalam integrasi itu sendiri, seperti parameter atau konfigurasi yang tidak valid. Kesalahan ini tidak dimaksudkan untuk ditampilkan kepada pelanggan Anda.
  • Breaking Metode asinkron, seperti confirm atau applyPromotionCode, diselesaikan dengan skema yang berbeda:
    • Bidang diskriminator type="success"|"error" telah ditambahkan.
    • Jika berhasil, status sesi yang diperbarui diisi di bawah kunci success. Sebelumnya, ini berada di bawah kunci session.
    • Jika tidak, kesalahan akan terus diisi di bawah kunci error.
  • Menambahkan opsi email, phoneNumber, billingAddress, dan shippingAddress ke confirm.
  • Breaking Address Element tidak lagi secara otomatis memperbarui bidang billingAddress atau shippingAddress pada Sesi.
    • Selama Address Element dipasang, nilai formulir akan secara otomatis digunakan ketika memanggil confirm.
    • Dengarkan kejadian perubahan untuk menggunakan nilai Address Element sebelum konfirmasi.

custom_checkout_beta_4

  • Menambahkan gambar ke objek Sesi.
  • Menambahkan bidang sebagai opsi ketika membuat Payment Element.
  • Menambahkan paymentMethods sebagai opsi ketika membuat Express Checkout Element.
  • Breaking Meneruskan opsi yang tidak valid ke createElement kini memunculkan kesalahan. Sebelumnya, opsi yang tidak dikenal akan diabaikan secara diam-diam.
  • Breaking updateEmail dan updatePhoneNumber menerapkan perubahan secara asinkron. Memanggil metode ini sebelum pelanggan selesai memasukkan nilai lengkap dapat menyebabkan kinerja yang buruk.
    • Sebagai ganti menelepon updateEmail atau updatePhoneNumber pada setiap kejadian perubahan input, tunggu sampai pelanggan Anda menyelesaikan input, seperti pada input yang mengabur atau saat mereka menyerahkan formulir untuk pembayaran.
    • updateEmail sekarang memvalidasi bahwa input adalah alamat email yang dibentuk dengan benar dan mengembalikan kesalahan jika input yang tidak valid digunakan.
    • updatePhoneNumber masih tidak melakukan validasi pada string input.

custom_checkout_beta_3

  • Bidang berikut telah ditambahkan ke objek Sesi:
  • Kartu yang disimpan sekarang dapat digunakan kembali. Pelajari cara menyimpan dan menggunakan kembali metode pembayaran.
  • Breaking Default tata letak dari Payment Element telah diubah ke accordion.
    • Untuk terus menggunakan tata letak default sebelumnya, Anda harus menentukan layout='tabs'.
  • Breaking Perilaku default confirm telah diubah untuk selalu dialihkan ke return_url Anda setelah konfirmasi berhasil.
    • Sebelumnya, confirm dialihkan hanya jika pelanggan memilih metode pembayaran berbasis pengalihan. Untuk terus menggunakan perilaku lama, Anda harus meneruskan pengalihan=‘if_required’ ke confirm.

custom_checkout_beta_2

custom_checkout_beta_1

Ini adalah versi beta front-end awal.

Log perubahan backend

Tentukan versi beta back-end ketika menyiapkan pustaka server Anda.

Tidak ada perubahan pada versi beta backend.

Apakah halaman ini membantu?
YaTidak
Butuh bantuan? Hubungi Tim CS.
Bergabunglah dengan program akses awal kami.
Lihat log perubahan kami.
Ada pertanyaan? Hubungi Bagian Penjualan.
LLM? Baca llms.txt.
Dijalankan oleh Markdoc