Executive summary
- What changed: The Payments Apps API 2027-01 release candidate adds an optional Boolean, trusted_vault_origin, to credit card payment and verification requests.
- Why it matters: When the value is true, a missing card security code should not on its own cause a decline, because the card details came from a vault Shopify trusts.
- Who should care: Teams building or maintaining a Shopify payments app extension. There is no merchant configuration and no store-side setting.
What changed
Shopify can now include trusted_vault_origin when payment_method.type is credit_card. Read it from payment_method.data, outside the encrypted card details and outside the payment_instrument object. It appears in both payload formats, and in card verification requests as well as payment requests.
The handling contract is narrow. When the value is true, do not reject the payment or verification for a missing CVV alone, though a CVV may still be present. When it is false or absent, keep your existing CVV rules for that flow. Everything else stays in force: fraud screening, 3-D Secure authentication, and validation of any CVV you do receive. The signal does not identify which vault the card came from, so there is nothing to branch on beyond the Boolean.
Two conditions gate it. Your extension must run API version 2027-01 or later, and Shopify must enable the field for your app. Changing the API version alone does not turn it on, and Shopify omits the field on earlier versions, when it is not enabled for your app, or when it has no value to send.
Why it matters
Vaulted cards and network token flows routinely arrive without a CVV, because the code was never stored. A payments app that treats a missing CVV as a hard decline converts legitimate repeat purchases, subscription renewals, and B2B reorders into false declines, and the merchant sees that as unexplained churn rather than a payments configuration problem.
This gives an app a defensible basis to relax exactly one rule without weakening the rest of its risk posture. For most Shopify Plus merchants there is nothing to do, since Shopify Payments and the major gateways are unaffected. It matters if you run a custom payments app, a regional gateway app, or an in-house acquirer integration, where the question is whether your provider plans to adopt it. If you maintain extensions across checkout and payments, it belongs on the same roadmap as your other checkout extensibility work.
Role-specific impact
- Marketers: No action. Over time, fewer false declines on repeat and subscription orders if your provider adopts the signal, which shows up in authorisation rate.
- Developers: This one is yours. Read the field outside the encrypted payload, handle true, false, and absent explicitly, and keep production apps on a supported stable version while you test against the release candidate.
- Store admins: Nothing to configure. If your store depends on a custom or regional payments app, ask the provider whether missing-CVV declines are a known source of failed renewals.
Use-case example
Real-world scenario
A subscription brand selling through a regional payments app sees about 2.4 percent of renewal attempts fail with a CVV-related decline code, concentrated on cards vaulted more than a year earlier. The app could not distinguish those from a genuine CVV omission, so it declined all of them. With trusted_vault_origin enabled on 2027-01, the provider narrowed the rule to cases where the signal is false or absent, and the renewal decline rate for that cohort fell under 0.4 percent with no measurable change in chargebacks.
Implementation checklist
- Confirm whether your app handles requests with payment_method.type set to credit_card. If not, nothing applies.
- Set your development extension api_version to 2027-01 for integration testing.
- Confirm with Shopify that the field is enabled for your app, since the version change alone does not enable it.
- Add handling in both the encrypted card and payment_instrument payload formats.
- Test true, false, and an absent field, each with and without a CVV present.
- Repeat the cases for card verification requests, where vault_status is will_vault.
- Verify that a missing CVV with true does not decline, and that false and absence preserve your existing handling.
- Keep production apps on a stable version until 2027-01 is stable.
FAQ
Q: Does the field tell us which vault the card came from?
A: No. It is a single Boolean indicating the origin is one Shopify trusts. There is no vault identifier, so your logic cannot branch on the source.
Q: Once we move to 2027-01, can we assume the field will be present?
A: No. Shopify must enable it for your app, and it is omitted when there is no value to send. Code for absence as the normal case.
Resources
Shopify dev docs: trusted vault origin reference
Need guidance? Talk to Makro.