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 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.
- 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.
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.
- 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.
- 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 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.
This section describes the requirements for making transactions using a payments app. Payment apps must also support test mode.
Payments apps must implement mTLS to handle all* requests where they are acting as the server and Shopify as the client. This is the case when Shopify initiates sessions with payments apps. In those cases, Shopify uses its own client certificate. Payments apps must use the self-signed CA provided below to validate that 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.
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)
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)
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 both 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
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.
To protect the stability of the platform, payments apps are rate-limited. For more information, refer to Shopify API rate limits.
The process of creating a payments app extension
- Apply to become a payment provider, and review the Additional Terms Applicable to Payments Developers section of the Shopify Partner Program Agreement. If you aren't a Shopify Partner yet, then you must sign up to be a Partner.
- If you've been approved to be a payments Partner, then you'll be granted access to Shopify’s payments ecosystem. You'll need to sign a revenue share agreement.
- Create your payments app extension.
- Configure your payments app extension.
- Submit your payments app extension.
- Get your payments app extension approved.
- Test your app payments app extension on a development store.
Payments apps support the following features:
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 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 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.
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 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 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.
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 for which Shopify already has a direct relationship. This includes, but is not limited to the following: Apple Pay, Google Pay, Shop Pay, PayPal, and Alipay.
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 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.