# Issuing ベータ版移行ガイド

Issuing ベータ版からの移行方法を紹介します。

Stripe Issuing は最近、アメリカのすべてのビジネスで一般的に利用できるようになりました。ベータ版からの移行に伴い、Stripe は新しい料金体系を適用し、API への変更をリリースしました。変更内容には、長期間を見据えた進化をサポートする新機能や機能更新が含まれます。お客様の組み込みによっては、これらの API 変更ですでにご使用の組み込みが使用できなくなる場合があるため、このガイドの各項目に特にご注意ください。

ベータ API は 2021 年 3 月 1 日に終了します。以下に、移行を支援するための API の変更点をすべてまとめました。ご質問がございましたら、[サポート](mailto:support-issuing@stripe.com)までお問い合わせください。

## 互換性

> 各セクションに記載されているように、正式に切り替えが行われるまで、新旧の双方の API をサポートすることをお勧めします。また、メインのアカウントで切り替えを行う前に、新しい Issuing アカウントを作成して、新しい API をテストすることもお勧めします。

### 属性

ベータ版のユーザは、現在すべての Issuing オブジェクトでレガシーの属性と新しい属性の両方を使用できます。名前が変更された属性は、それに対応するレガシーの属性と同じバックエンド値をポイントします。ベータ版が廃止された後は、新しい属性のみを使用できます。

準備のために、新しい API にうまく切り替えるまで、古い属性と新しい属性の両方をサポートするリードを切り替えることをおすすめします。

### パラメータ

名前が変更されたパラメータについては、レガシー名か新しい名前を使用できます。ただし、両方は使用できません。ベータ版が廃止された後は、新しいパラメータのみを使用できます。

準備のために、新しい API に切り替えるまでは、書き込みを古いパラメータと新しいパラメータの両方をサポートするように切り替えることをおすすめします。

### 列挙値

新しい列挙値への移行は、やや複雑です。新しい値の書き込みと読み取りは可能ですが、ベータ版が正式に廃止されるまでは、古い既存の値が引き続き返されます。

たとえば、Cardholder の [type](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-type) の `business_entity` は、`company` に名前が変更されました。既存の Cardholder オブジェクトでは、古い値である `business_entity` が引き続き表示されます。新しいオブジェクトは、`business_entity` でも、`company` でも作成でき、読み取りの際には、指定されたいずれかの値が返されます。

対応できるように、書き込みを新しい値 (新しいカード保有者を作成するときに、`type` を `company` に設定するなど) に切り替え、読み取りでは両方の値を処理することをお勧めします。

## API の変更

### オーソリ

- `held_amount` が `amount` に置き換えられました。`amount` は、常にカード保有者の通貨で承認または取得拒否された合計金額となります。`held_amount` とは異なり、取得時にゼロになることはありません。
  - オーソリで保留された金額は、その [balance_transactions](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-balance_transactions) 金額の合計によって取得できます。
- `held_currency` は `currency` に名前が変更されました。
- `authorized_amount` が `merchant_amount` に置き換えられました。`merchant_amount` は常に、加盟店の通貨によるキャプチャがオーソリまたは拒否された合計金額です。`authorized_amount` とは異なり、 `merchant_amount` は差戻しで減額できます。
- `authorized_currency` は `merchant_currency` に名前が変更されました。
- [オーソリの承認](https://docs.stripe.com/api/issuing/authorizations/approve.md)エンドポイントで、`held_amount` は `amount` に名前が変更されました。
- [pending_request](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-pending_request) ハッシュが追加されました。これは、リアルタイムのオーソリの[同期 Webhook](https://docs.stripe.com/issuing/controls/real-time-authorizations.md) リクエストでのみ入力されます。
  - `pending_held_amount` が `pending_request.amount` に置き換えられました。
  - `pending_authorized_amount` が `pending_request.merchant_amount` に置き換えられました。
  - `is_held_amount_controllable` が `pending_request.is_amount_controllable` に置き換えられました。
- [request_history](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history) 内のハッシュの属性の名前が変更されました。
  - `request_history.held_amount` は `request_history.amount` に名前が変更されました。
  - `request_history.held_currency` は `request_history.currency` に名前が変更されました。
  - `request_history.authorized_amount` は `request_history.merchant_amount` に名前が変更されました。
  - `request_history.authorized_currency` は `request_history.merchant_currency` に名前が変更されました。
  - `request_history.violated_authorization_controls` は削除されました。
- [request_history.reason](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history-reason) の値のいくつかが廃止されました。
  - `authentication_failed`、`incorrect_cvc`、および `incorrect_expiry` は `verification_failed` に統合されました。詳細については、[authorization.verification_data](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-verification_data) をご覧ください。
  - `account_compliance_disabled` と `account_inactive` は、`account_disabled` に置き換えられました。
  - `authorization_controls` は、`spending_controls` に名前が変更されました。これは、[Card (カード)](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-spending_controls) および [Cardholder (カード保有者)](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-spending_controls) リソースで名前が変更された属性との整合性を保持するためです。
- より詳細な説明を提供する `verification_data.three_d_secure` ハッシュが使用されるため、`verification_data.authentication` 列挙値が廃止されました。
  - `three_d_secure.result` は以前の `authentication` に代わるもので、これまでより多くの値を含みます。[新しい値](https://docs.stripe.com/issuing/3d-secure.md#prevent-fraud)の一覧については全概要をご覧ください。
  - この属性は、3D セキュア機能に登録したユーザにのみ表示されます。
- `verification_data.address_zip_check` は [verification_data.address_postal_code_check](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-verification_data-address_postal_code_check) に名前が変更されました。
- `wallet_provider`属性は `wallet` に名前が変更されました。

### 取引

- 以下の [type](https://docs.stripe.com/api/issuing/transactions/object.md#issuing_transaction_object-type) 値は、あまり使用されることがなく、他の方法で表現できるため、削除されました。
  - `cash_withdrawal` (現在は `capture`)
  - `refund_reversal` (現在はマイナスの `amount` が指定される `refund`)
  - `dispute` と `dispute_loss`。Disputes API を現在開発中です。
- 主張が認められた `Dispute` の資金移動を表す、`dispute` タイプの 2 番目の `Transaction` の作成を停止しました。その代わりに、`Dispute` に `balance_transactions` が直接追加されます。
  - これにより、`Dispute` の資金移動のための、`issuing_transaction.created` イベントが廃止されます。その代わりに、`balance_transactions` で更新された `Dispute` を送信する新しいイベントが使用されます。
- [すべての取引を一覧表示する](https://docs.stripe.com/api/issuing/transactions/list.md)エンドポイントから`dispute` クエリパラメーターが削除されました。
- [すべての取引を一覧表示する](https://docs.stripe.com/api/issuing/transactions/list.md)エンドポイントの `settlement` クエリパラメーターが、Settlement 機能ユーザーのみに制限されました。
- 取引データ機能強化ため `purchase_details` が追加されました。

### カード保有者

- `is_default` 属性が削除されました。その結果、新しいカードを作成する際に `cardholder` が必須パラメーターになります。[すべてのカード保有者を一覧表示する](https://docs.stripe.com/api/issuing/cardholders/list.md)エンドポイントは、クエリパラメーターとして `is_default` を受け付けなくなりました。
- 詳細情報が格納されるハッシュに合わせて、[type](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-type) の `business_entity` が `company` に変更されました。
- `billing.name`は、リソースの上位レベルの `name` と常に同じであるため削除されました。
- `authorization_controls` は [spending_controls](https://docs.stripe.com/api/issuing/cardholders/object.md#issuing_cardholder_object-spending_controls) に名前が変更されました。

### カード

- カードステータスの `lost` と `stolen` は削除されました。これらは、オプションの [cancellation_reason](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-cancellation_reason) が指定された [canceled](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-status) で表されます。
- `authorization_controls` は [spending_controls](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-spending_controls) に名前が変更されました。

- [replacement_reason](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-replacement_reason) 値の名前が以下のように変更されました。
  - `loss` から `lost` に変更
  - `theft` から `stolen` に変更
  - `damage` から `damaged` に変更
  - `expiration` から `expired` に変更
- `name` が削除されました。代わりに [cardholder.name](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-cardholder) を参照してください。
- `shipping.speed` 列挙値は [shipping.service](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-shipping-service) に名前が変更されました。`overnight` 値は `priority` に名前が変更されました。
- 現在のカードを交換したカードをポイントする [replaced_by](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-replaced_by) が追加されました。
- `authorization_controls` は [spending_controls](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-spending_controls) に名前が変更され、`max_approvals`、`max_amount`、`currency` は削除されました。カードの支出をより正確に管理するため、`amount` ベースの制限の使用をお勧めします。
- `merchant_data.url` は、3D セキュア機能に登録したユーザのみに使用が可能になります。
- `pin` は、PIN 管理機能に登録したユーザのみに使用が可能になります。
- [すべてのカードを一覧表示する](https://docs.stripe.com/api/issuing/cards/list.md)エンドポイントは `source` および `name` のパラメーターを受け付けなくなります。
- [カード詳細の取得](https://docs.stripe.com/api/issuing/cards/retrieve_details.md)エンドポイントは廃止されました。その代わりに、[取得](https://docs.stripe.com/api/issuing/cards/retrieve.md)エンドポイントから [number](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-number) と [cvc](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-cvc) を拡張できます。

### 不審請求の申請

- `disputed_transaction` は `transaction` に名前が変更されました。
- `balance_transactions` を追加しました。これには、`Dispute` に関連付けられたすべての [BalanceTransactions (残高取引)](https://docs.stripe.com/api/balance_transactions.md) が格納されます。
  - 各 `BalanceTransaction` には、以下のように、Issuing の `Dispute` に対応する新しい `type`、`source`、`description`、`reporting_category` が使用されます。
    - `type: "issuing_dispute"`
    - `source: "idp_1FMjf1GprvsjVv9gffmDmLGx"`
    - `description: "Issuing dispute"`
    - `reporting_category: "Issuing Dispute"`
- `Dispute` で主張が認められると、更新後の `Dispute` と新しい `BalanceTransaction` が指定された新しいイベント `issuing_dispute.funds_reinstated` が送信されます。

### イベント

- 以下のイベントは、Settlement 機能に登録しているユーザのみに制限されます。
  - `issuing_settlement.created`
  - `issuing_settlement.updated`

### 残高

- `issuing.pending` 残高が [Balance](https://docs.stripe.com/api/balance/balance_object.md#balance_object) オブジェクトから削除されました。代わりに [issuing.available](https://docs.stripe.com/api/balance/balance_object.md#balance_object-issuing-available) 残高を参照してください。