Creating a payments app

Creating a payments app extension requires configuration, versioning, and publishing. Publishing a new version requires review and approval by Shopify. This process is covered in the procedure below.


This guide assumes you've created a public app in the Partner Dashboard.

Configuring the app extension settings

To configure the app extension settings, you need to give your extension a name, open a draft to edit the configuration, and then version and publish it.

To configure your app extension:

  1. From your Partner Dashboard, click Apps.
  2. Click the name of the app that you want to change.
  3. Click Extensions.
  4. Under Payments click the Offsite payment provider card.
  5. Enter your extension name and select Save.

Editing the configuration

To edit the configuration:

  1. From the extension settings, click Open draft.

creating a draft

2. Configure the fields of the Payments extension details in the table below.

3. Click Save draft when you're done. You can also create a version as described below.

Payments extension details

Field Description
Payment session URL The URL that will receive payment and order details from the checkout.
Refund session URL The URL that refund session requests will be sent to.
Capture session URL The URL that capture session requests will be sent to.
Void session URL The URL that void session requests will be sent to.
Payment methods The payment methods (for example, Visa) that are available with your payment provider app.
Available countries The countries where your payment provider app is available.
Merchant admin name The name for your payment provider app. This name is displayed to merchants in the Shopify admin when they search for payment methods to add to their store. Limited to 50 characters.
Checkout name Optional. The name of the checkout. Your checkout name can be the same as your Merchant admin name or it can be customized for customers. This name is displayed with the payment methods you support in the customer checkout. After a checkout name has been set, translations should be provided for localization.
Test mode Allows merchants using your payment provider app to test their setup by simulating transactions. To test your app on a development store, your alternative payment provider in the Shopify admin must be set to test mode.
Buyer features The customer features that your payment provider app offers. 3D Secure support is mandated in some instances. For example, you must select the 3D Secure buyer feature checkbox if you plan to support credit card payments in countries which have mandated 3D Secure.
API Version The API version used by the payment provider app. This determines which version is used for requests being sent to the app. Currently, all versions of the payments app schema send identical payloads.

Versioning and publishing

After you're finished with your draft, you can version and publish it. To create a new version:

  1. From the Extension details screen, click Create version.

    editing a draft

  2. Select Minor or Major version depending on the nature of your code changes. Minor versions introduce changes that are backwards compatible. Major version changes aren't backwards compatible and might affect users who are currently using your extension.

  3. Click Submit for Review to submit a version of your extension to Shopify for approval:

    submitting an app extension version for review

  4. Wait for Shopify to approve your new version. While Shopify is reviewing your extension, the version displays in a Pending state:

    the app extension version displays in a pending state

    After Shopify approves your extension version, it's marked as Approved. The current version is marked with a Live tag:

    the app extension version displays in an approved state

  5. To publish your new version, select Publish beside the version you'd like to make live.

    You can't edit a version after it's created. If you want to change settings, then you have to create and publish a new version by clicking Edit draft.

Unpublishing a version

Do not unpublish a version. Instead, you should publish a different version.

Unpublishing a version invalidates the payments app provider. It breaks the payments app provider for stores that have it installed because the store will try to fetch a published version that no longer exists.

Next steps