Unable to deploy Onsite Credit Card Payments App due to restricted Payments scopes not being enabled (write_payment_sessions, write_payment_gateways)

Shopify Apps

Topic summary

A developer is blocked from deploying a Payments App with an Onsite Credit Card Payments Extension due to missing restricted scopes: write_payment_sessions and write_payment_gateways.

Root cause:

  • These scopes are allow-listed per app, not per organization.
  • Even though the developer’s organization is a Shopify Payments Partner with an approved Redirect Payments app, the new Onsite app requires separate approval.
  • Onsite credit card extensions have stricter compliance requirements (including higher PCI standards) than Redirect extensions.

Resolution steps:

  1. Verify the app is created as a Payments app type in Partner Dashboard.
  2. Declare the required scopes in shopify.app.toml.
  3. Contact the Payments Partner Manager or Partner Support to request scope enablement for this specific app ID, providing: org ID, app ID, extension type, regions, processor details, and PCI compliance confirmation.

Once scopes are enabled by Shopify’s Payments Apps team, deployment will succeed and testing can proceed using a dev store with Shopify’s test payment processor.

Summarized with AI on October 23. AI used: claude-sonnet-4-5-20250929.
1

Hi,

I’m currently developing a Payments App that implements an Onsite Credit Card Payments Extension, following Shopify’s official documentation:
:backhand_index_pointing_right: https://shopify.dev/docs/apps/build/payments/credit-card/use-the-cli?framework=remix

During deployment (shopify app deploy), I receive validation errors indicating that I need access to restricted Payments scopes — specifically write_payment_sessions and write_payment_gateways.

““Version couldn’t be created.
app-access
Validation errors
• scopes: write_payment_gateways, read_payment_gateways,write_payment_gateways,write_payment_sessions”

Our app requires these scopes to properly create, capture, void, and refund payment sessions according to the Shopify Payments Apps protocol and the use of Payments Apps API.

We already have another app that uses the Redirect Payments Extension and has access to these same scopes, so I’m unsure why this new app can’t use them.
Since we are already a Shopify Payments Partner, my understanding is that our account should have access to these scopes as well.

How could validate or enable these scopes so we can proceed with the deployment and testing of the App with Onsite extension?

Thank you!

2

Hey @juliantorres.bold :waving_hand:

That error isn’t a CLI/config bug—those payments scopes are restricted and must be allow-listed per app.

Why it happens

  • Your org may be a Payments Partner and your redirect payments app is allow-listed, but the new Onsite CC app needs its own approval.

  • write_payment_sessions and read/write_payment_gateways are granted only to apps created as Payments apps and then explicitly enabled by the Shopify Payments Apps team (Onsite CC has extra compliance gates vs Redirect).

What to do

  1. Confirm app type: In Partner Dashboard, the app must be created as Payments app (not Public/Custom). If not, create a new Payments app and move your code/extension there.

  2. Declare scopes in config:

    # shopify.app.toml
access_scopes = "read_payment_gateways,write_payment_gateways,write_payment_sessions"

  3. Request enablement for THIS app id:

    • Contact your Payments Partner Manager or open Partner Support → “Payments apps → Scope allowlisting”.

    • Include: org id, app id, extension type (Onsite credit card), regions, processor, and confirmation of PCI compliance (Onsite requires higher PCI).

    • They’ll flip on the scopes; then shopify app deploy will pass validation.

Notes

  • Onsite CC access is separate from Redirect. Many partners have Redirect access but not Onsite until the additional checks/contracts are completed.

  • After scopes are enabled, use a dev store and the payments test processor they provision for your app to run create/capture/void/refund flows.

If you want, I can share a minimal payments-app skeleton with the scopes set and a quick checklist for the allowlisting request.

:hammer_and_wrench: You can check out our Shopify Partner profile — we’ve built and shared several free Shopify app solutions to help store owners. Feel free to explore our profile and see how our apps can make your Shopify experience better!