Skip to main content

New trusted vault origin signal in Payments Apps API

The Payments Apps API 2027-01 release candidate adds payment_method.data.trusted_vault_origin to credit card payment and verification requests. Payment app developers can use this optional Boolean to handle missing CVV for cards from a vault Shopify trusts. Adoption is optional and requires Shopify enablement.

What changed

Shopify can include trusted_vault_origin in both encrypted card and payment_instrument payloads. Read it from payment_method.data, outside the encrypted card details or payment_instrument object.

  • true: Don't reject the payment or verification for missing CVV alone. A CVV may still be present.
  • false or absent: Keep your existing CVV rules for that flow, including flows that accept payments without CVV.

Continue your fraud checks, 3-D Secure authentication, and validation of any CVV provided. The signal does not identify the originating vault. See the trusted vault origin reference for the field contract and payload examples.

Who's affected

This applies to payments apps that handle requests with payment_method.type set to credit_card. Your extension must use API version 2027-01 or later, and Shopify must enable the field for your app. Changing the API version does not enable it.

Shopify omits the field on earlier API versions, when it has not enabled the field for your app, or when it has no value to send.

What to do

No immediate production migration is required. Use the 2027-01 release candidate for testing and keep production apps on a supported stable version.

To prepare your integration:

  1. Review your payment and verification handlers. Add support for the optional field and the CVV handling described above.
  2. For integration testing, set your development extension's api_version to 2027-01. Confirm Shopify has enabled the field for your app before expecting Shopify to send it.
  3. Test true, false, and an absent field, with and without CVV. Cover each payload format your app supports and repeat the cases for verification requests if applicable. Confirm that missing CVV does not cause rejection for true, while false and absence preserve your existing handling.

Related docs

Was this page helpful?