Issuing ベータ版移行ガイド

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

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

ベータ版の API は 2021 年 3 月 1 日をもって廃止されます。お客様の移行をサポートするため、API に対するすべての変更を以下にまとめました。ご不明な点はサポートまでお問い合わせください。

互換性

注意

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

属性

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

移行に備えて、新しい API への切り替えが正常に完了するまで、新旧双方の属性に対応できるように、読み取りを切り替えることをお勧めします。

パラメータ

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

移行に備えて、新しい API への切り替えが正常に完了するまで、新旧双方のパラメーターに対応できるように、書き込みを切り替えることをお勧めします。

列挙値

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

たとえば、Cardholder の type の business_entity は、company に名前が変更されました。既存の Cardholder オブジェクトでは、古い値である business_entity が引き続き表示されます。新しいオブジェクトは、business_entity でも、company でも作成でき、読み取りの際には、指定されたいずれかの値が返されます。

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

API の変更

オーソリ

held_amount は amount に置き換えられました。amount は常に、カード保有者の通貨によるキャプチャがオーソリまたは拒否された合計金額です。held_amount とは異なり、キャプチャ時にゼロにされることはありません。
- オーソリで保留された金額は、その balance_transactions 金額の合計によって取得できます。
held_currency は currency に名前が変更されました。
authorized_amount が merchant_amount に置き換えられました。merchant_amount は常に、加盟店の通貨によるキャプチャがオーソリまたは拒否された合計金額です。authorized_amount とは異なり、 merchant_amount は差戻しで減額できます。
authorized_currency は merchant_currency に名前が変更されました。
オーソリの承認エンドポイントで、held_amount は amount に名前が変更されました。
pending_request ハッシュが追加されました。これは、リアルタイムのオーソリの同期 Webhook リクエストでのみ入力されます。
- pending_held_amount が pending_request.amount に置き換えられました。
- pending_authorized_amount が pending_request.merchant_amount に置き換えられました。
- is_held_amount_controllable が pending_request.is_amount_controllable に置き換えられました。
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 の値のいくつかが廃止されました。
- authentication_failed、incorrect_cvc、および incorrect_expiry は verification_failed に統合されました。詳細については、authorization.verification_data をご覧ください。
- account_compliance_disabled と account_inactive は、account_disabled に置き換えられました。
- authorization_controls は、spending_controls に名前が変更されました。これは、Card (カード) および Cardholder (カード保有者) リソースで名前が変更された属性との整合性を保持するためです。
より詳細な説明を提供する verification_data.three_d_secure ハッシュが使用されるため、verification_data.authentication 列挙値が廃止されました。
- authentication に置き換わる three_d_secure.result は、以前よりも多くの値が格納されます。新しい値についての詳細はこちらをご覧ください。
- この属性は、3D セキュア機能に登録したユーザにのみ表示されます。
verification_data.address_zip_check は verification_data.address_postal_code_check に名前が変更されました。
wallet_provider属性は wallet に名前が変更されました。

取引

以下の 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 を送信する新しいイベントが使用されます。
すべての取引を一覧表示するエンドポイントからdispute クエリパラメーターが削除されました。
すべての取引を一覧表示するエンドポイントの settlement クエリパラメーターが、Settlement 機能ユーザーのみに制限されました。
取引データ機能強化ため purchase_details が追加されました。

カード保有者

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

カード

カードステータスの lost と stolen は削除されました。これらは、オプションの cancellation_reason が指定された canceled で表されます。
authorization_controls は spending_controls に名前が変更されました。

前

後

Command Line
curl https://api.stripe.com/v1/issuing/cards/ic_1CoYuRKEl2ztzE5GIEDjQiUI \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "status=lost"

Command Line
curl https://api.stripe.com/v1/issuing/cards/ic_1CoYuRKEl2ztzE5GIEDjQiUI \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "status=canceled" \
  -d "cancellation_reason=lost"

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

不審請求の申請

disputed_transaction は transaction に名前が変更されました。
balance_transactions を追加しました。これには、Dispute に関連付けられたすべての BalanceTransactions (残高取引) が格納されます。
- 各 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 (残高) オブジェクトから削除されました。代わりに issuing.available 残高を参照してください。