--- name: bt-wallets description: Accept Apple Pay, Google Pay, and wallet payments. license: MIT metadata: tier: standard last_verified: '2026-09-25' --- # Apple Pay and Google Pay ## What Basis Theory does in a wallet flow Fact: Basis Theory decrypts wallet payment tokens and turns them into vault tokens you can process through any PSP — keeping the decrypted DPAN/cryptogram out of your systems (Apple Pay: https://developers.basistheory.com/docs/guides/apple-pay/overview, API: https://developers.basistheory.com/docs/api/apple-pay/api; Google Pay: https://developers.basistheory.com/docs/guides/google-pay/accept-payments, API: https://developers.basistheory.com/docs/api/google-pay/api). The value is the same portability story as cards: wallet acceptance that is not welded to one PSP's SDK. ## Apple Pay: managed vs BYOK — the decision - **Managed** (https://developers.basistheory.com/docs/guides/apple-pay/setup-managed): Basis Theory operates the Apple Pay merchant infrastructure (certificates, decryption). Fastest path; right when the customer has no existing Apple Pay merchant setup and wants acceptance, not certificate operations. - **BYOK / bring your own** (https://developers.basistheory.com/docs/guides/apple-pay/setup-byok): the customer keeps their own Apple merchant identity and keys; Basis Theory decrypts with keys the customer controls. Right when Apple Pay already exists in-house, when the merchant-of-record relationship requires it, or when key custody is a compliance requirement. - **Web-domain scale** (https://developers.basistheory.com/docs/guides/apple-pay/overview): managed setup has a 99-domain limit per tenant; BYOK has no Basis Theory domain limit. In BYOK, the customer verifies domains with Apple under its own merchant identifiers, can register multiple identifiers with Basis Theory, and selects one per request with `merchant_registration_id` (https://developers.basistheory.com/docs/guides/apple-pay/setup-byok; https://developers.basistheory.com/docs/api/apple-pay/api). Do not claim Apple has no limits of its own or change tenant topology solely to work around managed setup. Implementation pattern: the deciding question is almost always "who owns the Apple merchant relationship today, and who should own it in two years?" — not a technical capability difference. Surface that question before recommending. Acceptance flow and frontend wiring: https://developers.basistheory.com/docs/guides/apple-pay/accept, implementation detail: https://developers.basistheory.com/docs/guides/apple-pay/implementation. ## Google Pay - Accept payments with Basis Theory handling token decryption: https://developers.basistheory.com/docs/guides/google-pay/accept-payments. - Use your own encryption keys (customer-held key custody): https://developers.basistheory.com/docs/guides/google-pay/own-encryption-keys. ## Existing-code mode 1. Confirm platform surface (web Payment Request, iOS PassKit, Android) and which PSP will process the wallet token. 2. Frontend: standard Apple/Google wallet button flows produce an encrypted payment token; send it to Basis Theory per the accept guides — the customer's servers never see the decrypted payload. 3. Backend: process the resulting token through the PSP. Wallet tokens are network-token-shaped at the PSP boundary (DPAN + cryptogram) — the `network_token` source-type mapping in `bt-payments` shows per-PSP field placement; verify the PSP's wallet-specific fields against its current docs. 4. Sandbox reality (implementation pattern): Apple Pay and Google Pay sandbox testing requires platform-side setup (test devices/accounts, domain verification). Budget setup time; it is usually the slowest step, not the code. 5. Tests: decryption path (sandbox wallet token → Basis Theory token), PSP authorize with wallet-sourced fields, and graceful fallback when the wallet is unavailable. ## Two gotchas that repeat - **DPAN metadata ≠ original card metadata.** Fact (verified 2026-07-22, https://developers.basistheory.com/docs/api/apple-pay/api): the `bin` and `last4` on a decrypted wallet token are derived from the DPAN/MPAN — the network token issued by the wallet — not the original physical card (FPAN), which never reaches Basis Theory. Implementation pattern: teams building matching, display, or dispute workflows on "the card's last4" get wrong answers. Say explicitly which identifier a workflow needs, and source original-card display metadata from the wallet payload context where the platform provides it — verify specifics against the current wallet docs. - **Cryptogram lifecycle.** Fact (same page): the wallet cryptogram (`threeds_cryptogram`) is a single-use, transaction-specific value. Implementation pattern: if the flow passes wallet auth data onward, charge promptly after tokenization — don't park a cryptogram-bearing payload behind a queue or a later batch, or the authorization will fail when it finally runs. In proxy detokenization of a Google Pay DPAN token, the cryptogram and ECI live at `$.authentication.threeds_cryptogram` and `$.authentication.eci_indicator`, not under `$.data` (verified 2026-09-25, https://developers.basistheory.com/docs/guides/google-pay/accept-payments). ## Out of scope — push provisioning (say this plainly) Adding _issued_ cards into Apple or Google wallets (push provisioning) is **not covered by current public Basis Theory docs** — there are no public docs pages for it, and these skills does not improvise one. The honest answer is: acceptance (above) is fully supported; for wallet provisioning of issued cards, check current Basis Theory docs or contact Basis Theory (https://basistheory.com/contact) before building against assumptions. Card issuing display/PIN flows are covered by `bt-issuing`. ## Basis Theory implementation guidance When the answer needs implementation judgment beyond public docs, load only the relevant slices below from [../\_shared/references/implementation-guidance/README.md](../_shared/references/implementation-guidance/README.md). Treat these as implementation patterns, not canonical product behavior; keep public docs as the source of truth and label the guidance as **Implementation pattern** or **Assumption** unless docs prove it. - `../_shared/references/implementation-guidance/wallets/` ## Working conventions (shared by all Basis Theory skills) - Public Basis Theory docs are the source of truth for product behavior. Link the specific docs page behind any product claim; if a skill and the docs disagree, follow the docs. - Keep customer ownership clear: customers own PSP accounts, credentials, compliance decisions, production rollout, and application code. Skills can guide plans, bounded changes, and examples; they do not certify production readiness. - Never request, echo, store, or commit real credentials. Use placeholders such as `` and prefer sandbox or synthetic data for examples. - If a live-looking credential, live cardholder data, or production secret appears, stop mutation work, tell the user exactly where it appeared, and require rotation/revocation before continuing. - Default to test tenants and PSP sandboxes. Do not run or recommend production charges, refunds, card reveals, credential migrations, or data moves unless the user explicitly asks and the plan names safeguards, rollback, and customer approval. - Treat vague planning, audit, review, and “should we” prompts as read-only unless the user explicitly asks for a bounded implementation change. - Before changing product code, map the existing checkout/data flow, credential-bearing paths, persistence, retries, refunds, webhooks, logs, and rollback expectations. - End with an honest final report: done, assumed, remaining, proof run, unverified live behavior, rollback, and go-live items.