Payments Apps APIに新設された信頼済みVault起源シグナル

10月 31, 2026

PAYMENTS API

Payments Apps APIに新設された
信頼済みVault起源シグナル

CVV不在でも決済を通すべきか判断できる新フィールド — 2027-01 RC で先行実装を

Payments Apps API バージョン 2027-01 RC より、payment_method.data.trusted_vault_origin フィールドが追加されました。クレジットカード決済・検証リクエストにおいて、ShopifyがCVVなしでも信頼できると判断したVault由来のカードかどうかをBoolean値で受け取れます。本番環境への即時移行は不要ですが、Shopify側の有効化が別途必要です。最終的な仕様は公式ドキュメントでご確認ください。

1変更内容の図解：Before / After

2業務に活かせる具体ユースケース

課題: サブスクリプション更新など、Vault保管カードによる自動決済でCVVが付与されず、既存の厳格なCVVルールにより決済が拒否されていた
打ち手: trusted_vault_origin: true を受信した場合のみ、CVV不在による拒否をスキップするロジックをハンドラーに追加する
効果: Vault信頼済みカードの自動更新成功率が向上し、不要なサブスク失敗通知・再試行コストを削減できる
技術メモ: payment_method.data の直下（encrypted card detailsやpayment_instrumentオブジェクトの外側）から読み取る。フィールドはオプショナルのため、不在ケースも必ずテストすること

課題: B2B・企業カードのように、カード会社がCVVを提供しないケースで決済が止まるが、その判断根拠がAPIから得られなかった
打ち手: Shopifyが当該appに対してフィールドを有効化した上で、true 受信時にのみCVV不在例外ルートを通す。それ以外は既存ルールを維持する
効果: CVV不在の正当なカードを正しく受理しながら、不正カードへの既存防御は損なわない二段構えの判断が可能になる
技術メモ: シグナルは起源Vaultの識別情報を含まない。fraud check・3DS・提供されたCVVの検証はtrue/false問わず継続が必須

課題: 新しいAPIバージョンへの移行時、既存の決済フロー・検証フローがフィールド追加で意図せず壊れないか確認が難しかった
打ち手: 開発用extensionのapi_versionを2027-01に設定し、true/false/不在 × CVVあり/なし × 各ペイロード形式 × verification requestの全組み合わせをテストする
効果: 本番移行前にエッジケースを網羅でき、リリース後の不具合リスクを最小化できる
技術メモ: APIバージョンを2027-01にするだけではフィールドは有効にならない。Shopify側の有効化確認が必須。有効化前はShopifyがフィールドを省略して送信する

3技術者が押さえるべき5つのポイント

ポイント	詳細
API バージョン	2027-01 RC から利用可能。本番は引き続きサポート済みの安定バージョンを使用し続けること。本番への即時移行は不要
有効化条件	APIバージョンの変更だけでは有効にならない。Shopifyによるアプリ単位の有効化が別途必要。有効化前・未送信時はフィールドが省略される
読み取り位置	`payment_method.data` の直下。encrypted card detailsオブジェクトやpayment_instrumentオブジェクトの内部ではない点に注意
セキュリティ継続	trueの場合もfalseの場合も不在の場合も、3-D Secure認証・不正チェック・提供CVVの検証は必ず継続する。このフィールドはCVV検証の代替ではない
対象スコープ	`payment_method.type` が `credit_card` のリクエストのみ対象。encrypted cardペイロードとpayment_instrumentペイロードの両方に含まれる可能性がある