Onboard a merchant to a payments app
Before a merchant can use your payments app, they need to go through an onboarding experience. This guide describes how a merchant discovers, installs, authorizes, and activates a payments app.
RequirementsAnchor link to section titled "Requirements"
- Your payments app needs to be approved before merchants can install it on their Shopify store.
- You're familiar with the different phases of the onboarding cycle for payments apps.
Step 1: Discover a payments appAnchor link to section titled "Step 1: Discover a payments app"
A merchant can discover a payments app in the following ways:
- Through a direct installation link.
- Through Shopify’s public list of payment gateways under additional payment methods.
To be added to the list of payment gateways in the Shopify admin, the payments app must meet certain criteria, such as being used by at least 50 Shopify stores and having processed over 1,000,000 USD.
Step 2: Install the payments appAnchor link to section titled "Step 2: Install the payments app"
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.
Payments app installation URLAnchor link to section titled "Payments app installation URL"
When you edit a version from the Edit draft page, you can access a URL that links to the provider page corresponding to your payments app. You can share this URL with merchants so that they can install your payments app on their stores.
The URL displays only after Shopify has approved your payments app.
Step 2A: Connect to the appAnchor link to section titled "Step 2A: 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 installation URL. This triggers the installation through OAuth.
Step 2B: Host an OAuth app URLAnchor link to section titled "Step 2B: Host an OAuth app URL"
Host an OAuth app URL on your servers so that the merchant can give your app permissions:
Payments apps should request for offline access, by setting
value. If no access mode is defined, then it defaults to offline access mode. Refer to OAuth for definitions of the app URL properties.
PermissionsAnchor link to section titled "Permissions"
You should only 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
- Required for the
write_payment_sessions: Allows access to APIs related to payment requests and callback APIs.
- Required for
- Required for
For more detailed information, refer to Getting started with OAuth.
Step 2C: Get a token for the shopAnchor link to section titled "Step 2C: 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 2D: Redirect the user to your app's onboardingAnchor link to section titled "Step 2D: Redirect the user to your app's onboarding"
The installation flow ends with the merchant being redirected to the redirection URL.
Step 3: Complete provider authorization and configurationAnchor link to section titled "Step 3: Complete 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.
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 readinessAnchor link to section titled "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.
GraphQL mutationAnchor link to section titled "GraphQL mutation"
You can set your app as ready to process payments by calling the
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: Allows your app to process payments.
false: Indicates your app isn't yet able to process payments.
You can set
externalHandleto let the merchant know that the account connection is established, but it's still awaiting finalization and approval to process payments:
After the merchant has completed all the actions that are required for your app's onboarding, they must be redirected back to the Shopify admin using the following URL:
Step 4: Activate a payments appAnchor link to section titled "Step 4: Activate a payments app"
After authorization and configuration are complete, merchants are redirected back to the Shopify admin to select payment methods to offer. These payment methods are displayed to customers as payment icons during checkout.
Merchants use the additional payment method settings in the Shopify admin to activate and deactivate payments apps.
For more information, refer to Additional payment method apps.
Step 5: Deactivate a payments app (optional)Anchor link to section titled "Step 5: Deactivate a payments app (optional)"
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 Additional payment method apps.