記事のサマリー(TL;DR)
- Payments Apps APIの2027-01リリース候補で、クレジットカードの決済・検証リクエストに
payment_method.data.trusted_vault_originという任意のBoolean型フィールドが追加されました。 - 決済アプリ開発者はこのフィールドを使い、Shopifyが信頼するボールト(vault)由来のカードでCVVが欠落している場合の扱いを判定できます。
- 採用は任意であり、利用にはAPIバージョン2027-01以降への対応に加えて、Shopifyによるアプリ単位での有効化が必要です。
利用条件・制約
- 対象は
payment_method.typeがcredit_cardに設定されたリクエストを処理する決済アプリです。 - 拡張機能はAPIバージョン2027-01以降を使用する必要があります。ただし、APIバージョンを変更するだけではフィールドは有効になりません。
- Shopifyが該当アプリに対してこのフィールドを有効化している必要があります。
- 以下の場合、Shopifyはフィールドを送信しません:より古いAPIバージョンを使用している場合、対象アプリでフィールドが有効化されていない場合、送信する値がない場合。
- 本番環境での即時の移行対応は不要とされています。2027-01リリース候補はテスト用に使用し、本番アプリはサポートされている安定版バージョンに維持することが案内されています。
詳細
変更内容
Shopifyは、暗号化されたカード情報(encrypted card)とpayment_instrumentの両方のペイロードにtrusted_vault_originを含めることができます。このフィールドはpayment_method.dataから読み取るものであり、暗号化されたカード詳細やpayment_instrumentオブジェクトの外側に位置します。
値の意味は次の通りです。
- true:CVVが欠落しているという理由だけで、決済や検証を拒否してはいけません。ただし、CVVが存在する場合もあります。
- false、またはフィールドが存在しない場合:そのフローについて、CVVなしでの決済を許容するフローを含め、既存のCVVルールをそのまま維持します。
いずれの場合も、不正検知チェック、3-Dセキュア認証、提供されたCVVの検証は引き続き実施する必要があります。なお、このシグナルは発行元のボールトを識別するものではありません。フィールドの契約内容やペイロード例については、trusted vault originのリファレンスを参照するよう案内されています。
対象となる開発者
この変更は、payment_method.typeがcredit_cardに設定されたリクエストを処理する決済アプリに適用されます。拡張機能はAPIバージョン2027-01以降を使用する必要があり、かつShopifyが該当アプリに対してフィールドを有効化している必要があります。APIバージョンの変更のみではフィールドは有効になりません。
対応方法
本番環境での即時の移行は求められていません。2027-01リリース候補はテストに使用し、本番アプリはサポートされている安定版に維持することが推奨されています。
統合を準備するための手順として、次が挙げられています。
- 決済・検証ハンドラーを確認する。
- 上記で説明した任意フィールドとCVV処理のサポートを追加する。
- 統合テストのため、開発用拡張機能の
api_versionを2027-01に設定する。 - Shopifyから送信されることを期待する前に、対象アプリでフィールドが有効化されていることを確認する。
- true、false、フィールド不在の3パターンを、CVVの有無それぞれと組み合わせてテストする。
- アプリがサポートする各ペイロード形式を網羅し、該当する場合は検証リクエストについても同様のケースを繰り返す。
- trueの場合はCVV欠落が拒否につながらないこと、false・不在の場合は既存の処理が維持されることを確認する。
関連ドキュメント
- Configure payments extensions
- Test credit card payment requests
- Shopify API versioning