Why am I getting 'Access Denied' when integrating a payment app with PHP in Shopify?

Shopify Apps

Topic summary

Access Denied errors occur when calling the PaymentsAppConfigure GraphQL mutation from a PHP cURL integration with a Shopify payment app. REST and other GraphQL calls succeed, but this mutation returns “You do not have permission”/“access denied” (screenshot provided).

Key causes identified:

  • Invalid or missing X-Shopify-Access-Token in the request header.
  • Missing mandatory OAuth scopes for payment apps: write_payment_gateways and write_payment_sessions (requested during app install).
  • PHP cURL requests without a User-Agent header can trigger 403 Forbidden; adding CURLOPT_USERAGENT resolved the issue for multiple participants.

Implementation notes:

  • Mutation: paymentsAppConfigure(externalHandle, ready). externalHandle value was questioned (e.g., using an API token), but no definitive answer provided.
  • Postman works (it sends a User-Agent by default), while PHP needed explicit CURLOPT_USERAGENT.

Outcomes:

  • Adding CURLOPT_USERAGENT fixed the error for some, confirming a header requirement not clearly documented by Shopify.

Open questions/remaining issues:

  • How to validate that payment permissions/scopes were granted post-install.
  • The correct/expected value for externalHandle.
  • One participant still receives “access denied” even after adding a User-Agent.

Status: Partially resolved; further clarification on permissions and externalHandle is pending.

Summarized with AI on February 21. AI used: gpt-5.
9

Thanks @Nermeen For information

Yes 100 % agree with you. There is no proper documentation on this