Hyperswitch Apple Pay and Google Pay setup

The decryption option you choose decides which system opens the encrypted Apple Pay payload. That choice moves key custody, PCI DSS scope and the approvals you need from each processor. Hyperswitch documents three Apple Pay options: Hyperswitch decryption, PSP decryption and merchant decryption. For Google Pay, the docs cover Hyperswitch decryption and PSP decryption. Before configuration starts, record for each wallet which option you will run, which processors sit behind it, and who in your organization signs off on the decision. Key material, network segmentation and processor agreements are expensive to rebuild once they exist, so settle this as an architecture decision first.

With Hyperswitch decryption, your self-hosted router decrypts the payload. Your team must hold the Apple Pay merchant identity material and private keys inside your deployment, so those keys share a trust boundary with the app server, PostgreSQL and Redis. Store them in a secrets store you operate, restrict which service accounts and administrators can read them, and log every access. Decrypted payment data then passes through components you run, so ask your QSA or compliance lead to map which Hyperswitch services fall inside the cardholder data environment. Expect that map to be broader than the processor-side model. Confirm the exact certificates and keys the current Apple Pay docs require before you request them.

With PSP decryption, your processor decrypts the payload and Hyperswitch passes the encrypted wallet data through to it. Your team holds fewer long-lived decryption secrets, but the model depends on the processor supporting the wallet and approving the feature on your merchant account. Ask each processor, in writing, whether it accepts Hyperswitch-forwarded encrypted payloads for Apple Pay web and in-app flows, what it needs from you, and whether the same account supports Google Pay PSP decryption. The encrypted payload still moves through your systems, so keep logging and access controls on those paths in scope for review.

With merchant decryption, your own service decrypts the wallet payload before the request reaches Hyperswitch. This gives you the most direct control over key handling, but it also places the most responsibility on you: you build and run the decryption service, protect its keys, and carry the PCI DSS scope of that service and its hosting. The supplied Google Pay docs do not show merchant decryption, so confirm in the current docs whether it is offered for Google Pay before you plan that path. For the Apple Pay web domain flow, note that Hyperswitch decrypts the payload, and some processors, Stripe among them, must enable the feature for your merchant account before it works.

The web domain flow is the Apple Pay setup for payments made in a browser on your own sites, where Hyperswitch decrypts the Apple Pay payload. Before that works, your team must prove that each domain belongs to you. Host the domain verification file at the path /.well-known/apple-developer-merchantid-domain-association on every domain that will show Apple Pay, then verify that domain in the Hyperswitch Control Center. Build the list of domains and subdomains from your actual checkout hostnames before the work starts, because a hostname missed here will fail later in a way that is hard to trace. Confirm the exact file contents and any Apple-side steps against the current Apple Pay documentation and the Hyperswitch Apple Pay docs.

The file has to stay reachable after the first successful verification, because the check is only as durable as the path that serves it. Most breaks come from outside the application code: a deployment pipeline that clears or overwrites the static directory, an ingress or reverse proxy that rewrites or redirects the path into the app, an HTTP to HTTPS redirect handled differently at the edge, a CDN that caches a 404 or an outdated copy, a web application firewall or bot rule that blocks an unfamiliar path, and a certificate renewal that moves traffic to a new host or load balancer. Ship the file as a versioned asset in your deployment artifacts, exempt the path from redirects, authentication and bot rules, and purge CDN cache whenever it changes. Then add a synthetic check that requests the path from outside your network and alerts on any response other than the expected content.

The warning in the Hyperswitch Apple Pay docs changes the project plan. Because the web domain flow decrypts at Hyperswitch, some processors must enable the feature for the merchant account before it works, and the docs name Stripe among them. Enablement sits with the processor, so a successful Control Center verification does not make Apple Pay live for that processor on its own. Ask each processor you intend to use whether it supports the web domain flow with decryption at Hyperswitch, which identifiers it needs from you to enable the feature, and how its approval process is scheduled. Record the answer in writing and note which merchant account it covers, since one self-hosted deployment can serve several accounts.

Request that approval before go-live and treat it as a dependency on the critical path. Processor review runs on the processor's schedule, not on your release calendar, and a domain can verify in Control Center while transactions still fail for a processor that has not enabled the feature. Test with that processor's sandbox if it offers one, then confirm production enablement with a small live transaction once it is granted. Also decide with your payments and security leads which systems will see decrypted Apple Pay data in this model, because that decision shapes access controls, logging and compliance scope for the rest of the project.

Test every wallet path before go-live, and test each one with the decryption model you intend to run in production. Build the plan as a matrix with one row for each channel you enable: Apple Pay on the web, Apple Pay in an iOS app, and Google Pay in an app or on the web. Hyperswitch documents these channels with Hyperswitch decryption or processor decryption, so each row should name the model it uses. For each row, run a successful sandbox wallet payment through the processor you have chosen. A pass under one decryption model says little about another, because the token handling, the processor approvals involved and the error messages can all differ. Record the environment, processor, wallet, SDK version and Hyperswitch version against every result so the matrix can be repeated later.

Add two negative cases to every row. The first is a decline. Use the processor's documented test scenarios for declined outcomes if it offers them for wallet tokens, and confirm that the customer sees a clear message and that the attempt is recorded as failed rather than left pending. The second is a failed decryption. Provoke it deliberately, for example with a token that does not match the merchant configuration you are testing, so you can see which component reports the error and whether Control Center shows a usable reason. Check each trigger against your processor's documentation, because sandbox support for declines and decryption failures varies between connectors. Write down the exact error your checkout shows for each case so support teams can recognize it later.

For every successful and failed attempt, confirm the same transaction in three places: the payment record in Control Center, the matching transaction in the processor's sandbox dashboard, and the webhook events your system receives. Compare the amount, currency, status, payment method type and processor reference. Treat a status mismatch between Control Center and the processor as a reconciliation defect and block go-live until it is explained. For webhooks, check that your endpoint receives an event for each outcome, that signature verification passes on your side, and that a replayed event does not create a duplicate order or a second capture. Also record what happens when the endpoint is unavailable during a test, so your on-call team knows whether events are retried and how to recover a missed one.

Confirm which test environment supports wallet payments for your chosen processor before you set the schedule. Hyperswitch documents a hosted sandbox and a local Docker setup for testing, but support for wallet tests is not the same thing as support for every processor. Ask the processor and Hyperswitch whether Apple Pay and Google Pay test tokens run in each environment under the decryption model you plan to use, and whether the processor needs its own merchant enablement for test wallets. If one mode cannot be exercised in a given environment, plan a staging setup that matches your production configuration closely enough to run the same paths, and list the gap as a known limit of the test plan. Do not assume coverage that you have not run.

Repeat the full matrix after every Hyperswitch upgrade, every Control Center upgrade and every change to the SDK version in your apps, because any of these can change how a wallet token is passed, displayed or reported. Keep the matrix as a runbook with expected results and saved evidence so a second tester can run it and compare outcomes. Schedule the repeat as part of the upgrade change rather than as a later task, and decide in advance who signs off a failed row. Hyperswitch ships minor releases roughly monthly, and each release has a compatibility matrix for Control Center and web client versions. Read those notes before the change window to see whether any wallet-related component is affected, and set the scope of the repeat from that review.