# Log perubahan Elements dengan Checkout Sessions API beta
Terus lacak perubahan pada integrasi Elements dengan Checkout Sessions API beta.
> Dokumen ini berisi log perubahan yang terkait dengan versi beta Elements dengan Checkout Sessions API.
>
> Log perubahan ini tidak berlaku untuk Anda jika Anda menggunakan [Clover](https://docs.stripe.com/changelog/clover.md) atau yang lebih baru. Lihat [log perubahan Stripe](https://docs.stripe.com/changelog.md) untuk detailnya.
## Bermigrasi ke Clover
### Perubahan semanggi
- (Breaking) Si [stripe.initCheckout](https://docs.stripe.com/js/custom_checkout/init) metode sekarang sinkron, bukan asinkron. Ini mengurangi latensi render dan memungkinkan Elements menampilkan pemuat kerangka lebih awal. Lihat [Memperbarui initCheckout menjadi sinkron](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md) untuk detail migrasi.
- (Breaking) Metode pembayaran yang disimpan sekarang secara otomatis diaktifkan di Elemen Pembayaran saat dikonfigurasi pada Sesi Checkout, tanpa memerlukan konfigurasi sisi klien tambahan. Lihat [Memperbarui perilaku default untuk metode pembayaran yang disimpan](https://docs.stripe.com/changelog/clover/2025-09-30/custom-checkout-saved-payment-method-defaults.md) untuk detailnya.
- (Breaking) Kode pos tidak lagi dikumpulkan secara otomatis untuk pembayaran kartu di Kanada, Inggris Raya, dan Puerto Riko. Lihat [Menghapus kode pos untuk pembayaran kartu](https://docs.stripe.com/changelog/clover/2025-09-30/postal_code_in_card_form_for_non_us_countries.md) jika Anda mengandalkan data ini.
- (Breaking) Untuk integrasi React:
- Jalur impor telah berubah dari `@stripe/react-stripe-js` ke `@stripe/react-stripe-js/checkout`.
- [useCheckout](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) kini mengembalikan disjoint union yang menggambarkan status asinkron (`{type: 'loading'}`, `{type: 'success', checkout: ...}`, atau `{type: 'error', error: ...}`) alih-alih melempar kesalahan.
- [CheckoutProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) kini selalu merender children tanpa syarat, bukan lagi merender `null` ketika [initCheckout](https://docs.stripe.com/js/custom_checkout/init) belum berhasil.
### Peningkatan semanggi
Sebelum bermigrasi ke Clover, pertama-tama [perbarui integrasi Anda](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#migrating-to-basil) ke Basil.
- Jika Anda menggunakan paket Stripe NPM apa pun, Anda harus meningkatkan `@stripe/stripe-js` ke setidaknya `8.0.0` dan `@stripe/react-stripe-js` ke setidaknya `5.0.0`.
- Jika Anda memuat Stripe.js melalui tag skrip, perbarui tag ke referensi `clover` menggunakan [versioned Stripe.js nomenclature](https://docs.stripe.com/sdks/stripejs-versioning.md) sebagai berikut:
```html
Checkout
```
- Perbarui versi API setidaknya `2025-09-30.clover` pada integrasi back-end Anda.
#### HTML + JS
Perbarui integrasi Anda sebagai berikut:
1. Hapus semua panggilan `await` atau `.then()` yang terkait dengan `initCheckout`.
1. Ganti `fetchClientSecret` fungsi dengan string rahasia klien atau Promise yang diselesaikan ke string rahasia klien.
1. Panggil fungsi asinkron baru `checkout.loadActions()` untuk mengakses tindakan seperti `getSession()`, yang menggantikan `session()`atau `confirm()`. Anda hanya perlu menelepon `loadActions()` sekali.
1. Jika sebelumnya Anda membungkus `initCheckout` dalam blok `try...catch`, periksa nilai `type` yang diselesaikan dari `loadActions()` alih-alih memeriksa kesalahan.
```javascript
const clientSecret = fetch("/create-checkout-session", {
method: "POST",
headers: { "Content-Type": "application/json" },
})
.then((r) => r.json())
.then((r) => r.clientSecret);
const checkout = stripe.initCheckout({
clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
const session = loadActionsResult.actions.getSession();
}
```
#### React
Tingkatkan Anda `@stripe/react-stripe-js` dependensi setidaknya versi `5.0.0`. Jika Anda meningkatkan dari versi yang lebih lama dari `4.0.0`, pastikan Anda membaca [catatan rilis v4.0.0](https://github.com/stripe/react-stripe-js/releases/tag/v4.0.0) untuk langkah migrasi tambahan.
#### Mengimpor perubahan
Perbarui impor Anda untuk menggunakan titik masuk khusus checkout baru:
```jsx
import {useCheckout, PaymentElement} from '@stripe/react-stripe-js/checkout';
```
#### Perubahan CheckoutProvider dan useCheckout
Mengganti `fetchClientSecret` dengan `clientSecret`. Anda sekarang dapat merender Elemen tanpa terlebih dahulu memeriksa apakah `useCheckout` Kembali `type: 'success'`, yang mengurangi latensi dan memungkinkan Elements menampilkan pemuat kerangka lebih awal.
```jsx
const App = () => {
const promise = useMemo(() => {
return fetch('/create-checkout-session', {
method: 'POST',
headers: { "Content-Type": "application/json" },
})
.then((res) => res.json())
.then((data) => data.clientSecret);
}, []);
return (
);
}
const CheckoutPage = () => {
const {type, ...rest} = useCheckout();
return (
);
}
```
Untuk detail selengkapnya, lihat [Memperbarui initCheckout menjadi sinkron](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md) entri changelog.
## Bermigrasi ke Basil
### Perubahan Basil
- (Breaking) Metode asinkron, seperti [confirm](https://docs.stripe.com/js/custom_checkout/confirm) atau [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), 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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) pada [confirm](https://docs.stripe.com/js/custom_checkout/confirm) bila [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) pada [confirm](https://docs.stripe.com/js/custom_checkout/confirm) atau [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/api/invoice-payment/list.md) untuk menemukan invoice terkait.
- Untuk mempelajari lebih lanjut, baca [2025-03-31.basil API changelog](https://docs.stripe.com/changelog/basil/2025-03-31/checkout-legacy-langganan-upgrade.md).
- Menambahkan [percentOff](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts-percentOff) ke [discountAmounts](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts) sebagai opsi untuk menampilkan diskon.
### Peningkatan Basil
Sebelum bermigrasi ke Basil, pertama-tama [perbarui integrasi Anda](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#beta-changelog) 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, dan Anda masih menggunakan `v3` atau `acacia`, perbarui tag tersebut untuk mereferensikan `basil` menggunakan [nomenklatur Stripe.js dengan versi](https://docs.stripe.com/sdks/stripejs-versi.md) sebagai berikut:
```html
Checkout
```
- Hapus header beta Stripe.js ketika menginisialisasi Stripe.js.
#### HTML + JS
```js
const stripe = Stripe(
'<>', {
}
);
```
#### React
```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<>", {
});
```
- Hapus header beta versi API dan tentukan versi API menjadi setidaknya `2025-03-31.basil` pada integrasi back-end Anda.
### Before
#### TypeScript
```javascript
// 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';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
apiVersion: '2026-04-22.dahlia; custom_checkout_beta=v1' as any,
});
```
### After
#### TypeScript
```javascript
// 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';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
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 (misalnya, `custom_checkout_beta=v1`), yang diatur pada integrasi backend Anda.
### Versi beta front-end
Tentukan versi beta front-end saat [menginisialisasi Stripe.js](https://docs.stripe.com/payments/quickstart-checkout-sessions.md).
#### 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](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-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](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-clientSecret). 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](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) kini merespons Billing Address Element atau Shipping Address Element yang terpasang.
- [canConfirm](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) kini menjadi `false` jika ada konfirmasi yang sedang diproses.
- Menghapus `confirmationRequirements`.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) kini menampilkan kesalahan jika [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-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.
- Misalnya, ganti `total.total` dengan [`total.total.minorUnitsAmount`](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-total-total-minorUnitsAmount).
- 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 dipungut. Pelajari cara [memungut ID pajak](https://docs.stripe.com/tax/checkout/tax-ids.md).
- 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](https://docs.stripe.com/js/custom_checkout/init)
- Dalam React Stripe.js, `CustomCheckoutProvider` telah diubah namanya menjadi `CheckoutProvider` dan `useCustomCheckout` telah diubah namanya menjadi `useCheckout`.
- Untuk mengonfirmasi Element Checkout Ekspres, hubungi [confirm](https://docs.stripe.com/js/custom_checkout/confirm), lalu teruskan [confirm event](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event) sebagai `expressCheckoutConfirmEvent`.
- Sebelumnya, Express Checkout Element dikonfirmasikan dengan memanggil `event.confirm()`.
- (Breaking) Bila [confirm](https://docs.stripe.com/js/custom_checkout/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 suatu 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](https://docs.stripe.com/js/custom_checkout/confirm) atau [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), 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](https://docs.stripe.com/js/custom_checkout/confirm).
- (Breaking) Address Element tidak lagi secara otomatis memperbarui bidang [billingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-billingAddress) atau [shippingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-shippingAddress) pada Sesi.
- Selama Address Element dipasang, nilai formulir akan secara otomatis digunakan ketika memanggil [confirm](https://docs.stripe.com/js/custom_checkout/confirm).
- Dengarkan [kejadian perubahan](https://docs.stripe.com/js/element/events/on_change?type=addressElement) untuk menggunakan nilai Address Element sebelum konfirmasi.
#### custom_checkout_beta_4
- Menambahkan [gambar](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-images) ke [objek Sesi](https://docs.stripe.com/js/custom_checkout/session_object).
- Menambahkan [bidang](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields) sebagai opsi ketika membuat Payment Element.
- Menambahkan [paymentMethods](https://docs.stripe.com/js/custom_checkout/create_express_checkout_element#custom_checkout_create_express_checkout_element-options-paymentMethods) sebagai opsi ketika membuat Express Checkout Element.
- (Breaking) Meneruskan opsi yang tidak valid ke [createElement](https://docs.stripe.com/js/custom_checkout/create_payment_element) kini memunculkan kesalahan. Sebelumnya, opsi yang tidak dikenal akan diabaikan secara diam-diam.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) dan [updatePhoneNumber](https://docs.stripe.com/js/custom_checkout/update_phone_number) 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](https://docs.stripe.com/js/custom_checkout/session_object):
- [id](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-id)
- [livemode](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-livemode)
- [businessName](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-businessName)
- Kartu yang disimpan sekarang dapat digunakan kembali. Pelajari cara [menyimpan dan menggunakan kembali](https://docs.stripe.com/payments/checkout/save-during-payment.md) metode pembayaran.
- (Breaking) Default [tata letak](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) dari Payment Element telah diubah ke `accordion`.
- Untuk terus menggunakan tata letak default sebelumnya, Anda harus menentukan `layout='tabs'`.
- (Breaking) Perilaku default [confirm](https://docs.stripe.com/js/custom_checkout/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’](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) ke `confirm`.
#### custom_checkout_beta_2
- (Breaking) Bidang `lineItem.recurring.interval_count` ini telah dihapus dan diganti dengan [lineItem.recurring.intervalCount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-recurring-intervalCount).
- (Breaking) Bidang `lineItem.amount` ini telah dihapus dan diganti dengan yang berikut ini:
- [lineItem.amountSubtotal](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountSubtotal)
- [lineItem.amountDiscount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountDiscount)
- [lineItem.amountTaxInclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxInclusive)
- [lineItem.amountTaxExclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxExclusive)
#### custom_checkout_beta_1
*Ini adalah versi beta front-end awal.*
### Versi back-end
Tentukan versi beta sisi belakang saat [menyiapkan pustaka server Anda](https://docs.stripe.com/payments/quickstart-checkout-sessions.md#init-stripe).
*Tidak ada perubahan pada versi beta backend.*