# 非同期キャプチャー

非同期キャプチャーを使用して PaymentIntent 確定の高速化を有効にします。

非同期キャプチャーを利用すると、売上確定処理がバックグラウンドで実行されるため、PaymentIntent の確定に待たされる時間が短縮されます。確定リクエストが送信されると、実装で成功レスポンスが受信され、Stripe がバックエンドで支払いの確定を完了します。

これにより次のような影響があります。

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

実装では、取引残高がすぐに利用可能にならない可能性に対処する必要があります。

## 非同期キャプチャーを選択する

既存の実装をアップグレードして非同期キャプチャーのサポートを追加するには、PaymentIntent を作成する際に、`automatic_async` をキャプチャー方法として使用します。

最新バージョンの API ではデフォルトでこの機能が有効になっているため、`capture_method=automatic_async` パラメーターの指定は任意になります。

#### curl

```bash
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -d amount=2000 \
  -d currency=usd \
  -d payment_method=pm_card_visa \
  --data-urlencode "return_url=https://example.com/return" \
  -d capture_method=automatic_async \
  -d confirm=true
```

非同期キャプチャーを選択すると、API レスポンスと一部の Webhook は他のキャプチャー方法とは動作が異なるため、追加の変更が必要になる場合があります。

すべての支払いで、以下のオブジェクトの [balance_transaction](https://docs.stripe.com/api/balance_transactions.md) は `null` です。Connect の支払いの場合は、以下のオブジェクトの [transfer](https://docs.stripe.com/api/charges/object.md#charge_object-transfer) と [application_fee](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-application_fee_amount) も `null` です。

- API レスポンスの関連付けられた [Charge](https://docs.stripe.com/api/charges/object.md) オブジェクト
- [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) Webhook
- [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) Webhook

[charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) Webhook の変更された Charge オブジェクト:

```json
# Charge Object
{
    "id": "ch_123",
    "object": "charge",
    "amount_captured": 1000, # the capture has happened
    "application_fee_amount": 100,
    "captured": true,
    "balance_transaction": null,  # object might not be created yet, might be shown as nil.
    "transfer": null,             # object might not be created yet, might be shown as nil.
    "application_fee": null,      # object might not be created yet, might be shown as nil.
    ...
}
```

変更された API レスポインスと [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) Webhook: ([API バージョン](https://docs.stripe.com/upgrades.md)によって異なります)

#### API バージョン 2022-11-15 以降

```json
# PaymentIntent Object
{
  "id": "pi_123",
  "object": "payment_intent",
  "capture_method": "automatic_async",
  "status": "succeeded",
  "latest_charge": "ch_**" # if expanded, this is the Modified Charge object above
}
```

## Webhook をリッスンして、追加データが利用可能になったときに通知を受け取ります

> charge.updated Webhook の SLA は、PaymentIntent が正常に確定されてから 1 時間後です。

非同期キャプチャーを使用する場合は、Webhook をリッスンして、最初は `null` であったオブジェクトのステータスを確認できます。

- [balance_transaction](https://docs.stripe.com/api/balance_transactions.md) を取得するには、[charge.updated](https://docs.stripe.com/api/events/types.md#event_types-charge.updated) Webhook イベントをサブスクライブします。
- [application_fee](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-application_fee_amount) を取得するには、[application_fee.created](https://docs.stripe.com/api/events/types.md#event_types-application_fee.created) Webhook イベントに登録します。
- [transfer](https://docs.stripe.com/api/charges/object.md#charge_object-transfer) を取得するには、[transfer.created](https://docs.stripe.com/api/events/types.md#event_types-transfer.created) Webhook イベントに登録します。

非同期キャプチャーの Webhook

```json

# charge.updated events
{
  "data": {
    "id": "ch_123",
    "object": "charge",
    "amount": 100,
    "balance_transaction": "txn_123", # applicable to all charges.
    "transfer": "tr_123",         # applicable to destination charge only.
    "application_fee": "fee_123", # applicable to destination charge only.
    ...
  },
  previous_attributes: {
   "balance_transaction": null, # applicable to all charges.
   "transfer": null,          # applicable to destination charge only.
   "application_fee": null,   # applicable to destination charge only.
  }
}
```

```json

# transfer.created events
{
  "data": {
    "id": "tr_123",
    "object": "transfer",
    "amount": 1000,
    ...
  }
}
```

```json

# application_fee.created events
{
  "data": {
    "id": "fee_123",
    "object": "application_fee",
    "amount": 100,
    ...
  }
}
```