# Upgrade integrasi Anda Tingkatkan integrasi Anda ke versi API terbaru. Periksa [Changelog Pengembang](https://docs.stripe.com/changelog.md) untuk catatan lengkap perubahan pada API Stripe. Untuk meningkatkan versi integrasi, selesaikan langkah berikut. Cari [Changelog](https://docs.stripe.com/changelog.md?api_usage=true) untuk mendapatkan informasi khusus tentang integrasi Anda. ## Tentukan versi target untuk pembaruan Anda Pastikan Anda menentukan versi API yang Anda integrasikan dalam kode alih-alih mengandalkan versi API default akun Anda. Untuk menguji versi yang lebih baru untuk panggilan API, atur header `Stripe-Version` (di lingkungan live atau pengujian). Pelajari cara [mengatur versi API di SDK sisi server kami](https://docs.stripe.com/upgrades.md#specify-sdk-api-version). Lihat versi API yang digunakan integrasi Anda di [Tab Gambaran Umum](https://dashboard.stripe.com/workbench/overview) di [Workbench](https://docs.stripe.com/workbench/overview.md). Tinjau [Changelog](https://docs.stripe.com/changelog.md) untuk menemukan versi target untuk pembaruan Anda. ## Tentukan versi API di SDK Anda Akun Anda memiliki *versi API bawaan* (If an API request doesn’t specify a version, Stripe uses your account’s default API version, which you can set in the Stripe Dashboard. We recommend specifying the version for each request (either with the Stripe-Version HTTP header or by using a pinned SDK) so your code determines the API version instead of your Dashboard settings) yang menentukan cara Anda melakukan pemanggilan API, fungsionalitas yang dapat Anda akses, serta struktur respons API. Saat menggunakan [SDK sisi server](https://docs.stripe.com/sdks.md#server-side-libraries), panggilan API Anda ke Stripe akan menggunakan versi API yang terbaru pada saat SDK tersebut dirilis. Anda tidak dapat menargetkan versi API yang berbeda jika menggunakan bahasa pemrograman strongly typed, seperti Java, Go, atau .NET. #### Ruby Pustaka [stripe-ruby](https://github.com/stripe/stripe-ruby) memungkinkan Anda menetapkan versi API secara global atau per permintaan. Jika Anda tidak menetapkan versi API, versi stripe-ruby terbaru menggunakan versi API yang terbaru pada saat versi stripe-ruby Anda dirilis. Versi stripe-ruby sebelum [v9](https://github.com/stripe/stripe-ruby/blob/master/CHANGELOG.md#900---2023-08-16) menggunakan versi API default akun Anda. Untuk menetapkan versi API secara **global** dengan SDK, tetapkan versinya pada properti `Stripe.api_version`: ```ruby require 'stripe' # Don't put any keys in code. See /keys-best-practices. client = Stripe::StripeClient.new('<>', stripe_version: '2026-08-26.dahlia') ``` Atau tetapkan versi per-permintaan: ```ruby require 'stripe' # Don't put any keys in code. See /keys-best-practices. client = Stripe::StripeClient.new('<>') intent = client.v1.payment_intents.retrieve( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', { stripe_version: '2026-08-26.dahlia', }, ) intent.capture ``` > Ketika Anda mengesampingkan versi secara global atau per-permintaan, objek respons API juga dikembalikan dalam versi tersebut. #### Python Pustaka [stripe-python](https://github.com/stripe/stripe-python) memungkinkan Anda mengatur versi API secara global atau per permintaan. Jika Anda tidak menetapkan versi API, versi stripe-python terbaru menggunakan versi API yang terbaru pada saat versi stripe-python Anda dirilis. Versi stripe-python sebelum [v6](https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md#600---2023-08-16) menggunakan versi API default akun Anda. Untuk menetapkan versi API secara **global** dengan SDK, tetapkan versi ke properti `stripe.api_version`: ```python import stripe # Don't put any keys in code. See /keys-best-practices. stripe.api_key = <> stripe.api_version = '2026-08-26.dahlia' ``` Atau tetapkan versi per permintaan: ```python import stripe intent = stripe.PaymentIntent.retrieve( "pi_1DlIVK2eZvKYlo2CW4yj5l2C", stripe_version="2026-08-26.dahlia", ) intent.capture() ``` > Saat Anda mengesampingkan versi secara global atau per permintaan, objek respons API juga dikembalikan dalam versi tersebut. #### PHP Pustaka [stripe-php](https://github.com/stripe/stripe-php) memungkinkan Anda menetapkan versi API secara global atau per permintaan. Jika Anda tidak mengatur versi API, versi stripe-php terbaru menggunakan versi API yang terbaru pada saat versi stripe-php Anda dirilis. Versi stripe-php sebelum [v11](https://github.com/stripe/stripe-php/blob/master/CHANGELOG.md#1100---2023-08-16) menggunakan versi API default akun Anda. Untuk mengatur versi API **secara global** dengan SDK, teruskan versi tersebut ke metode `\Stripe\Stripe::setApiVersion()`: ```php $stripe = new \Stripe\StripeClient([ // Don't put any keys in code. See /keys-best-practices. "api_key" => "<>", "stripe_version" => "2026-08-26.dahlia" ]); ``` Atau atur versi per-permintaan: ```php $intent = $stripe->paymentIntents->capture( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', [], ['stripe_version' => '2026-08-26.dahlia'] ); ``` > Saat Anda mengesampingkan versi secara global atau per-permintaan, objek respons API juga dikembalikan dalam versi tersebut. #### Java Karena Java adalah bahasa pemrograman dengan tipe yang kuat, versi API yang digunakan dalam SDK bersifat *tetap* dan merupakan versi API terbaru pada saat rilis SDK. Kami tidak menyarankan untuk menetapkan versi API yang berbeda untuk bahasa pemrograman dengan tipe yang kuat, karena objek respons mungkin tidak sesuai dengan tipe yang kuat dalam SDK dan mengakibatkan kegagalan permintaan. Misalnya, jika versi API yang Anda targetkan memerlukan parameter yang tidak ada dalam tipe SDK, permintaan akan gagal. #### Node Pustaka [stripe-node](https://github.com/stripe/stripe-node) memungkinkan Anda mengatur versi API secara global atau per permintaan. Jika Anda tidak menetapkan versi API, versi stripe-node terbaru akan menggunakan versi API yang terbaru pada saat versi stripe-node Anda dirilis. Versi stripe-node sebelum [v12](https://github.com/stripe/stripe-node/blob/master/CHANGELOG.md#1200---2023-04-06) menggunakan versi API default akun Anda. Untuk menetapkan versi API secara **global** menggunakan SDK, sediakan opsi `apiVersion`: ```javascript // Don't put any keys in code. See /keys-best-practices. const stripe = require('stripe')('<>', { apiVersion: '2026-08-26.dahlia', }); ``` Atau tetapkan versi per permintaan: ```javascript const intent = await stripe.paymentIntents.retrieve('pi_1DlIVK2eZvKYlo2CW4yj5l2C', { apiVersion: '2026-08-26.dahlia', }); ``` #### Penggunaan TypeScript Jenis TypeScript mencerminkan versi API terbaru pada saat rilis. Versi ini dienkode dalam [file API_VERSION](https://github.com/stripe/stripe-node/blob/master/API_VERSION). Impor Stripe sebagai impor default dan buat instance sebagai `new Stripe()` dengan versi API terbaru. ```javascript import Stripe from 'stripe'; const stripe = new Stripe('<>', { apiVersion: '2026-08-26.dahlia' }); ``` #### Go Karena Go adalah bahasa pemrograman dengan tipe yang kuat, versi API yang digunakan dalam SDK bersifat *tetap* dan merupakan versi API terbaru pada saat rilis SDK. Kami tidak menyarankan untuk menetapkan versi API yang berbeda untuk bahasa pemrograman dengan tipe yang kuat, karena objek respons mungkin tidak sesuai dengan tipe yang kuat dalam SDK dan mengakibatkan kegagalan permintaan. Misalnya, jika versi API yang Anda targetkan memerlukan parameter yang tidak ada dalam tipe SDK, permintaan akan gagal. #### .NET Karena C# adalah bahasa pemrograman dengan tipe yang kuat, versi API yang digunakan dalam SDK .NET bersifat *tetap* dan merupakan versi API terbaru pada saat rilis SDK. Kami tidak menyarankan untuk menetapkan versi API yang berbeda untuk bahasa pemrograman dengan tipe yang kuat, karena objek respons mungkin tidak sesuai dengan tipe yang kuat dalam SDK dan mengakibatkan kegagalan permintaan. Misalnya, jika versi API yang Anda targetkan memerlukan parameter yang tidak ada dalam tipe SDK, permintaan akan gagal. #### cURL ```sh curl https://api.stripe.com/v1/charges \ -u <>: \ -H "Stripe-Version: 2026-08-26.dahlia" ``` #### Stripe CLI ```sh stripe charges create --stripe-version 2026-08-26.dahlia ``` ## Perbarui kode untuk menangani perubahan API Tinjau permintaan terpenting Anda dan perbarui kode untuk menangani perubahan pada respons. Untuk setiap permintaan, tinjau [breaking change yang relevan di changelog](https://docs.stripe.com/changelog.md?api_usage=true) guna memahami perubahan yang diperlukan untuk menggunakan versi target Anda. Lihat permintaan API Anda di [Tab Gambaran Umum](https://dashboard.stripe.com/workbench/overview) di [Workbench](https://docs.stripe.com/workbench/overview.md). ## Perbarui tujuan peristiwa Anda > [Thin event](https://docs.stripe.com/event-destinations.md#thin-events) untuk sumber daya API v1 sekarang tersedia dalam pratinjau privat. Anda dapat menggunakannya untuk menyederhanakan peningkatan integrasi tanpa perlu mengubah konfigurasi webhook. Sebelumnya, thin event hanya mendukung sumber daya API v2. [Pelajari selengkapnya dan minta akses](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Tinjau setiap tujuan peristiwa yang menerima peristiwa snapshot, termasuk endpoint webhook dan tujuan cloud untuk Amazon EventBridge serta Azure Event Grid. Untuk peristiwa snapshot, properti [snapshot_api_version](https://docs.stripe.com/api/v2/core/event-destinations/object.md#v2_event_destination_object-snapshot_api_version) pada tujuan tersebut mengontrol versi API yang digunakan untuk merender payload peristiwa. Pengaturan ini tidak bergantung pada versi API yang digunakan oleh SDK sisi server Anda. Payload peristiwa berukuran kecil tidak memiliki versi. Anda hanya dapat menetapkan `snapshot_api_version` saat membuat tujuan peristiwa. Untuk menggunakan versi API yang berbeda, buat dan uji tujuan yang dikonfigurasi dengan versi tersebut sebelum menghapus tujuan yang sudah ada. Jika kedua tujuan aktif selama migrasi, penangan peristiwa Anda harus bersifat idempoten karena Stripe mengirimkan peristiwa yang memiliki langganan ke kedua tujuan. ## Perbarui endpoint webhook Untuk melakukan peningkatan pada endpoint webhook, Anda perlu [memverifikasi tanda tangan webhook yang masuk](https://docs.stripe.com/webhooks.md#verify-events) dan mengizinkan lalu lintas dari [alamat IP publik](https://docs.stripe.com/ips.md) Stripe. Anda juga perlu membuat endpoint baru, mengalihkan lalu lintas ke endpoint tersebut, lalu menonaktifkan endpoint yang lama. #### Buat endpoint webhook nonaktif yang baru Buat endpoint webhook baru dengan parameter berikut: - `url`: URL yang sama dengan endpoint webhook asli Anda, tetapi tambahkan parameter query untuk membedakan peristiwa yang dikirim ke dua endpoint yang berbeda. Sebagai contoh `https://example.com/webhooks?version=2024-04-10`. - `enabled_events`: peristiwa yang sama dengan endpoint webhook asli Anda. - `api_version`: versi API yang ingin Anda mutakhirkan. Jika memutakhirkan ke versi API terbaru, Anda dapat menggunakan Dashboard atau API untuk membuat endpoint tersebut. Untuk versi lainnya, gunakan API untuk menetapkan versi tertentu. Setelah Anda membuat endpoint webhook baru, nonaktifkan endpoint tersebut. Anda akan mengaktifkannya kembali pada langkah berikutnya. ![Dua endpoint, tetapi hanya endpoint lama yang mengirimkan peristiwa](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png) #### Perbarui kode webhook agar mengabaikan peristiwa yang dikirim ke endpoint baru Perbarui kode pemrosesan peristiwa Anda: - Jika parameter query ditujukan untuk versi API lama, proses seperti biasa. - Jika parameter query ditujukan untuk versi API baru, abaikan peristiwa dan kembalikan respons 200 untuk mencegah percobaan ulang pengiriman. Selanjutnya, aktifkan endpoint webhook baru yang Anda buat pada langkah sebelumnya. Pada titik ini setiap peristiwa dikirim dua kali: satu kali dengan versi API lama dan satu kali dengan yang baru. ![Dua endpoint mengirimkan peristiwa, tetapi hanya memproses yang lama](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png) #### Perbarui kode webhook untuk memproses peristiwa bagi endpoint baru Perbarui kode pemrosesan peristiwa Anda: - Jika parameter query untuk versi lama, abaikan peristiwa tersebut. Kami menyarankan untuk mengembalikan status 400 agar Stripe mengulang peristiwa secara otomatis. Ini memastikan bahwa jika Anda perlu mengembalikan, peristiwa akan dikirim ulang ke endpoint webhook lama. - Jika parameter query untuk versi baru, proses peristiwa tersebut. ![Dua endpoint mengirim peristiwa, tetapi hanya memproses yang baru](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png) #### Pantau endpoint webhook Anda Pantau trafik ke endpoint webhook baru untuk mengonfirmasi bahwa mereka memproses peristiwa dengan benar. Jika peristiwa tidak ditangani dengan benar oleh kode baru Anda, coba yang berikut ini: 1. Kembalikan ke versi kode Anda sebelumnya. 2. Nonaktifkan sementara endpoint webhook baru. 3. Proses peristiwa yang gagal (jika Anda mengembalikan status 400 seperti yang dijelaskan pada langkah sebelumnya, Stripe secara otomatis mengirim ulang semua peristiwa). 4. Selidiki dan perbaiki masalah. 5. Aktifkan endpoint webhook baru dan lanjutkan pemantauan. #### Nonaktifkan endpoint webhook lama Setelah peningkatan berhasil, nonaktifkan endpoint webhook lama agar server Anda berhenti mengembalikan status `400`. Jika Anda tidak menonaktifkannya, hal ini dapat menyebabkan masalah dengan integrasi yang bergantung pada respons `200`. Setelah Anda menonaktifkan endpoint webhook yang lama, Stripe tidak akan mengirim ulang peristiwa yang mengembalikan `400`. ![Dua endpoint, tetapi hanya endpoint baru yang mengirim peristiwa](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png) ## Tes dan pantau integrasi Anda [Uji integrasi Anda](https://docs.stripe.com/testing.md) di [sandbox](https://docs.stripe.com/sandboxes.md) untuk memastikan integrasi tersebut dapat menangani versi yang baru sesuai harapan. Selain panduan pengujian umum, ikuti panduan untuk produk dan sumber daya yang digunakan integrasi Anda: - [Billing](https://docs.stripe.com/billing/testing.md): Gunakan [jam percobaan](https://docs.stripe.com/billing/testing/test-clocks.md) untuk [menyimulasikan langganan](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md). - [Invoicing](https://docs.stripe.com/invoicing/integration/testing.md): Uji notifikasi webhook, kegagalan pembayaran, dan skenario lain. - [Connect](https://docs.stripe.com/connect/testing.md): Buat [akun pengujian](https://docs.stripe.com/connect/testing.md?accounts-namespace=v2#creating-accounts) dan gunakan untuk [pengujian verifikasi](https://docs.stripe.com/connect/testing-verification.md). - [Terminal](https://docs.stripe.com/terminal/references/testing.md): Uji [pembaruan reader yang disimulasikan](https://docs.stripe.com/terminal/references/testing.md?terminal-card-present-integration=terminal#simulated-reader-updates). - [Payment Intents](https://docs.stripe.com/payments/quickstart-payment-intents.md#test-payment): Buat PaymentIntent dan gunakan nomor kartu percobaan untuk menyimulasikan pembayaran.