Install and test a payments app on a development store

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

• You've created a payments app, submitted it for approval, and published a version.
• You've configured test mode for your payments app extension.

You can install your app on a development store to test your app.

1. From your Partner Dashboard, go to Apps.
2. Click the app that you want to test.
3. In the Test your app section, click Select store.
4. Select the store that you want to install your app on.
5. Click Install Anyway

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:

Payments apps should request for offline access. If no access mode is defined, then it defaults to offline access mode. Refer to OAuth for definitions of the app URL properties.

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 PaymentsAppConfigure mutation.

• write_payment_sessions: Allows access to APIs related to payment requests and callback APIs.

  • Required for paymentSessionResolve, paymentSessionReject, paymentSessionPending, captureSessionResolve, captureSessionReject, refundSessionResolve, refundSessionReject, voidSessionResolve and voidSessionReject.

For more detailed information, refer to Getting started with OAuth.

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:

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.

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.

For example:

• 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.

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.

You need to 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:

  

  

  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:

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.

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.

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.

1. From your Partner Dashboard, go to Apps.
2. Click the app that you want to enable a development preview for.
3. Click Extensions.
4. Select your payments app extension.

5. From the extension page, in the Working draft section, under Development store preview, click Enable.

   

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.

After you’ve implemented your app and ensured that it's production-ready, you can submit it for approval. For more information, refer to app review process.

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.