扩展响应用例

展开 API 响应以返回常见的支付详情。

在您的 API 请求中使用 expand 参数，以检索 API 在其默认响应中未返回的详细信息。以下用例针对常见的请求信息对此进行了说明。

查看特定付款的 Stripe 费用

您可以在支付处理完成后查看支付费用，Stripe 会创建余额交易。charge.updated 事件引用 balance_transaction 属性（例如 txn_123），表示它准备就绪，可供使用。

您可以使用 expand 在一个单独的调用中检索余额交易，而不必单独检索余额交易。

注意

IC+ 用户无法从余额交易中检索支付费用信息。请改用支付费用报告。

API 版本 2022-08-01 或更早版本的用户：

注意

为确保 Stripe 已收取费用，PaymentIntent 必须被捕获，且其状态为 succeeded。

使用 automatic_async（自 2024-04-10 版本后默认 capture_method）时，支付成功后会创建余额交易，但在后台异步进行。这意味着：

确认支付后，Charge 对象中的 balance_transaction 字段可能会立即为 null
如果您展开 balance_transaction 或 latest_charge.balance_transaction，其可能无法在响应中使用
您可以监听 charge.updated 事件，了解何时可使用余额交易

这种异步行为提高了支付效率，但需要确保您的集成能处理余额交易有时无法立即可用的情况。

查看提现中包含的收款

每笔自动提现都会与您的 Stripe 账户余额的历史变化有关。API 以余额交易来记录这些历史变化，可通过余额交易列表来检索。您可以从余额交易列表中扩展 source 属性来收集触发账户余额变化的因素（收款、退款、转账，等）的信息。例如：

注意

只能检索_自动_提现所涉及的余额交易记录。如果启用了手动提现，则必须自己跟踪交易记录。

了解有关提现对账的更多信息。。

如果您用 Connect 进行定向收款，则可以代您的 Connect 子账户检索同一信息。不同之处在于，向 Connect 子账户转移资金时，定向收款涉及转账和关联的付款（以 Charge 对象的形式）。因此，在列示特定于您的 Connect 子账户的提现的余额交易时，每笔余额交易的来源都会关联到转账的 Payment，而非原始 Charge。检索原始 Charge 时，需要通过 source_transfer 属性扩展付款关联的转账；从这里，扩展转账的 source_transaction 属性。