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 に名前が変更されました。
- 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
のパラメータを受け付けなくなります。 - カード詳細を取得するエンドポイントは廃止されました。その代わりに、取得エンドポイントから、番号とセキュリティコードを展開できます。
不審請求の申請
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 残高を参照してください。