Kasus penggunaan untuk memperluas tanggapan

Gunakan parameter expand dalam permintaan API Anda untuk mengambil detail yang tidak dikembalikan oleh API dalam respons default. Kasus penggunaan berikut mengilustrasikan hal ini untuk informasi yang umum.

Lihat biaya Stripe untuk pembayaran tertentu

Anda dapat memeriksa biaya pemrosesan pembayaran setelah pembayaran diproses dan Stripe membuat transaksi saldo. Kejadian charge.updated mereferensikan properti balance_transaction (misalnya, txn_123), yang mengindikasikan bahwa properti siap digunakan.

Sebagai ganti mencari transaksi saldo secara terpisah, Anda dapat mengambilnya dalam satu panggilan menggunakan expand.

curl https://api.stripe.com/v1/payment_intents/pi_1Gpl8kLHughnNhxyIb1RvRTu \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "expand[]"="latest_charge.balance_transaction" \
  -G

Pengguna pada versi API 2022-08-01 atau lebih lama:

curl https://api.stripe.com/v1/payment_intents/pi_1Gpl8kLHughnNhxyIb1RvRTu \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "expand[]"="charges.data.balance_transaction" \
  -G

When using automatic_async (the default capture_method since version 2024-04-10), balance transactions are created after the payment succeeds, but asynchronously in the background. This means:

• Kolom balance_transaction pada objek Charge mungkin bernilai null segera setelah konfirmasi.
• Jika Anda memperluas balance_transaction atau latest_charge.balance_transaction, data tersebut mungkin belum tersedia dalam respons.
• Anda dapat mendengarkan peristiwa charge.updated untuk mengetahui kapan transaksi saldo tersedia

Perilaku asinkron ini meningkatkan performa pembayaran, namun mengharuskan integrasi Anda untuk menangani kemungkinan bahwa transaksi saldo mungkin belum tersedia secara langsung.

Lihat charge yang disertakan dalam payout

Setiap payout otomatis dikaitkan dengan perubahan historis pada saldo akun Stripe Anda. API mencatat perubahan historis ini sebagai transaksi saldo, yang dapat Anda ambil menggunakan Daftar Transaksi Saldo. Dari daftar transaksi saldo, Anda dapat memperluas properti sumber untuk mengumpulkan informasi tentang hal yang memicu perubahan pada saldo akun (Charge, Pengembalian dana, Transfer, dan lain-lain). Misalnya:

curl https://api.stripe.com/v1/balance_transactions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d payout=po_1Gl3ZLLHughnNhxyDrOia0vI \
  -d type=charge \
  -d "expand[]"="data.source" \
  -G

Pelajari selengkapnya rekonsiliasi payout.

Jika menggunakan Connect dengan Destination Charges, Anda dapat mengambil informasi yang sama atas nama akun terhubung. Perbedaannya adalah Destination Charges melibatkan transfer maupun pembayaran yang dikaitkan (dalam bentuk objek Charge) untuk memindahkan dana ke akun terhubung. Jadi, ketika mencantumkan transaksi saldo yang digabungkan dalam payout akun terhubung Anda, setiap sumber transaksi saldo ditautkan pada pembayaran transfer, bukan Charge asal. Untuk mengambil Charge asal, Anda perlu memperluas transfer tertaut pembayaran melalui properti source_transfer; dan dari sana, perluas properti source_transaction transfer:

curl https://api.stripe.com/v1/balance_transactions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d payout=po_1G7bnaD2wdkPsFGzdVOqU44u \
  -d type=payment \
  -d "expand[]"="data.source.source_transfer.source_transaction" \
  -H "Stripe-Account: acct_1G7PaoD2wdkPsFGz" \
  -G