# レスポンス拡張のユースケース

API レスポンスを拡張して一般的な決済の詳細を返すようにします。

API リクエストの `expand` パラメーターを使用して、API がデフォルトのレスポンスで返さない詳細を取得します。次のユースケースは、一般的にリクエストされる情報について示しています。

## 特定の支払いに対する Stripe 手数料を確認する

決済が処理され、Stripe が [Balance Transaction (取引残高)](https://docs.stripe.com/api/balance_transactions/object.md#balance_transaction_object-fee_details) を作成した後で、決済の処理手数料を確認できます。[charge.updated](https://docs.stripe.com/api/events/types.md#event_types-charge.updated) イベントは、`balance_transaction` プロパティ (`txn_123` など) を参照し、使用する準備ができたことを示します。

取引残高を個別に検索する代わりに、`expand` を使用して 1 回のコールで取得できます。

> *IC+ ユーザー* (A pricing plan where businesses pay the variable network cost for each transaction plus the Stripe fee rather than a flat rate for all transactions. This pricing model provides more visibility into payments costs)は、取引残高から支払い手数料の情報を取得できません。代わりに、決済手数料レポートを使用してください。

#### curl

```bash
curl https://api.stripe.com/v1/payment_intents/pi_1Gpl8kLHughnNhxyIb1RvRTu \
  -u <<YOUR_SECRET_KEY>>: \-d "expand[]"="latest_charge.balance_transaction" \
  -G
```

API バージョン [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) 以前のユーザー:

#### curl

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

> Stripe 手数料が利用可能になるには、PaymentIntent が [キャプチャー](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md#capture-funds) され、[ステータス](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) が `succeeded` である必要があります。

`automatic_async` (バージョン `2024-04-10` 以降のデフォルトの `capture_method`) を使用する場合、取引残高は決済成功後にバックグラウンドで非同期的に作成されます。これは次のことを意味します。

- Charge オブジェクトの `balance_transaction` フィールドが確認直後に `null` になる場合があります
- `balance_transaction` または `latest_charge.balance_transaction` を展開すると、レスポンスで利用できなくなる場合があります
- `charge.updated` イベントを監視することで、取引残高が利用可能になったタイミングを知ることができます

の非同期処理により決済パフォーマンスが向上しますが、取引残高がすぐに利用できない場合があるため、システム導入時にはこの点を考慮する必要があります。

## 入金に含まれる支払いを確認する

各自動*入金* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit)は、Stripe アカウントの残高の履歴変更に結びついています。この API はこれらの履歴変更を [Balance Transaction (取引残高)](https://docs.stripe.com/api/balance_transactions/object.md) として記録します。これは、[List Balance Transactions API](https://docs.stripe.com/api/balance_transactions/list.md) を使用して取得できます。取引残高のリストから、[source](https://docs.stripe.com/api/balance_transactions/object.md#balance_transaction_object-source) プロパティを展開し、何 (支払い、返金、送金など) がアカウント残高の変化を引き起こしたのか、情報を集めることができます。以下に例を挙げます。

#### curl

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

> 「自動」入金に関してのみ、取引残高履歴を取得できます。手動の入金が有効になっている場合には、ご自身で残高履歴を追跡する必要があります。

[入金の照合](https://docs.stripe.com/payouts/reconciliation.md)で詳細をご覧ください。

デスティネーション支払いで *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) を使用している場合、連結アカウントの代わりに同じ情報を取得することができます。唯一の違いは、デスティネーション支払いでは、売上を連結アカウントに移動するために、送金および関連付けられた支払い (Charge オブジェクトの形式で) の両方が関与します。このため、連結アカウントの入金にバンドルされた取引残高をリストアップする際、各取引のソースは元の Charge ではなく、送金の支払いに関連付けられます。元の Charge を取得するには、[source_transfer](https://docs.stripe.com/api/charges/object.md#charge_object-source_transfer) プロパティを使用して、支払いに関連付けられた送金を拡張する必要があります。そこから、送金の [source_transaction](https://docs.stripe.com/api/transfers/object.md#transfer_object-source_transaction) プロパティを拡張します。

#### curl

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