# Payment Intents API と Payment Methods API への移行

Sources API および Tokens API から Payment Methods API に移行する方法をご紹介します。

支払い情報の収集と保管の導入に推奨される方法は、既存の [Tokens](https://docs.stripe.com/api/tokens.md) API と [Sources](https://docs.stripe.com/api/sources.md) API を使用する方法から、[Payment Methods API](https://docs.stripe.com/api/payment_methods.md) を使用する方法に変わりました。この API は [Payment Intents API](https://docs.stripe.com/payments/payment-intents.md) と連携して、多種多様な支払い方法による支払いを作成できます。

カード決済での Sources API のサポートを終了する予定です。現在、Sources API を使用してカード決済を処理している場合は、Payment Intents API に移行する必要があります。Sources API のサポート終了に関する詳細はメールでお知らせします。

## Payment Intents API に移行する

実装を移行するには、[Payment Intents API](https://docs.stripe.com/api/payment_intents.md) を使用するようにサーバーとフロントエンドを更新します。以下は一般的な実装オプションの例です。

- 決済フローの [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) にリダイレクトする。
- 自社の決済ページで Stripe の [Payment Element](https://docs.stripe.com/payments/payment-element.md) を使用する。
- カスタムフォームを作成し、Stripe JS SDK を使用して決済を完了します。

Checkout または Payment Element を使用すると、コードを変更せずに Stripe ダッシュボードからほとんどの決済手段を追加したり、管理したりできます。

Payment Methods API を使用したカード決済手段の実装について、詳しくは[決済手段のドキュメント](https://docs.stripe.com/payments/payment-methods/overview.md)で該当する決済手段の手順を参照してください。以下の表は各決済タイプの違いを大まかに比較したものです。

| 以前の実装 | Stripe Checkout | Payment Element | カスタムフォーム |
| --- | --- | --- | --- |
|  | 複雑度: 低 | 複雑度: 中 | 複雑度: 高 |
| フロントエンドまたはサーバーで Source を作成します。 | サーバーで `CheckoutSession` を作成します。 | サーバーで `PaymentIntent` を作成します。 | サーバーで `PaymentIntent` を作成します。 |
| ウィジェットを読み込むか、サードパーティーにリダイレクトして支払いを承認します。 | 不要 | フロントエンドに client secret を渡し、Stripe JS SDK を使用して Payment Element をレンダリングして、決済を完了します。 | client secret をフロントエンドに渡し、自社のフォームを使用して顧客から詳細情報を収集し、決済手段に応じて決済を完了します。 |
| Source が決済可能な状態であることを確認し、Source に対して決済を実行します。 | 不要 | 不要 | 不要 |
| `charge.succeeded` Webhook を使用して、Charge が成功したことを非同期で確認します。 | `payment_intent.succeeded` Webhook を使用して、Checkout Session が成功したことを確認します。 | `payment_intent.succeeded` Webhook を使用して、PaymentIntent が成功したことを確認します。 | `payment_intent.succeeded` Webhook を使用して、PaymentIntent が成功したことを確認します。 |

> #### Charge オブジェクトを引き続き使用する
> 
> `PaymentIntent` オブジェクトは、新しい実装での決済を表し、フロントエンドで決済を確定すると `Charge` を作成します。これまで `Charge` への参照を保存していた場合は、顧客が決済を完了した後に `PaymentIntent` から `Charge` ID を取得することで、引き続き保存できます。ただし、`PaymentIntent` ID も保存することをお勧めします。

### 支払いステータスの確認

以前は、API コールのたびに `Source` と `Charge` の両方のステータスを確認する必要がありました。今後は 2 つのオブジェクトを確認する必要はなく、フロントエンドで確定した後に `PaymentIntent` または `CheckoutSession` のステータスを確認するだけです。

| payment_intent.status | 意味 |
| --- | --- |
| `succeeded` | 支払いが成功しました。 |
| `requires_payment_method` | 支払いが失敗しました。 |
| `requires_action` | おそらく [3DS が必要なため](https://docs.stripe.com/payments/3d-secure/authentication-flow.md#check-status)、顧客は決済の承認を完了していません。 |

サーバーで取得するか、サーバーで Webhook イベントをリッスンして、常に `PaymentIntent` のステータスを確認します。`PaymentIntent` を確定する際に提供される `return_url` にユーザーが戻ることだけに依存しないでください。

### 返金

`Charge` ID の代わりに `PaymentIntent` ID を使用して、Refunds API をコールできます。

あるいは、`PaymentIntent` によって作成される `Charge` の ID を使用して Refunds API を引き続きコールすることもできます。`Charge` の ID は [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) プロパティから取得できます。

### エラー処理

以前は、`Source` でエラーを処理する必要がありました。`PaymentIntents` では、作成時および顧客が決済の承認を完了した後に `PaymentIntent` でエラーを確認します。`PaymentIntent` のエラーのほとんどは `invalid_request_error` タイプで、無効なリクエストの場合に返されます。

実装を移行する際は、`PaymentIntent` のエラーコードが `Sources` の対応するエラーコードと異なる場合があることに注意してください。

### Webhook

以前に `Source` イベントをリッスンしていた場合は、代わりに他のオブジェクトのイベントをリッスンするよう実装を更新する必要が生じる場合があります。以下の表に例を示します。

| 古いイベント | 新しい Checkout イベント | 新しい PaymentIntent イベント | 特記事項 |
| --- | --- | --- | --- |
| `source.chargeable` | 該当しない | 該当しない |  |
| `source.failed` | 該当しない | 該当しない |  |
| `source.canceled` | 該当しない | 該当しない |  |
| `charge.succeeded` | `checkout.session.completed` | `payment_intent.succeeded` | `charge.succeeded` イベントも送信されるため、他のイベントの代わりに引き続きリッスンできます。 |
| `charge.failed` | 適用されません。 顧客は[有効期限が切れる](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-expires_at)まで同じ Checkout セッションで支払いを再試行でき、有効期限が切れた時点で `checkout.session.expired` イベントが届きます。 | `payment_intent.payment_failed` | `charge.failed` イベントも送信されるため、他のイベントの代わりに引き続きリッスンできます。 |
| `charge.dispute.created` | `charge.dispute.created` | `charge.dispute.created` |  |

## Payment Methods API に移行する

Payment Methods API と Sources API の主な違いは、Sources では [status](https://docs.stripe.com/api/sources/object.md#source_object-status) プロパティで取引の状態を表すことです。つまり、各 `Source` オブジェクトは、決済に使用する前に決済可能な状態に移行する必要があります。これに対し、`PaymentMethod` は状態を保持せず、決済の状態は PaymentIntent オブジェクトで表されます。

> 以下の表には、すべての支払い方法が掲載されているわけではありません。Sources API を使用してこの他の支払い方法を導入している場合は、それらも同様に Payment Methods API に移行してください。

| フロー | Payment Methods API と Payment Intents API | Charges API を使用する Tokens と Sources |
| --- | --- | --- |
| カード | [カード支払い](https://docs.stripe.com/payments/cards.md) | 非推奨 |
| ACH ダイレクトデビット | [アメリカの銀行の (ACH) ダイレクトデビット](https://docs.stripe.com/payments/ach-direct-debit.md) | [Tokens では対応](https://docs.stripe.com/ach-deprecated.md)、Sources では非対応 |

実装する API を選択した後で、[支払い方法ガイド](https://stripe.com/payments/payment-methods-guide)を参照すると、サポートが必要な適切な支払い方法タイプを判断しやすくなります。

このガイドには各支払い方法の詳細が記載され、顧客対応フローの違いと、その支払い方法に最も適した[地域](https://stripe.com/payments/payment-methods-guide#payment-methods-fact-sheets)について説明されています。利用可能な支払い方法は、[ダッシュボード](https://dashboard.stripe.com/account/payments/settings)で有効にできます。通常は即時に有効化され、追加の契約は必要ありません。

## 保存済み Sources を PaymentMethods に移行する

`Sources` または [Charges API で作成されたカード](https://docs.stripe.com/payments/charges-api.md)に保存されている既存顧客の認証情報を引き続き使用するには、[Stripe ダッシュボードのデータ移行ツール](https://dashboard.stripe.com/workbench/health/migrations)を使用して `PaymentMethods` に変換する必要があります。

移行された `PaymentMethod` を Payment Intents API で使用するには、`PaymentIntent` の作成時に `PaymentMethod` ID と `Customer` ID を渡します。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "automatic_payment_methods[enabled]=true" \
  -d amount=1099 \
  -d currency=usd \
  -d "customer={{CUSTOMER_ID}}" \
  -d "payment_method={{PAYMENTMETHOD_ID}}"
```

## See also

- [支払い方法ガイド](https://stripe.com/payments/payment-methods-guide)
- [Connect での支払い](https://docs.stripe.com/connect/charges.md)
- [Payment Methods API リファレンス](https://docs.stripe.com/api/payment_methods.md)