Payments apps overview
Payments apps are public apps that integrate with the Shopify admin to provide customized payment processing services for merchants. Only approved Partners can build payments apps on Shopify's Payments Platform.
Payments apps provide merchant stores with the following features:
- provide additional payment methods
- perform specific operations on payment methods
- control payment security for buyers
- automate payment services, such as reoccurring payments
- decide if they want to capture funds at the time of purchase or at the time of fulfillment. For more information, refer to Payment authorization
How payments apps workAnchor link to section titled "How payments apps work"
- The customer begins a payment or a refund.
- The merchant redirects the customer to an app-hosted page to begin their payment or refund.
- The payment or refund takes place on the payments app, which is hosted on the app-hosted page.
- The app performs app-specific operations during the payment.
- The app records the payment in Shopify admin.
RequirementsAnchor link to section titled "Requirements"
- You've created a public app in the Partner Dashboard.
- Your public app meets the following requirements:
If you don't meet the requirements, then Shopify can remove your app from the public list of payment gateways, suspend access to the payments ecosystem, terminate participation in the payments ecosystem, or take any other action deemed necessary.
Feature requirementsAnchor link to section titled "Feature requirements"
Payments apps need to have the following features:
- Merchants can charge, refund, and process test transactions.
- The app complies with the regulatory requirements for Strong Customer Authentication in the countries where credit card payments are processed. Being compliant might include implementing 3D Secure authentication.
Technical requirementsAnchor link to section titled "Technical requirements"
- Idempotency: To provide a consistent buyer experience, payments apps must implement idempotency.
- Retry policy: In case of network errors, payments apps must retry their requests according to the retry policy.
- Mutual TLS (mTLS): Authentication must be implemented to guarantee that traffic is secure and trusted in both directions between Shopify and your payments app. This authentication allows your app to confirm if an upstream request has originated from Shopify. Payments apps must use the Shopify CA certificate for verification.
- HMAC verification: For payments app installation, the
hmacparameter is included in the redirect to your payments app URL. You need to verify the authenticity of these requests using the provided
hmac. However, the HMAC verification process isn't applicable for payments operation requests that are initiated from Shopify to your payments app, such as
void. As a result, payments requests, don't include an
- Rate limiting: Your app's GraphQL requests are rate limited according to the rate limiting guidelines.
- API Versioning: Partners must implement a supported version of Shopify's Payments Apps APIs. Partners can configure the API version that their payments app will use to receive requests from Shopify. Partners must use the same API version for sending GraphQL requests. API versions are updated in accordance with Shopify's general API versioning timelines.
- 3-D Secure: If you offer credit card payment methods in a country where 3-D Secure authentication is mandated, then you must support 3-D Secure authentication.
- GDPR: You need to implement GDPR webhooks.
- Payments app extension configuration change approvals: To provide a positive buyer experience, your payments app extension configuration changes must be approved by Shopify. For more information on payments app extension changes and reviews, refer to How to become a payments partner.
Merchant experience requirementsAnchor link to section titled "Merchant experience requirements"
- Payments apps must, at a minimum, be operational and available on a 24-hour, 7 days a week basis at least 99.95% of the time in any measurement period.
- In the event of outages or issues, Partners must respond within 2 hours.
- Payments apps must provide servicing support to all merchants.
Transaction requirementsAnchor link to section titled "Transaction requirements"
This section describes the requirements for making transactions using a payments app. Payment apps must also support test mode.
mTLS configurationAnchor link to section titled "mTLS configuration"
Payments apps need to implement mTLS to handle all requests where the app acts as the server and Shopify acts as the client, such as when Shopify initiates sessions with payments apps for
void requests. In these cases, Shopify uses its own client certificate. Payments apps need to use the provided self-signed CA to validate Shopify's certificate. Using mTLS in these scenarios allows payments apps to verify that the client initiating the request is Shopify and that the traffic between Shopify and the payments app is trusted and secure.
Because mTLS is mutual, the payments app also needs to provide a certificate that Shopify will validate. For this certificate, you need to use a Trusted CA Signed SSL Certificate, and not Shopify’s self-signed CA.
Shopify's self-signed CAAnchor link to section titled "Shopify's self-signed CA"
IdempotencyAnchor link to section titled "Idempotency"
Payments Apps APIs support idempotency, which allows Shopify to safely retry requests without accidentally performing the same operation twice. It's critical in cases where there are network errors to prevent, such as multiple charges for the same payment.
Payments Apps APIs (HTTP requests from Shopify to your app)Anchor link to section titled "Payments Apps APIs (HTTP requests from Shopify to your app)"
You need to support idempotent requests for the Payments Apps APIs. Regardless of how many requests with the same idempotency key are sent, the result must be the same. The idempotency key attributes are defined on a per-API basis.
GraphQL mutations (GraphQL requests to Shopify)Anchor link to section titled "GraphQL mutations (GraphQL requests to Shopify)"
Idempotency is implemented, for a given
id, at a per operation name level. If multiple mutation requests of the same name are sent, then the operation is performed only once and the same response is returned. For example, if several PaymentSessionResolve requests were sent with the same
id, then the PaymentSessionResolve mutation is performed only once.
If requests with different names are sent with the same ID, then only the first request is processed. For example, if a PaymentSessionResolve and PaymentSessionReject request are sent for the same payment ID, then the
PaymentSessionResolve request is processed, and the
PaymentSessionReject request fails and returns a
In specific situations, if requests with different names are sent with the same ID, then the requests are processed. For example, if a paymentSessionPending request is sent first, then the next
paymentSessionReject request with the same ID is also processed.
Retry policyAnchor link to section titled "Retry policy"
Due to the asynchronous nature of Shopify's Payments Apps APIs, you must send a GraphQL request to notify Shopify of the results of any payment or refund requests. A retry policy helps provide data consistency between merchants, Partners, and Shopify.
If you don't receive an acknowledgment of a GraphQL request (HTTP 200 status code), then you must retry the request according to the following incremental strategy, up to a total of 18 retries over 24h.
|Number of recommended retries||The maximum number of recommended retries.||18|
|Base delay interval||The time interval after which the first retry is attempted.||5 seconds|
|Exponential backoff factor||Partners are expected to retry their requests immediately, and then 5 seconds afterwards, and then at increasing time intervals after that, until the request is acknowledged or 24 hours has passed, whichever comes first.||See example|
[0 seconds, 5 seconds, 10 seconds, 30 seconds, 45 seconds, 1 minute, 2 minutes, 5 minutes, 12 minutes, 38 minutes, 1 hour, 2 hours] + [4 hours] * 5
You must implement a retry policy for the Payments Apps API mutations.
Rate limitingAnchor link to section titled "Rate limiting"
To protect the stability of the platform, payments apps are rate-limited. For more information, refer to Shopify API rate limits.
Payments app approval processAnchor link to section titled "Payments app approval process"
Before a payments app can be approved on Shopify’s Payments Platform, three reviews are required:
- Payments Partner application review
- Payments app extension review
- Payments app review
Payments Partner application reviewAnchor link to section titled "Payments Partner application review"
- The Partner applies to become a Payments Partner.
- We grant the payment Partner access to build a payments app.
- If you've been approved to be a Payments Partner, you'll be granted access to Shopify’s payments ecosystem. You'll need to sign a revenue share agreement, which we provide in an email when you're approved.
The Partner creates a new public app in the Shopify Partner’s dashboard and emails us about the newly created app.
We grant API access scopes to the newly created app.
Payments app extension reviewAnchor link to section titled "Payments app extension review"
The Partner creates and configures the payments app extension.
The Partner submits the payments app extension for review.
We review the payments app extension.
If the app extension is approved, then the Partner can now publish the app extension.
The Partner tests the payments app extension on a development store.
Payments app reviewAnchor link to section titled "Payments app review"
The Partner fills out the app listing and submits the payment app for review. For more information, refer to the app review process.
We review the app.
If we approve the app, then the Partner can launch the app.
Optional: If the app needs to be changed before it can be approved, then the Partner reconfigures the payments app extension and submits a new version of the payments app extension for approval.
Payments app lifecycleAnchor link to section titled "Payments app lifecycle"
A payments apps can go through four states. Each of these states defines by whom and how your app can be installed, and the general visibility of the app for merchants. The states are the following:
Development: The default state of a payments app is
Development, after your first extension version is approved and published. The payments app can then be installed on dev stores for testing purposes.
Hidden: The payment app enters
Hiddenstate after the app is approved and published by the app review team. The payments app is not discoverable to merchants through the admin, but can now be installed by merchants by sharing the installation URL available in your dashboard.
Generally Available: The payments app enters
Generally Availablestate by request if it meets certain criteria, such as being used by at least 50 Shopify stores and has processed over 1,000,000 USD. The payments app is now discoverable from the store admin as an alternative payment provider for all merchants in supported countries. It will also appear in the public payments brochure.
Not Installable: If the payments app fails to meet the minimum product requirements, it will be put into
Not Installablestate. In this state, the app is not discoverable to merchants through the admin. The installation URL is removed from your dashboard, and it cannot be used for installation. The app can't be installed on any new shop, but shops that had the app installed previously will still be able to use it.
|Visible as alternative payments provider ?||only on dev stores||only if installed||yes||only if installed|
|Can process payments ?||only in test mode||yes||yes||yes|
|Has an installation URL ?||no||yes||yes||no|
|Visible on brochure ?||no||no||yes||no|
You can view the payments app state when you edit a version from the Edit draft page of your payments app extension.
Supported featuresAnchor link to section titled "Supported features"
Payments apps support the following features:
Supported payment methodsAnchor link to section titled "Supported payment methods"
Merchants can use payments apps to redirect customers to an app-hosted page for payment processing, which can include the following payment methods:
- Wallets (refer to Prohibited actions for current limitations)
- Buy Now Pay Later / Installments / Buyer Financing
- Bank Transfers / Online Banking
- Cash and ATM
Supported payment operationsAnchor link to section titled "Supported payment operations"
The payment methods support the following operations:
- Charge: Partners can collect a buyer’s payment information and charge them for their purchase.
- Refund: Merchants can trigger a refund from their Shopify admin.
- Authorize: Merchants can place a hold that can be charged at a later time.
- Capture: Merchants can charge the amount previously specified via an authorization.
- Void: Merchants can cancel a previously authorized amount.
Payments partner responsibilitiesAnchor link to section titled "Payments partner responsibilities"
Payment processing is a core part of Shopify merchants’ workflows. Our stores run 24/7 selling to buyers in a variety of currencies across the globe. We rely on and trust our payments Partners to provide a secure environment for buyers to purchase and help merchants handle settlement and payouts.
Payment securityAnchor link to section titled "Payment security"
During a buyer’s purchase, payments apps are responsible for the following:
- Securely collecting a buyer’s payment information and adhering to applicable law and any PCI requirements or market regulations, including the secure storage of buyer data.
- Processing the payment according to parameters specified by Shopify.
- Redirecting the buyer to Shopify.
- Settling transactions within five days.
Partners are responsible for monitoring and managing risk and fraud. If an unreasonably high percentage of a merchant's payments are fraudulent or high-risk (as determined in Shopify’s sole discretion), then Shopify may take action. Actions can include the following:
- Removing your payments app from Shopify's public list of payment gateways
- Restricting access to Shopify’s payments ecosystem
- Taking any other action deemed necessary
Transparent pricing and flexible merchant agreementsAnchor link to section titled "Transparent pricing and flexible merchant agreements"
- Partners must have transparent, easy-to-understand pricing for merchants.
- Partners can't offer low promotional or introductory rates for a limited time to later increase the rate.
- Partners can't refer to any fee, expense, or other costs as Shopify fees on invoices to merchants.
- Partners must allow merchants to terminate their merchant agreements with a 7-day notice period without penalty, fine, or other consequence.
Revenue share agreementAnchor link to section titled "Revenue share agreement"
All Partners are required to have a signed revenue share agreement with Shopify. Revenue share is calculated and applied on total payments volume (total GMV) processed by the payments app for all Shopify merchants with the app installed.
A signed revenue share agreement is required before Shopify approves a payments app to process real, live payments. More information will be provided after Partners have requested for access to the Payments Platform.
Prohibited actionsAnchor link to section titled "Prohibited actions"
Payments apps aren't permitted to do any of the following:
- Use any Shopify APIs other than the Payments Apps API and mandatory webhooks for GDPR.
- Store payment credentials for unapproved purposes. You can only use credentials for the original transaction or services approved by Shopify.
- Redistribute, share, transfer, sell unauthorized access to Shopify’s Payments Platform without Shopify’s approval. Access to Shopify’s payments ecosystem is strictly provided to the approved payments Partner only.
- Create fake or fraudulent merchants, orders, or sales.
- Process payment methods that include, but aren't limited to, Apple Pay, Google Pay, Shop Pay, PayPal, and Alipay. Shopify has a direct connection with providers that improves performance and checkout conversion for merchants.
Naming restrictionsAnchor link to section titled "Naming restrictions"
To make choosing additional payment methods as straightforward as possible for merchants, you should adhere to certain rules when naming your payments app:
- The name of the payments app can't contain marketing text: For example, the name “World's Best Provider: Get 50 payment methods” isn't allowed. This is because merchants won't see the name of the payments app until they have chosen the payment method they wish to add to their store.
- The name of the payments app can't be used by partners to gain a higher listing: There isn't a general alphabetized directory of payments apps for merchants to navigate. Instead merchants discover payments apps using the payment methods they want to add.
You should make sure that the payment methods and locations offered are accurate because this is the only information that's used to surface the app to merchants. If a name appears to have been created with the purpose of gaining a higher listing on an alphabetized list, then it will not be allowed.
Other considerations for payments appsAnchor link to section titled "Other considerations for payments apps"
- Line items, order ID, and checkout ID aren't available through the Payments Apps APIs.
- Payments apps aren't visible nor installable in the Shopify App Store.
- As part of the payment processing flow, buyers must enter their payment information on a page hosted by the payments developer.