Adding Apple Pay, Google Pay, or another digital wallet to an online checkout is more than displaying a familiar button. This guide provides a reusable wallet payments integration checklist covering merchant validation, domains and certificates, token handling, authorization, recurring payments, refunds, fallback behavior, webhooks, and sandbox-to-production testing.
Overview
Digital wallet payments integration usually connects four moving parts: the shopper’s device or browser, the wallet platform, your checkout, and your payment processor or gateway. The wallet creates a payment credential, often represented as an encrypted or network-tokenized payload. Your integration passes that payload to the processor, which handles authorization and returns a result that your order system must record accurately.
The visible checkout experience can be simple, but the operational requirements are not. Wallet buttons may depend on device, browser, region, currency, merchant configuration, and whether the customer has an eligible card saved in the wallet. A successful implementation therefore needs both payment-path tests and failure-path tests.
Before starting, document your intended flow:
- Which wallet platforms and devices will be supported?
- Will the payment be authorized immediately, captured later, or split into separate actions?
- Will wallet payments be available for subscriptions, saved payment methods, or one-time purchases only?
- Which system is the source of truth for payment status: the client response, the processor, or confirmed webhooks?
- How will the checkout behave when a wallet is unavailable or a wallet transaction fails?
Keep payment credentials out of application logs and avoid assuming that a wallet payment is interchangeable with a manually entered card. The token format, lifecycle, authentication signals, refund process, and recurring-payment eligibility may differ by wallet and processor. For background on token types, see Payment Tokenization Explained.
Checklist by scenario
1. Before building the checkout
- Confirm that your payment gateway or payment API supports the wallet platforms, countries, currencies, environments, and transaction types you need.
- Create a written responsibility map for your merchant account, gateway, wallet configuration, domain registration, certificates, encryption, webhooks, and refunds.
- Register every production domain, subdomain, app identifier, or package identifier required by the relevant wallet and processor.
- Separate sandbox credentials, test certificates, test merchant identifiers, and test webhooks from production credentials.
- Define how wallet availability will be detected. Do not show a button merely because a browser or device appears compatible.
2. Merchant validation, domains, and certificates
- Complete the wallet provider’s merchant validation or domain-verification process for every checkout origin.
- Use HTTPS throughout the payment flow and verify that redirects, content-security policies, and embedded checkout frames do not block wallet initialization.
- Record certificate owners, expiration dates, renewal steps, production locations, and rollback contacts.
- Test certificate renewal in a controlled environment where possible, then verify the live merchant session after renewal.
- Check that load balancers, proxies, and web application firewalls pass the required validation requests without rewriting or caching them incorrectly.
3. One-time wallet payments
- Confirm the amount, currency, order reference, tax, shipping, and merchant descriptor before creating the payment request.
- Pass the wallet token to the processor using the documented field and encoding. Do not parse, modify, or store encrypted token content unless the integration specifically requires it.
- Test successful authorization, declined authorization, processor timeout, malformed token, duplicate submission, and customer cancellation.
- Test both immediate capture and separate authorization-and-capture flows if your business uses both.
- Make the order state idempotent so a retry cannot create two orders, two authorizations, or two captures.
4. Recurring billing and saved payment methods
Do not assume that a wallet token used for a one-time purchase can automatically fund recurring billing. Confirm the wallet and processor rules for merchant-initiated transactions, subscription setup, subsequent charges, customer consent, and payment-method updates. Test the complete lifecycle:
- Initial customer-initiated wallet payment.
- Storage or network-token registration, if supported.
- First scheduled charge and later retries.
- Expired, replaced, or unavailable payment credentials.
- Cancellation, mandate or consent records, and customer notifications.
Keep this flow separate from ordinary saved-card logic until the processor confirms that the same payment method representation and retry rules apply. The recurring billing and subscription guide provides a broader lifecycle checklist.
5. Refunds, disputes, and reconciliation
- Issue full and partial refunds using the processor’s payment reference, not only your internal order number.
- Verify how wallet transactions appear in processor reports, settlement files, customer statements, and dispute records.
- Match authorization, capture, refund, fee, and settlement events to one internal payment record.
- Confirm that support staff can identify wallet transactions without exposing sensitive token data.
For a broader matching process, use the payment reconciliation checklist.
Wallet-support comparison
| Area | Apple Pay | Google Pay | Other wallets |
|---|---|---|---|
| Availability | Depends on supported Apple devices, browser context, wallet setup, and merchant configuration. | Depends on supported browsers or devices, wallet setup, region, and merchant configuration. | Varies by provider, device, country, browser, and integration method. |
| Setup | Typically includes merchant identity, domain or app configuration, and certificates or validation steps. | Typically includes merchant profile, allowed origins or app configuration, and gateway setup. | Follow the provider’s current merchant, domain, app, and security requirements. |
| Token handling | Use the processor’s documented wallet-token flow; do not treat the payload as ordinary card data. | Use the processor’s documented wallet-token flow and required payment-method parameters. | Confirm token format, decryption responsibility, expiry, and storage restrictions. |
| Recurring use | Validate eligibility and merchant-initiated charging rules before promising subscriptions. | Validate eligibility and merchant-initiated charging rules before promising subscriptions. | Requirements differ; test setup, subsequent charges, and payment-method updates. |
What to double-check before launch
Run a pre-launch test matrix rather than relying on one successful device. At minimum, test supported desktop and mobile browsers, a wallet-enabled device, a device without an eligible wallet, authenticated and unauthenticated sessions, different order totals, supported currencies, shipping changes, discount codes, and network interruption during submission.
For each test, record the customer-visible result, processor response, webhook sequence, order status, inventory action, email or receipt, and reconciliation record. Include these cases:
- Wallet button hidden when the customer is ineligible.
- Wallet button visible and payment authorized successfully.
- Customer closes the wallet sheet.
- Issuer or processor declines the transaction.
- Client loses connectivity after submission but before displaying the result.
- Webhook arrives before, after, or instead of the browser response.
- Customer refreshes or double-clicks the payment control.
- Refund is issued partially and then fully.
- Subscription setup succeeds but a later recurring charge fails.
Review security boundaries as well. Apply least-privilege access to certificates and merchant credentials, redact tokens from logs, protect webhook endpoints, verify webhook signatures according to processor documentation, and maintain an appropriate PCI DSS scope record. The PCI DSS 4.0 checklist can help organize that review.
Common mistakes and troubleshooting workflow
Common failures include registering the wrong domain, using sandbox credentials in production, allowing a certificate to expire, showing a wallet button without checking eligibility, treating a browser response as final payment confirmation, and assuming every wallet token supports recurring billing. Another frequent problem is implementing a fallback that silently changes the amount, currency, shipping, or customer authentication experience.
When a wallet button does not appear, check the page origin, HTTPS certificate, browser and device eligibility, wallet account status, merchant registration, currency, country, and JavaScript or content-security-policy errors. When the button appears but the transaction fails, compare the request sent to the processor with the documented schema, inspect the processor response and webhook events, verify idempotency behavior, and confirm that the token was not altered.
Classify the failure before changing code:
- Presentation: the button is missing or incorrectly rendered.
- Validation: merchant, domain, certificate, amount, or currency configuration is rejected.
- Token processing: the wallet payload is invalid, unsupported, expired, or sent to the wrong endpoint.
- Authorization: the issuer, risk engine, or processor declines the payment.
- State management: the payment succeeds but the order, webhook, refund, or reconciliation record is wrong.
For decline investigation, consult the payment decline troubleshooting workflow and review risk rules without automatically weakening controls. Wallet payments still require appropriate fraud monitoring; related guidance is available in Payment Fraud Rules.
When to revisit
Re-run this checklist before a major seasonal release, mobile redesign, checkout migration, new country or currency launch, subscription feature, processor change, or certificate renewal. Revisit it after a material increase in wallet declines, unexplained duplicate orders, refund mismatches, webhook delays, or customer reports that the wallet button is missing.
At least twice a year, compare your implementation with the current wallet and payment-provider documentation. Review supported devices and browsers, merchant validation steps, certificate ownership, token formats, recurring-payment eligibility, refund behavior, authentication requirements, and sandbox coverage. Record the review date, documentation versions or links, test results, open risks, and the person responsible for the next update.
A practical maintenance routine is to keep one small automated smoke test for button availability and one controlled end-to-end payment test for each supported wallet. Pair those tests with monitoring for authorization outcomes, wallet-specific conversion, webhook failures, refund exceptions, and reconciliation gaps. This turns wallet payments integration from a one-time launch task into a manageable part of checkout operations.