Install and test a payments app on a development store
You can install your payments app on a development store to test it. This tutorial shows how to install a payments app and enable a development preview to test draft extensions. This is a similar to how merchants onboard to your payments app. Refer to merchant onboarding for more details.
What you'll learnAnchor link to section titled "What you'll learn"
In this tutorial, you'll learn how to do the following tasks:
- Install your payments app extension on a development store
- Enable the development store preview to test your changes
- Fill out testing instructions for your payments app extension
RequirementsAnchor link to section titled "Requirements"
- You've created a payments app, submitted it for approval, and published a version.
- You've configured test mode for your payments app extension.
Step 1: Install your payments app on a development storeAnchor link to section titled "Step 1: Install your payments app on a development store"
You can install your app on a development store to test your app.
- From your Partner Dashboard, go to Apps.
- Click the app that you want to test.
- In the Test your app section, click Select store.
- Select the store that you want to install your app on.
- Click Install Anyway
Step 2: Trigger the OAuth FlowAnchor link to section titled "Step 2: Trigger the OAuth Flow"
Step 2A: Host an OAuth app URLAnchor link to section titled "Step 2A: Host an OAuth app URL"
By clicking Install Anyway, the merchant is redirected to the Payments app installation URL. This triggers the installation through OAuth. Use OAuth to obtain permission from the merchant to install your payments app.
Host an OAuth app URL on your servers so that the merchant can give your app permissions:
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 2B: Get a token for the storeAnchor link to section titled "Step 2B: Get a token for the store"
You can get a token for a store by exchanging the code for a token. When a store 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 2C: Redirect the merchant to your app's onboardingAnchor link to section titled "Step 2C: Redirect the merchant to your app's onboarding"
Click Install unlisted app. The installation flow ends with the merchant being redirected to the redirection URL passed in the OAuth flow in Step 2A.
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 up to you. Complete any required authentication or configuration as part of this step.
Prompt a merchant to login to or create an account with the payment provider.
Ask a 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 store. Until then, Shopify displays a warning banner in the Shopify admin as a reminder to complete the account set up by clicking on Manage.
GraphQL mutationAnchor link to section titled "GraphQL mutation"
You need to 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: Enable test mode for the payment gatewayAnchor link to section titled "Step 5: Enable test mode for the payment gateway"
After you've configured test mode for your payments app extension, you need to enable test mode for the payment gateway on the development store.
When a payment gateway is in test mode, requests from Shopify include the
test attribute. If
test is set to
true, then the payment is processed as a test payment and no real transaction is made.
Step 6: Enable development store previewAnchor link to section titled "Step 6: Enable development store preview"
You can enable the development store preview to test your changes quickly by using the draft version configuration instead of the published version on the development stores where your app is installed. This is useful to avoid going through the approval process to publish multiple versions during development.
When you test your payments app on a development store, the app needs to use the draft version configuration. If you disable the development preview, then the development store needs to revert to the published version.
- From your Partner Dashboard, go to Apps.
- Click the app that you want to enable a development preview for.
- Click Extensions.
- Select your payments app extension.
From the extension page, in the Working draft section, under Development store preview, click Enable.
Step 7: Deactivate a payments app (optional)Anchor link to section titled "Step 7: 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.
Step 8: Submit your app for approval after implementationAnchor link to section titled "Step 8: Submit your app for approval after implementation"
You need to fill out the Testing instructions on the app listing with the following details:
- The credentials to enable installing the payments app for testing. For example, activation codes and login credentials.
- The instructions on how to process a test payment and refund
- A description of specific testing scenarios:
- Installments or deferred payments
- 3D Secure authentication, if applicable
- A screencast of how your payments app or payment flow works on each of the supported browsers.
For more information, refer to submitting your app.