Lewati ke konten
Buat akun
atau
Masuk
Logo Dokumen Stripe
/
Tanya AI
Buat akun
Masuk
Mulai
Pembayaran
Otomatisasi keuangan
Platform dan situs belanja online
Manajemen uang
Alat bantu pengembang
Mulai
Pembayaran
Otomatisasi keuangan
Mulai
Pembayaran
Otomatisasi keuangan
Platform dan situs belanja online
Manajemen uang
Gambaran Umum
Pembuatan versi
Log perubahan
Tingkatkan versi API Anda
Upgrade versi SDK Anda
Alat bantu pengembang
SDK
API
    API v2
    Kunci API
    Header Stripe-Context
    Log perubahan harian
    Batas tingkat
    Percobaan otomatis
    Metadata
    Memperluas respons
      Contoh penggunaan
    Penomoran halaman
    Domain dan alamat IP
    Cari
    Pelokalan
    Penanganan kesalahan
    Kode kesalahan
Pengujian
Workbench
Tujuan Kejadian
Alur kerja
Stripe CLI
Stripe Shell
Dashboard Pengembang
Toolkit agen
Bangun dengan LLMStripe untuk Visual Studio CodePeringatan kesehatan StripePengunggahan file
Security and privacy
Keamanan
Privasi
Perluas Stripe
Stripe Apps
Stripe Connector
Mitra
Ekosistem mitra
Sertifikasi mitra
BerandaAlat bantu pengembangAPI

Memperluas respons

Pelajari cara mengurangi jumlah permintaan yang Anda buat ke Stripe API dengan memperluas objek dalam respons.

Salin halaman

Panduan ini menerangkan cara meminta properti tambahan dari API. Anda akan mempelajari pengubahan permintaan untuk menyertakan:

  • properti dari objek terkait
  • properti dari objek yang terkait jauh
  • properti tambahan pada semua objek dalam daftar
  • properti yang tidak disertakan secara default dalam respons

Cara kerjanya

Stripe API diatur ke dalam sumber daya yang diwakili oleh objek dengan properti kontekstual, konfigurasi, dan status. Semua objek ini memiliki identifikasi unik yang dapat Anda gunakan untuk mengambil, memperbarui, serta menghapusnya. API juga menggunakan identifikasi ini untuk menautkan objek terkait bersamaan. Misalnya, sebuah Sesi Checkout menautkan ke Pelanggan dengan Identifikasi Pelanggan.

{ "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ... "customer": "cus_HQmikpKnGHkNwW", ... }

Dalam hal Anda membutuhkan informasi dari objek yang ditautkan, Anda dapat mengambil objek yang ditautkan dalam panggilan baru menggunakan identifikasinya. Namun, pendekatan ini memerlukan dua permintaan API untuk mengakses satu nilai saja. Jika Anda membutuhkan informasi dari beberapa objek yang ditautkan, masing-masing juga mengharuskan permintaan terpisah, yang semuanya menambah latensi dan kompleksitas aplikasi Anda.

API memiliki fitur Perluas yang memungkinkan Anda mengambil objek yang ditautkan dalam satu panggilan, secara efektif menggantikan identifikasi objek dengan semua properti dan nilainya. Misalnya, Anda ingin mengakses detail tentang pelanggan yang dikaitkan dengan Sesi Checkout tertentu. Anda akan mengambil Sesi Checkout dan meneruskan properti customer ke larik expand, yang memberi tahu Stripe untuk menyertakan seluruh objek Customer dalam respons:

Command Line
cURL
curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}}
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "expand[]"=customer

Yang mengembalikan Sesi Checkout dengan objek Customer lengkap, bukan identifikasinya:

{ "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ... "customer": { "id": "cus_HQmikpKnGHkNwW", "object": "customer", ... "metadata": { "user_id": "user_xyz" }, ... } }

Catatan

Tidak semua properti dapat diperluas. Referensi API menandai properti yang dapat diperluas dengan label “Dapat diperluas”.

Memperluas beberapa properti

Untuk memperluas beberapa properti dalam satu panggilan, tambahkan item tambahan ke larik perluas. Misalnya, jika Anda ingin memperluas customer maupun payment_intent untuk Sesi Checkout tertentu, Anda harus meneruskan expand larik dengan string customer maupun payment_intent:

Command Line
cURL
curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}}
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "expand[]"=customer \ -d "expand[]"=payment_intent

Memperluas beberapa level

Jika nilai yang Anda inginkan bersarang sangat dalam di beberapa sumber daya yang ditautkan, Anda dapat menjangkaunya dengan memperluas secara berulang menggunakan notasi titik. Misalnya, jika Anda perlu mengetahui tipe metode pembayaran yang digunakan untuk Sesi Checkout tertentu, pertama-tama Anda mengambil maksud pembayaran Sesi Checkout, kemudian mengambil metode pembayaran yang dikaitkan dari maksud pembayaran untuk mendapatkan tipenya. Dengan expand, Anda dapat melakukan hal ini dalam satu panggilan:

Command Line
cURL
curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}}
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "expand[]"="payment_intent.payment_method"

Yang mengembalikan Sesi Checkout dengan objek PaymentIntent dan PaymentMethod lengkap sebagai ganti identifikasinya:

{ "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ... "mode": "payment", "payment_intent": { "id": "pi_1GkXXDLHughnNhxyLlsnvUuY", "object": "payment_intent", "amount": 100, ... "charges": {...}, "client_secret": "pi_1GkXXDLHughnNhxyLlsnvUuY_secret_oLbwpm0ME0ieJ9Aykz2SwKzj5", ... "payment_method": { "id": "pm_1GkXXuLHughnNhxy8xpAdGtf", "object": "payment_method", "billing_details": {...}, "card": {...},

Catatan

Perluasan memiliki kedalaman maksimum sebanyak empat level. Artinya, string expand tidak dapat berisi lebih dari empat properti: property1.property2.property3.property4.

Memperluas properti dalam daftar

Bila API mengembalikan daftar objek, Anda dapat menggunakan kata kunci data untuk memperluas properti tertentu pada setiap objek dalam daftar itu. Misalnya, Anda membutuhkan informasi tentang metode pembayaran yang digunakan oleh salah satu pelanggan. Untuk mendapatkan informasi ini, Anda dapat mencantumkan PaymentIntents pelanggan, yang mengembalikan objek dengan struktur berikut:

{ "object": "list", "data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ... "payment_method": "pm_1GrvBxLHughnNhxyJjtBtHcc", ... },

Catatan

Semua daftar yang dikembalikan dalam API memiliki struktur di atas, di mana properti data berisi larik objek yang dicantumkan. Anda dapat menggunakan kata kunci data di segala posisi dalam string perluas untuk memindahkan kursor perluas ke dalam daftar.

Daripada mengulang setiap maksud pembayaran dalam daftar dan mengambil metode pembayaran yang ditautkan dalam panggilan terpisah, Anda dapat memperluas semua metode pembayaran sekaligus menggunakan kata kunci data:

Command Line
cURL
curl -G https://api.stripe.com/v1/payment_intents \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d customer=
{{CUSTOMER_ID}}
\ -d "expand[]"="data.payment_method"

Daftar tersebut kemudian menyertakan objek metode pembayaran lengkap pada setiap maksud pembayaran:

{ "object": "list", "data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ... "payment_method": { "id": "pm_1GrvBxLHughnNhxyJjtBtHcc", "object": "payment_method", "billing_details": {...}, "card": { "brand": "visa", ...

Catatan

Memperluas respons berimplikasi pada kinerja. Agar permintaan tetap cepat, coba batasi banyak perluasan yang bersarang pada permintaan daftar.

Menggunakan ekspansi untuk meminta properti yang dapat disertakan

Di sebagian kasus, sumber daya memiliki properti yang tidak disertakan secara default. Salah satu contohnya adalah properti line_items di Sesi Checkout, yang hanya disertakan dalam respons jika diminta menggunakan parameter expand, misalnya:

Command Line
cURL
curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}}
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "expand[]"=line_items

Catatan

Seperti properti lain yang dapat diperluas, referensi API menandai properti yang dapat disertakan dengan label “Dapat diperluas”.

Menggunakan ekspansi dengan webhook

Anda tidak dapat menerima kejadian webhook dengan properti yang diperluas secara otomatis. Objek yang dikirim dalam kejadian selalu dalam bentuk minimalnya. Untuk mengakses nilai yang bersarang di properti yang dapat diperluas, Anda harus mengambil objek tersebut pada panggilan terpisah dalam handler webhook.

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
Produk yang Digunakan
Checkout
Payments