Memperluas respons

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:

curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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"
    },
    ...
  }
}

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:

curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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:

curl -G https://api.stripe.com/v1/checkout/sessions/
{{SESSION_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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": {...},

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",
      ...
    },

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:

curl -G https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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",
          ...

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:

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

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.