paymentSessionModal Mutation - Access Denied Despite All Scopes and Setup

GraphQL Admin API Troubleshooting
1

I’m implementing a Payments App. After marking a payment session as pending (paymentSessionPending, which works), I immediately call paymentSessionModal to show a QR modal after checkout.

Both paymentSessionPending and paymentSessionModal mutations require the write_payment_sessions access scope. However, only paymentSessionPending works; calling paymentSessionModal always fails.

The paymentSessionModal mutation always returns:

{
    "errors": [
        {
            "message": "Access denied for paymentSessionModal field. Required access: `write_payment_sessions` access scope.",
            "locations": [
                {
                    "line": 1,
                    "column": 87
                }
            ],
            "path": [
                "paymentSessionModal"
            ],
            "extensions": {
                "code": "ACCESS_DENIED",
                "documentation": "https://shopify.dev/api/usage/access-scopes",
                "requiredAccess": "`write_payment_sessions` access scope."
            }
        }
    ]
}

The same access token works for paymentSessionPending right before this.
Both use the same session ID, same shop, same endpoint call and require the same access scope.

Extra info

  • Endpoint:
    https://{shop}/payments_apps/api/2025-07/graphql.json

  • Access Token Scopes (via /admin/oauth/access_scopes.json):

{
  "access_scopes": [
    { "handle": "read_orders" },
    { "handle": "read_payment_gateways" },
    { "handle": "write_orders" },
    { "handle": "write_payment_gateways" },
    { "handle": "write_payment_sessions" },
    { "handle": "write_products" },
    { "handle": "read_payment_sessions" },
    { "handle": "read_products" }
  ]
}
  • Available mutations
    Querying the schema at:
https://{{shop}}/payments_apps/api/2025-07/graphql.json

With:

{
  __type(name: "MutationRoot") {
    fields {
      name
    }
  }
}

returns paymentSessionModal as available in the list of mutations:

{ "name": "paymentSessionModal" }
1 Like
2

Hey @serinolli,

The modal should be available on the latest API version 2025-07 and it looks like you’ve met the criteria outlined.

Let me dig in deeper here to see what I can find. I may send a DM to get some more specific details from you if needed.

1 Like
4

Hey @serinolli,

After looking in to this further, I’ve identified some additional scopes that are needed that your partnerships manager will be able to enable for you.

You can see this in our documentation here: https://shopify.dev/docs/apps/build/payments/alternative/build-an-alternative-payment-extension?framework=remix#using-the

To initiate a request for Shopify to present a buyer verification challenge, your payments extension will need to use the paymentSessionModal mutation.

Prerequisites:

  • Shopify needs to grant you the write_payment_session_modals and read_payment_session_modals access scopes. Check with your partnerships manager if these scopes are not already enabled for your app.

We will work to update our primary graphql docs to highlight this as well. Thanks so much for reporting this discrepancy!