Onboarding a merchant to a payments app

Merchant experience

The key steps of the merchant's experience of your payments app are as follows:

  • Discovery: Payments apps can be installed by merchants directly through an installation link shared by the payments developer, or through Shopify’s public list of payment gateways, accessible on the Payment settings page in the Shopify admin.
  • Installation: Installation is the process in which a Shopify app authenticates using OAuth.
  • Configuration: After installing a payments app, merchants can select the specific payment methods that they want to present to buyers. After this is completed, customers will see a list of supported payment method icons on the merchant’s checkout.
  • Activation: Generate orders and complete payments for merchants.

The following diagram illustrates how all the aspects of the build process come together to support the merchant experience of your payments app:

Merchant experience overview

  1. Payments apps can be installed by merchants directly through an installation link shared by the payments developer or through Shopify’s public list of payment gateways in the Shopify admin.
  2. Merchant connects the app using OAuth.
  3. Merchant is redirected to the payments app page to perform configuration. During this time, a banner shows that the provider is not ready to process payments yet.
  4. Merchant configures the payments app.
  5. The app marks itself as ready by calling the Shopify API.
  6. Shopify enables the app to be activated by the merchant in Shopify admin.
  7. The merchant activates the app.


There are two ways for a merchant to discover a payments app:

  1. Through a direct installation link.
  2. Through Shopify’s public list of payment gateways under alternative payment methods.

To be added to the list of payment gateways in the Shopify admin, the payments app must be used by at least 50 Shopify stores and must have processed over $1,000,000, USD.


You use OAuth to obtain permission from the merchant to install your payments app. The merchant clicks on a link to install your app, which redirects to Shopify's OAuth screen.

After the merchant agrees to the OAuth permissions, your app requests an access token for API access.

Step 1: Connect to the app

After selecting a payments app for the first time, the merchant is presented with a description and a Connect button. By clicking Connect, the merchant is redirected to the Payments App URL. This triggers the installation through OAuth.

payments apps connect

Step 2: Host app URL

Host an OAuth app URL on your servers so that the merchant can give your app permissions:

Refer to OAuth for definitions of the app URL properties.


You can request the following OAuth access scopes from the merchant:

  • write_payment_gateways: Allows access to APIs related to merchant onboarding and readiness management.
    • Required for the PaymentsAppConfigure mutation.
  • write_payment_sessions: Allows access to APIs related to payment requests and callback APIs.
    • Required for PaymentSessionResolve, PaymentSessionReject, RefundSessionResolve, and RefundSessionReject.

For more detailed information, refer to Authenticate with OAuth.

Step 3: Get a token for the shop

You can get a token for a shop by exchanging the code for a token. When a merchant grants your app permissions, the following redirect URL is returned to your app server, including the code that can be exchanged for an access token:

Step 4: Redirect the user to your app's onboarding

The installation flow ends with the merchant being redirected to the redirection URL.

Provider authorization and configuration

After the installation is completed, the merchant is redirected to the payments app to complete configuration. What that page contains is totally up to the app developer. The merchant completes any required authentication or configuration as part of this step.

For example:

  • Prompt the merchant to login to or create an account with the payment provider.
  • Ask the merchant to complete configuration for billing plans, payouts, or notifications.

Provider readiness

Your app needs to inform Shopify that it's ready to process payments for the merchant. Until then, Shopify displays a warning banner in the Shopify admin as a reminder to the merchant.

payments apps connect

GraphQL mutation

You can set your app as ready to process payments by calling the paymentsAppConfigure mutation.

There are two required arguments that you need to supply in the mutation:

  • externalHandle: A username or identifier associated with the account that the merchant has used with the partner. This is displayed in the Shopify admin on the Payments section of the Shopify admin Settings. It allows the merchant to identify the connected payment provider account.
  • ready: A signal that the provider is ready to process payments. Accepted values are true or false.

    • true: Allows your app to process payments.
    • false: Indicates your app isn't yet able to process payments.

    You can set ready: false and externalHandle to let the merchant know that the account connection is established, but it's still awaiting finalization and approval to process payments:

    account status

payments apps connect


After the payments app is installed and ready, the merchant can activate the app to make it visible on the checkout page. The merchant can disable the app and hide it from the checkout page from the Payments section of the Shopify admin Settings.

For more information, refer to Alternative payment method apps.


If merchants no longer need a payments app, then they can deactivate it. When a merchant deactivates a payments app, customers can't select it at checkout for payment. However, merchants can still manage refunds and captures for orders created with the deactivated payments app. For more information, refer to Alternative payment method apps.

Next steps

Additional information