Panduan migrasi harga Checkout

Prices API menambahkan fleksibilitas dan fitur baru pada cara Anda men-charge pelanggan. Integrasi baru ini menawarkan:

• Pemodelan yang lebih terpadu untuk item Checkout—bukan paket, SKU, dan item baris dalam baris, setiap item sekarang menjadi harga.
• Kemampuan untuk menampilkan gambar produk untuk item rutin.
• Buat katalog harga dan produk yang dapat digunakan kembali, bukan mata anggaran satu kali.
• Buat skema biaya dalam baris untuk langganan.
• Terapkan tarif pajak dinamis pada langganan dan pembayaran satu kali.

Tidak ingin melakukan migrasi? Anda dapat terus menggunakan integrasi saat ini, tetapi fitur yang baru tidak didukung. Anda dapat menggunakan paket baru atau harga rutin yang Anda buat di parameter plan pada panggilan API yang ada.

Gambaran umum produk dan harga

Harga adalah entitas inti baru dalam Stripe yang berfungsi dengan langganan, invoice, dan Checkout. Setiap harga dikaitkan dengan satu Produk, dan setiap produk dapat memiliki beberapa harga. Barang fisik atau tingkat layanan yang berbeda harus diwakili oleh produk. Skema biaya produk itu harus diwakili oleh harga.

Harga menentukan harga dasar, mata uang, dan—untuk produk rutin—siklus tagihan. Hal ini memungkinkan Anda mengubah dan menambahkan harga tanpa perlu mengubah detail dari yang Anda tawarkan. Misalnya, Anda mungkin memiliki satu produk “emas” yang memiliki harga 10 USD/bulan, 100 USD/tahun, 9 EUR/bulan, dan 90 EUR/tahun. Atau Anda mungkin memiliki kaus biru dengan harga 20 USD dan 15 EUR.

Pembayaran satu kali

Integrasi untuk pembayaran satu kali memiliki beberapa perubahan sebagai berikut:

• Sebagai ganti item baris ad-hoc (yaitu, mengatur nama, jumlah, dan mata uang), pembuatan Sesi Checkout memerlukan pembuatan produk dan, biasanya, harga.
• mode sekarang diperlukan.

Kode sisi client tetap sama.

Tabel pemetaan

Sebagai ganti penentuan setiap bidang pada line_items, Checkout menggunakan objek harga dan produk pokok untuk menentukan nama, keterangan, jumlah, mata uang, dan gambar. Anda dapat membuat produk dan harga dengan API atau Dashboard.

Kode sisi server untuk item dalam baris

Sebelumnya, Anda hanya dapat membuat item satu kali dalam baris. Dengan harga, Anda dapat terus mengonfigurasi item dalam baris, tetapi juga dapat menentukan harga secara dinamis dengan price_data ketika Anda membuat Sesi Checkout.

Bila Anda membuat Sesi Checkout dengan price_data, referensikan identifikasi produk yang ada dengan price_data.product, atau tentukan detail produk Anda secara dinamis menggunakan price_data.product_data. Contoh berikut menunjukkan alur untuk membuat item satu kali.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][product_data][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][price_data][product_data][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][price_data][currency]"=usd \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Kode sisi server untuk harga satu kali

Dengan integrasi baru ini, Anda dapat membuat katalog produk dan harga di awal bukannya perlu menentukan jumlah, mata uang, dan nama setiap kali Anda membuat Sesi Checkout.

Anda dapat membuat produk dan harga dengan Prices API atau melalui Dashboard. Anda membutuhkan identifikasi harga untuk membuat Sesi Checkout. Contoh berikut menunjukkan cara membuat produk dan harga melalui API:

curl https://api.stripe.com/v1/products \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d name=T-shirt \
  -d description="Comfortable cotton t-shirt" \
  -d "images[]"="https://example.com/t-shirt.png"

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d product="{{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Subscriptions

Integrasi untuk pembayaran rutin memiliki beberapa perubahan sebagai berikut:

• Semua item diteruskan ke satu bidang line_items, bukan subscription_data.items.
• mode sekarang diperlukan. Atur mode=subscription jika sesi menyertakan item rutin.

Kode sisi client tetap sama. Paket yang ada dapat digunakan di mana pun harga rutin disetujui.

Kode sisi server dengan paket

Berikut adalah contoh sebelum dan sesudah membuat Sesi Pembayaran dengan uji coba dan menggunakan paket yang ada, yang dapat digunakan secara bergantian dengan harga. Paket sekarang diteruskan ke line_items bukan subscription_data.items.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "subscription_data[items][][plan]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Kode sisi server untuk harga rutin dengan biaya penyiapan

Jika Anda memiliki paket rutin dengan biaya penyiapan satu kali, buat produk dan harga yang mewakili biaya satu kali tersebut sebelum membuat Sesi Checkout. Lihat tabel pemetaan untuk mengetahui cara bidang line_items yang lama memetakan ke integrasi baru. Anda dapat membuat produk dan harga melalui Prices API atau melalui Dashboard Stripe. Anda juga dapat membuat item satu kali dalam baris. Contoh berikut menggunakan identifikasi harga yang ada:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "subscription_data[items][][plan]"="{{PLAN_ID}}" \
  -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[1][price]"="{{ONE_TIME_PRICE_ID}}" \
  -d "line_items[1][quantity]"=1 \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Perubahan objek respons

Sebagai ganti pencantuman item dengan display_items, objek Checkout Session menggunakan line_items. Bidang line_items tidak ditampilkan secara default seperti yang dilakukan display_items, tetapi Anda dapat menyertakannya menggunakan perluas ketika membuat Sesi Checkout:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method_types[]"="card" \
  -d "mode"="payment" \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "success_url"="https://example.com/success" \
  -d "cancel_url"="https://example.com/cancel" \
  -d "expand[]"="line_items"

Perubahan webhook

Karena line_items dapat termasuk, respons webhook checkout.session.completed tidak lagi mencantumkan item secara default. Objek respons yang lebih kecil memungkinkan Anda menerima webhook Checkout lebih cepat. Anda dapat mengambil item dengan endpoint line_items yang baru:

curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Untuk detail selengkapnya, lihat pemenuhan pesanan dengan Checkout.