Wallets & Click to Pay

This page covers the three “express” payment surfaces MVS Pay renders inside the embedded checkout: Apple Pay, Google Pay, and Click to Pay V2. All three ride on the same machinery — Hyperswitch’s HyperLoader.js Web SDK, loaded by @mvs/mvs-pay-ui, drawing the wallet/SRC tiles inside its <PaymentElement />. MVS Pay itself ships almost no wallet-specific code: the only first-party runtime surface is the Apple Pay domain-association route. The rest is configuration (certs, merchant IDs, connectors) that lives in Apple’s portal, Google’s console, Hyperswitch, and Infisical.

How the three surfaces fit together

All three are surfaced by the same embedded widget. The merchant’s server mints a clientSecret (Apple Pay / Google Pay) or, for the saved-method widget, an sdkAuthorization token; the browser hands it to HyperLoader; HyperLoader draws whichever tiles the active business profile’s connectors support.

The key consequence of this design: adding a wallet or Click to Pay almost never touches the SDK or the UI. You configure a connector and/or paste a secret, and the tile appears. The one exception is Apple Pay’s domain association, which requires MVS Pay to serve a file — covered below.

The HyperLoader bridge

@mvs/mvs-pay-ui loads Hyperswitch’s Web SDK and mounts its payment element. The relevant files:

loadHyperLoader injects a single shared <script id="mvs-pay-hyperloader"> tag, defaulting to https://beta.hyperswitch.io/v1/HyperLoader.js (DEFAULT_SCRIPT_SRC). It is idempotent — concurrent callers share one promise, and a rejected load nulls the cached promise so a transient script failure does not permanently break every widget on the page.

Google Pay: the one env var

Google Pay is the simplest of the three — no certificates. The merchant ID alone is enough. MvsPayCheckout accepts a googlePayMerchantId prop and composes it into the HyperLoader payment element’s wallets block:

1
// MvsPayCheckout.tsx — composedWallets (last wins):
2
//   1. walletReturnUrl   (from returnUrl prop)
3
//   2. googlePay.merchantId (from googlePayMerchantId prop)
4
//   3. caller-supplied wallets block (escape hatch)
5
const composedWallets = {
6
  ...(returnUrl ? { walletReturnUrl: returnUrl } : {}),
7
  ...(googlePayMerchantId ? { googlePay: { merchantId: googlePayMerchantId } } : {}),
8
  ...(callerWallets ?? {}),
9
};

The caller reads process.env.NEXT_PUBLIC_GOOGLE_PAY_MERCHANT_ID and passes it in. Without the merchant ID, Google Pay still renders in test mode, but production processing requires the value (documented in the prop’s JSDoc and in apps/mvs-pay/.env.example).

Apple Pay — provisioning model

Apple Pay is configured per Apple Developer Merchant ID, not per Hyperswitch merchant. One Merchant ID (merchant.com.mvscloud.<org_slug>) covers all of an MVS org’s profiles. Two distinct certificates are involved, and they do different jobs:

The critical security property: the Payment Processing Certificate’s CSR is generated inside Hyperswitch’s Control Center, so the matching private key never leaves Hyperswitch’s key vault. The operator never holds the key that decrypts payment tokens. The full step-by-step (CSRs, openssl invocation, Apple portal navigation, the “processed exclusively in China?” → No prompt) lives in the Wallet Validation runbook.

Certs are uploaded to Hyperswitch against the existing card MCA (Stripe, Cybersource, Adyen, …) — Apple Pay is not a separate connector, it rides on the card processor’s merchant_connector_id:

$
curl -X POST \
>
  "$HYPERSWITCH_BASE_URL/v1/account/$MERCHANT_ID/connectors/$MCA_ID/wallets/apple_pay/certs" \
>
  -H "api-key: $HYPERSWITCH_ADMIN_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "merchant_identity_cert": "...", "merchant_identity_key": "...",
>
        "payment_processing_cert": "...",
>
        "merchant_id": "merchant.com.mvscloud.<org_slug>",
>
        "domain_names": ["pay.mvscloud.com", "<embed-host-domain>"] }'

The response returns a domain-association token per domain in domain_names. That token is what MVS Pay has to serve back to Apple’s verifier.

The Apple Pay domain-association route

This is the single piece of first-party wallet runtime in MVS Pay. Apple requires that, for every domain on which the Apple Pay button is rendered, the server respond at the canonical path:

GET /.well-known/apple-developer-merchantid-domain-association
GET /.well-known/apple-developer-merchantid-domain-association?domain=partner.example.com

Source: apps/mvs-pay/app/.well-known/apple-developer-merchantid-domain-association/route.ts. It is a Node-runtime, force-dynamic route that resolves the token from an env var and returns it as text/plain.

Token resolution

Two resolution paths:

1. No domain param → use the environment-default key: APPLE_PAY_DOMAIN_ASSOCIATION_PROD in production (when NODE_ENV, INFISICAL_ENV, or VERCEL_ENV indicate prod), else APPLE_PAY_DOMAIN_ASSOCIATION_DEV.
2. ?domain=partner.example.com → look up a per-domain override at APPLE_PAY_DOMAIN_ASSOCIATION_<SLUG>. On a miss it falls through to the default so embed-host deployments keep working when a new partner is added to Hyperswitch but their override hasn’t been pasted into Infisical yet.

The slug function is exported and worth pinning down exactly:

1
// route.ts — domainToEnvSlug
2
domain.trim().toUpperCase()
3
  .replace(/[^A-Z0-9]+/g, "_")   // any run of non-alphanumerics → one "_"
4
  .replace(/^_+|_+$/g, "");      // strip leading/trailing underscores

Responses

The 404 is intentional: Apple’s verifier reads 404 as a clean “not provisioned” signal rather than a half-broken integration, and no-store prevents a stale negative from being cached. HEAD mirrors GET’s status and headers with an empty body.

Infisical paths

See Secrets Management and the Secrets Rotation runbook for how these flow into the deployment.

End-to-end: provisioning Apple Pay for an org

$
curl -i https://pay.mvscloud.com/.well-known/apple-developer-merchantid-domain-association
$
# → 200 + the token

The full runbook — including the failure-mode triage (token mismatch, deploy lag, stale CDN) and the 25-month cert-rotation cadence — is the Wallet Validation runbook.

The www.mvspay.io re-verification requirement

The production checkout host is moving from pay.mvscloud.com to www.mvspay.io (see the deployment topology and Domain & DNS — www.mvspay.io; the cutover is also called out in the Architecture overview and the gap list on the Overview page).

Apple Pay domain association is bound to the exact host. A domain change is not transparent — it triggers a full re-provision on the Apple side:

Google Pay is also domain-scoped: the Google Pay & Wallet Console integration is registered per domain, so www.mvspay.io needs to be added there too. The merchant ID itself is reused (it does not change), so this is a console-side domain addition rather than a re-issue.

Click to Pay V2 does not require domain re-verification — it is gated on the connector being active on the profile, not on a .well-known file, so it survives the host cutover unchanged.

Click to Pay V2

Click to Pay V2 implements the EMV Secure Remote Commerce (SRC) standard. Hyperswitch v1.123.1 ships it as two connectors:

No new SDK component is needed

This is the central point: Click to Pay requires zero MVS code changes. HyperLoader’s <PaymentElement /> — the same one mounted by <MvsPayCheckout /> — automatically surfaces a “Click to Pay” tile when a CTP connector is active on the checkout’s business profile. There is no MvsPayClickToPay component, no prop, no env var. You add the connector; the tile appears.

Provisioning via the connector wizard

Click to Pay is added through the same connector wizard as any other connector, driven at /connectors/new. The full steps (creds pre-flight, forced card / credit + debit payment methods, routing append, $0 auth smoke test, the MerchantConnectorExtension sidecar row) are in the Connector Onboarding runbook §3.

Routing interaction

Click to Pay does not bypass routing. The CTP MCA is just another merchant_connector_id in the active routing rule:

• To pin CTP-only flows (e.g. for the E2E test), set algorithm.type = "single" with the CTP connector.
• To make CTP optional alongside a primary acquirer (the typical setup), keep the priority list with CTP as a fallback entry.

See Routing & Smart Retries for the routing model.

What’s actually tested

Verification checklist

The full verification matrix (commands + pass criteria) is in the Wallet Validation runbook §10. The essentials:

Honest gaps

• No org is provisioned. Per-org Apple Pay merchant certs are explicitly in the “NONE done” bucket of docs/HANDOFF.md §6d. The code is ready; the live Apple Developer accounts, certs, Google Pay integrations, and CTP credentials are not.
• Wallet validation has no automated coverage. The only automated test is the Click to Pay E2E, and it skips without sandbox creds. Apple Pay / Google Pay validation is manual against a real device/browser.
• The HyperLoader CDN is external. Wallet/CTP rendering depends on beta.hyperswitch.io/v1/HyperLoader.js unless scriptSrc is overridden. CSP must allow it (mvsPay profile in packages/shared/lib/security-headers.ts).
• The www.mvspay.io cutover is pending and re-verification is manual. There is no automation that re-uploads certs / re-registers domains on the host change — it is a runbook step that must be done by hand at cutover, and Apple Pay is unavailable on the new host until it completes.
• Cert rotation is a calendar reminder. Apple Pay certs expire at 25 months; there is no automated expiry alerting wired for the per-org certs yet — the runbook prescribes a manual reminder at month 24.

Related pages