A payment integration can pass every demo and still fail on its first real customer: a payment confirmed only in the browser, a webhook processed twice, a refund that leaves Shopify and the provider out of step. This checklist gathers the checks to run before an integration takes real money. Each item should be a clear “yes” before go-live.
Who it is for. Merchants switching or adding a payment provider, and the developers or agencies shipping the integration. Items marked (custom) apply when the provider is connected through a custom integration (for example when it is not available in Shopify’s checkout); a provider installed from Shopify’s payment settings handles most of them for you.
1. Provider account and money flow
- The live account is fully verified on the provider’s side (identity, business documents), not only created.
- The payout bank account is verified, and you know the payout schedule and any reserve the provider applies.
- Every country, currency, card network and local method you need is enabled on the live account, not only in the sandbox.
- The statement descriptor (the name shown on the customer’s bank statement) is one your customers will recognise.
- The total cost is understood: provider fees, currency conversion, chargeback fees and, when you do not use Shopify Payments, the additional transaction fee Shopify may charge depending on your plan.
2. Credentials and access
- Live API keys live on a server, in environment variables or a secret manager. Never in the theme, in front-end JavaScript or in a code repository.
- Test and live keys are separated by environment, so the live store cannot run on test keys, and the reverse.
- Each key has the minimum permissions it needs, including the scopes of any Shopify Admin API access.
- Webhook signing secrets are stored server-side, with a written procedure to rotate them.
- Provider and Shopify dashboards use two-step authentication, and access is limited to the people who need it.
- Card data never reaches your servers: the customer types it on the provider’s hosted payment page or hosted fields. This keeps your PCI DSS scope as small as possible.
3. Payment flow (custom)
- The amount and currency are computed on the server from the Shopify order, never taken from the browser.
- Each order has one payment reference, stored on both sides: the provider’s transaction ID on the Shopify order, the Shopify order ID in the provider’s metadata.
- Creating a payment is idempotent: a double click or a retried request cannot charge the same order twice. Use the provider’s idempotency key when it offers one.
- The payment is confirmed server to server, through the provider’s webhook or an API status check. Never from the browser redirect alone: customers close tabs before returning, and anyone can open a return URL.
- Success, failure and cancellation pages each lead somewhere sensible, and none of them marks the order as paid by itself.
- Strong customer authentication is tested. In the EU and the UK, most online card payments go through 3-D Secure: test a challenge that succeeds, one that fails and one the customer abandons.
- Expired payment sessions have a defined outcome for the order: cancel it, send a reminder, or keep it pending for a set time.
4. Webhooks and order state
- Every webhook signature is verified on the raw request body before anything else is read. Our guide Webhook vs API explains why, and the open-source shopify-webhook-patterns repository shows it in Node.js and Python.
- The endpoint answers 2xx within seconds and does the work afterwards, in a queue. Shopify, for its own webhooks, expects a response within five seconds.
- Duplicates are absorbed at two levels: repeated deliveries are skipped using the delivery ID, and an order can be marked paid, fulfilled or invoiced only once. On Shopify, the
orderMarkAsPaidmutation only applies to an order that still has an outstanding balance and is not already paid, which helps, but your own logic should still check before acting. - Out-of-order events cannot corrupt an order: a refund event that arrives before the payment event must not leave the order in the wrong state.
- Shopify webhook subscriptions are monitored. After 8 consecutive failed deliveries, a subscription created through the Admin API is deleted and Shopify emails the app’s emergency developer address: make sure someone reads that inbox.
- A scheduled reconciliation compares provider transactions with Shopify orders and alerts on differences: a payment without an order, an order marked paid without a transaction, an amount that does not match. Shopify’s own documentation describes this kind of job as a common practice to recover data a webhook missed.
5. The Shopify order
- The order is marked as paid only after a confirmed payment, and its financial status, transactions and payment method name look right in the admin.
- Stock behaviour is decided: reserved at order creation or at payment, and tested for an abandoned payment.
- Customer notifications go out once, at the right moment: no “order confirmed” email before the payment is confirmed when your flow creates the order first.
- Full and partial refunds work end to end: the money is returned by the provider and the refund is recorded in Shopify, and the team knows which side to start from.
- Cancelled and expired payments leave no forgotten pending orders: each one is cancelled, reminded or reviewed.
6. The test matrix
Run each scenario in the provider’s sandbox first, then finish with one real low-value payment made with your own card, and refund it.
| Scenario | Expected result |
|---|---|
| Successful payment | Order paid once, one confirmation email, stock updated |
| Card declined | Order not paid; the customer can retry or choose another method |
| 3-D Secure: succeeded, failed, abandoned | Paid only in the first case; a clear message in the other two |
| Customer pays, then closes the tab before the redirect | Order still marked paid, through the webhook or the status check |
| Double click on the pay button | A single charge |
| Same webhook delivered twice | Processed once |
| Webhook endpoint down for ten minutes | Retries or the reconciliation job bring the order up to date |
| Provider API times out | Clear message to the customer, no duplicate charge on retry |
| Full refund, then a partial refund on another order | Provider and Shopify agree on amounts and status |
| Each market and currency you sell in | Right currency, right amount, right payment methods |
| Mobile browsers (Safari on iOS, Chrome on Android) | Redirect and return work, including after a banking app switch |
7. Monitoring and runbook
- One log line per payment attempt and per webhook, with the order ID, the provider reference, the status and any error code. No card data and no secrets in the logs.
- Alerts on failed webhooks, on reconciliation differences and on a sudden rise in declines.
- A short runbook: where to look when a customer says “I paid but I have no order”, who contacts the provider, and how to switch the payment method off quickly. Our guide on why payments are refused on Shopify covers the first diagnostic steps.
- A fallback: another payment method can stay available if the integration has to be switched off.
8. Customers and accounting
- The payment methods and card logos shown at checkout match what is really accepted.
- Error messages tell the customer what to do next: retry, use another card, or contact you.
- Terms of sale and the refund policy are published and easy to reach from checkout.
- Payouts, fees and refunds can be matched to orders, for example by exporting the provider’s transaction IDs, and your accountant knows where to find them.
Frequently asked questions
Do I need all of this for a provider listed in Shopify’s payment settings?
No. Sections 3 and 4 are mostly handled by the provider’s payments app. Keep sections 1 and 2 for accounts and access, the refund checks of section 5, the relevant rows of the test matrix, and sections 7 and 8. To compare providers first, read how to choose a Shopify payment provider.
Can I mark an order as paid when the customer lands on the success page?
No. Treat the return page as a message to the customer. The payment is confirmed only when your server receives the provider’s signed webhook or reads the payment status from the provider’s API.
Is this a legal or PCI compliance checklist?
No. It covers technical and operational checks. Your payment provider, and a qualified adviser where needed, confirm your compliance obligations for your country and business.
Launching a new payment setup? See our payment gateway integration services, including our SumUp Shopify integration. For webhooks and synchronisation with your other tools, see API integration and automation, or describe your project.