# 最新の柔軟な支払いシナリオに対応する

ベータ版の高度な決済シナリオを一般リリース版に適応させます。

Stripe では、カード非提示取引に対していくつかの柔軟な決済シナリオをサポートするようになりました。すでにこれらの機能のプライベートベータ版を実装している場合は、このガイドで一般リリース版への詳しいアップグレード方法をご確認ください。新しく実装する場合は、以下のガイドでご興味のある機能をご確認ください。

- [オーソリを増額する](https://docs.stripe.com/payments/incremental-authorization.md)
- [オーソリ額を超える金額をキャプチャーする](https://docs.stripe.com/payments/overcapture.md)
- [オンラインカード決済に対する保留を延長する](https://docs.stripe.com/payments/extended-authorization.md)
- [支払いを複数回キャプチャーする](https://docs.stripe.com/payments/multicapture.md)

Stripe では、これらの機能に対してフィードバックに基づいた以下の改善を行いました。

- *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process) レベルでの機能の詳細なコントロール。
- *確定* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment)フェーズ後の機能の利用可能状況と使用量に関する明確な予測。

柔軟な決済の各機能には、プライベートベータ実装とは異なる要件があります。 アップグレードが必要な機能を選択し、上部の注釈でその機能に固有の変更点と要件を参照してください。

# 増分オーソリ

> This is a 増分オーソリ for when flex-payment-features is incremental-auth. View the full page at https://docs.stripe.com/payments/flexible-features-migration?flex-payment-features=incremental-auth.

> #### ベータからの変更点
> 
> この実装の最初のステップは必須になりました。

## 増分オーソリをリクエストする

確定前に *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process) に増分オーソリのリクエストを含める必要があります。

> このステップは以前はオプションでしたが、現在は必須になりました。

### Before

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d payment_method=pm_card_debit_incrementalAuthAuthorized \
  -d confirm=true \
  -d capture_method=manual \
  -d "expand[]=latest_charge" \
  -d "payment_method_options[card][request_incremental_authorization_support]=true"
```

### After

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d payment_method=pm_card_debit_incrementalAuthAuthorized \
  -d confirm=true \
  -d capture_method=manual \
  -d "expand[]=latest_charge" \
  -d "payment_method_options[card][request_incremental_authorization]=if_available"
```

レスポンスでは、[latest_charge](https://docs.stripe.com/api/charges/object.md) の `payment_method_details.card.incremental_authorization.status` プロパティに増分オーソリリクエストのステータスが返されるようになりました。ステータスの値は、顧客の支払い方法に応じて `available` または `unavailable` になります。

### Before

```json
// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 1000,
  "amount_received": 0,
  ...
  // if latest_charge is expanded
  {
    "latest_charge": {
        "amount": 1000,
        "payment_method_details": {
          "card": {"incremental_authorization_supported": true // or false
          }
        }
        ...
      }
  }
}
```

### After

```json
// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 1000,
  "amount_received": 0,
  ...
  // if latest_charge is expanded
  {
    "latest_charge": {
        "amount": 1000,
        "payment_method_details": {
          "card": {
            "incremental_authorization": {"status": "available" // or "unavailable"
            }
          }
        }
        ...
      }
  }
}
```

## オーソリ額を段階的に変更する

**このステップにはベータ版からの変更はありません。**

```curl
curl https://api.stripe.com/v1/payment_intents/pi_ANipwO3zNfjeWODtRPIg/increment_authorization \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1500
```


# オーバーキャプチャー

> This is a オーバーキャプチャー for when flex-payment-features is overcapture. View the full page at https://docs.stripe.com/payments/flexible-features-migration?flex-payment-features=overcapture.

> #### ベータからの変更点
> 
> この実装の最初のステップは以前はありませんでしたが、現在は必須になりました。

## オーバーキャプチャーをリクエストする

確定前に *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process) にオーバーキャプチャーのリクエストを含める必要があります。プライベートベータ実装のオーバーキャプチャーでは、リクエストパラメーターが存在しなかったため、このステップはありませんでした。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d capture_method=manual \
  -d "expand[]=latest_charge" \
  -d "payment_method_options[card][request_overcapture]=if_available"
```

レスポンスでは、[latest_charge](https://docs.stripe.com/api/charges/object.md) の `payment_method_details.card.overcapture.status` プロパティにオーバーキャプチャーリクエストのステータスが返されます。ステータスの値は、顧客の支払い方法に応じて `available` または `unavailable` になります。

```json
// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 1000,
  "amount_received": 0,
  ...
  // if latest_charge is expanded
  {
    "latest_charge": {
        "amount": 1000,
        "payment_method_details": {
          "card": {
            "overcapture": {"status": "available", // or "unavailable"
                "maximum_capturable_amount": 1200
            }
          }
        }
        ...
      }
  }
}
```

## オーソリ額を超える金額をキャプチャーする

*PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process) での現在のオーソリ額を超える金額をキャプチャーするには、[キャプチャー](https://docs.stripe.com/api/payment_intents/capture.md)エンドポイントを使用して、[maximum_amount_capturable](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details-card-overcapture) の最大額までで [amount_to_capture](https://docs.stripe.com/api/payment_intents/capture.md#capture_payment_intent-amount_to_capture) を指定します。

```curl
curl https://api.stripe.com/v1/payment_intents/pi_ANipwO3zNfjeWODtRPIg/capture \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount_to_capture=1200
```


# オーソリの延長

> This is a オーソリの延長 for when flex-payment-features is extended-auth. View the full page at https://docs.stripe.com/payments/flexible-features-migration?flex-payment-features=extended-auth.

> #### ベータからの変更点
> 
> この実装の最初のステップは以前はありませんでしたが、現在は必須になりました。

## オーソリの延長をリクエストする

確定前に *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process) にオーソリの延長のリクエストを含める必要があります。プライベートベータ実装のオーソリの延長では、リクエストパラメーターが存在しなかったため、このステップはありませんでした。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d capture_method=manual \
  -d "expand[]=latest_charge" \
  -d "payment_method_options[card][request_extended_authorization]=if_available"
```

レスポンスでは、[latest_charge](https://docs.stripe.com/api/charges/object.md) の `payment_method_details.card.extended_authorization.status` プロパティにオーソリの延長リクエストのステータスが返されます。ステータスの値は、顧客の支払い方法に応じて `available` または `unavailable` になります。

```json
// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 1000,
  "amount_received": 0,
  ...
  // if latest_charge is expanded
  {
    "latest_charge": {
        "amount": 1000,
        "payment_method_details": {
          "card": {// The field is now always available, even when not using extended authorization
            "capture_before": 1679090539,
            // The response contains information on whether the capture window was extended.
            "extended_authorization": {"status": "enabled", // or "disabled"
            }
          }
        }
        ...
      }
  }
}
```

## オーソリをキャプチャーする

**このステップはベータ版からの変更はありません。**

[`capture_before` フィールド](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details-card-capture_before)に指定された日付より前にデータをキャプチャーします。

```curl
curl https://api.stripe.com/v1/payment_intents/pi_ANipwO3zNfjeWODtRPIg/capture \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount_to_capture=1000
```


# Multicapture

> This is a Multicapture for when flex-payment-features is multicapture. View the full page at https://docs.stripe.com/payments/flexible-features-migration?flex-payment-features=multicapture.

> #### ベータからの変更点
> 
> ベータから一般提供版への移行には、以下の 4 つのステップすべてに影響を及ぼす変更が必要になります。

## Multicapture をリクエストする

確定前に *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process) に Multicapture のリクエストを含める必要があります。プライベートベータ実装の Multicapture では、リクエストパラメーターが存在しなかったため、このステップはありませんでした。

一般提供版の機能へのアクセスをリクエストするには、*PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process) を確定する前に [Stripe-Version](https://docs.stripe.com/sdks/set-version.md) ヘッダーで `multicapture_migrate_to_ga_from_beta` 値を渡します。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-04-22.preview; multicapture_migrate_to_ga_from_beta" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d capture_method=manual \
  -d "expand[]=latest_charge" \
  -d "payment_method_options[card][request_multicapture]=if_available"
```

レスポンスでは、[latest_charge](https://docs.stripe.com/api/charges/object.md) の `payment_method_details.card.multicapture.status` プロパティに Multicapture リクエストのステータスが返されます。ステータスの値は、顧客の支払い方法に応じて `available` または `unavailable` になります。

```json
// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent","amount": 1000,
  "amount_capturable": 1000,
  "amount_received": 0,
  ...
  // if latest_charge is expanded
  "latest_charge": {"amount": 1000,
      "amount_captured": 0,
      "amount_refunded": 0,
      "payment_method_details": {
        "card": {
          "multicapture": {"status": "available" // or "unavailable"
          }
        }
      }
      ...
    }
  ...
}
```

## オーソリ額を部分的に複数回キャプチャーする

ベータ版と同じように、オプションの `final_capture` パラメーターを使用して、 [requires_capture 状態](https://docs.stripe.com/payments/paymentintents/lifecycle.md)のままである限り *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process) を複数回キャプチャーできます。

```curl
curl https://api.stripe.com/v1/payment_intents/pi_ANipwO3zNfjeWODtRPIg/capture \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-04-22.preview; multicapture_migrate_to_ga_from_beta" \
  -d amount_to_capture=700 \
  -d final_capture=false \
  -d "expand[]=latest_charge"
```

```json
// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent","amount": 1000,
  "amount_capturable": 300, // 1000 - 700 = 300
  "amount_received": 700,
  "status": "requires_capture",
  // if latest_charge is expanded
  "latest_charge": {"amount": 1000,
      "amount_captured": 700,
      "amount_refunded": 0,
      ...
    }
  ...
}
```

> 一般提供版では、`final_capture` パラメーターを `false` に設定して残額をすべてキャプチャーしようとすると、400 エラーが返されます。

### Before

```curl
curl https://api.stripe.com/v1/payment_intents/pi_ANipwO3zNfjeWODtRPIg/capture \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount_to_capture=300 \
  -d final_capture=false \
  -d "expand[]=latest_charge"
```

```json
// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent","amount": 1000,
  "amount_capturable": 0, // 1000 - 700 - 300 = 0
  "amount_received": 1000,
  "status": "succeeded",
  // if latest_charge is expanded
  "latest_charge": {"amount": 1000,
      "amount_captured": 1000,
      "amount_refunded": 0,
      ...
    }
  ...
}
```

### After

```curl
curl https://api.stripe.com/v1/payment_intents/pi_ANipwO3zNfjeWODtRPIg/capture \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount_to_capture=300 \
  -d final_capture=false \
  -d "expand[]=latest_charge"
```

```json
// HTTP 400
{
  "message": "can't set final_capture as false when fully capturing a payment intent.",
  "type": "invalid_request_error"
}
```

## Webhook

Multicapture のイベント生成はベータ版とは異なりますが、イベントの内容は変わりません。

| 動作           | 移行前                                                                                                     | 移行後                                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| 最終以外のキャプチャー時 | Stripe は [charge.captured](https://docs.stripe.com/api/events/types.md#event_types-charge.captured) を送信 | Stripe は [charge.updated](https://docs.stripe.com/api/events/types.md#event_types-charge.updated) を送信   |
| 最終キャプチャー時    | Stripe は [charge.captured](https://docs.stripe.com/api/events/types.md#event_types-charge.captured) を送信 | Stripe は [charge.captured](https://docs.stripe.com/api/events/types.md#event_types-charge.captured) を送信 |

## 返金

一般提供版では、ユーザーが `final_capture=true` で渡す *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process) の未キャプチャーの売上を表す [Refund (返金)](https://docs.stripe.com/api/refunds/object.md)は作成されません。


## 最初のオーソリ額を超える金額をキャプチャーする方法を選択する

次の 2 つの柔軟な決済で、最初のオーソリ額を超える金額をキャプチャーすることができます。

- 一定の限度額までオーバーキャプチャーする ([支払いでオーソリ額を超える金額をキャプチャーする](https://docs.stripe.com/payments/overcapture.md))
- 既存のオーソリを増額し、その後新しいオーソリ額をキャプチャーする ([オーソリを増額する](https://docs.stripe.com/payments/incremental-authorization.md))

以下の例では、これらの機能が一般提供版でどのように補完し合うかを示しています。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d payment_method=pm_card_visa \
  -d confirm=true \
  -d capture_method=manual \
  -d "expand[]=latest_charge" \
  -d "payment_method_options[card][request_incremental_authorization]=if_available" \
  -d "payment_method_options[card][request_overcapture]=if_available"
```

```json
// PaymentIntent Response
{
  "object": "payment_intent",
  "amount": 1000,
  ...
  // if latest_charge is expanded
  {
    "latest_charge": {
      "payment_method_details": {
        "card": {
          "incremental_authorization": {"status": "available" // or "unavailable"
          },
          "overcapture": {"status": "available", // or "unavailable"
              "maximum_capturable_amount": 1200
          }
        }
      }
      ...
    }
  }
}
```

PaymentIntent の*確定* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment)時に両方の機能を利用できる場合、次のステップで最初にオーソリ額を超える金額をキャプチャーするには、次のオプションがあります。

1. 希望金額が `maximum_capturable_amount` 以下の場合はオーバーキャプチャーします。
1. 希望金額に対する増分オーソリを実行し、その後キャプチャーします。