Primary + companion mobile app

This page covers the primary + companion mobile app certification path: your existing app remains the primary issuer experience, while a deep-linked companion app provided by Weavr handles in-app provisioningIn-app provisioning The flow that adds a card to a digital wallet (Apple Pay, Google Pay) from inside an issuer's mobile app, using the issuer's own authentication. In Weavr's stack, in-app provisioning is implemented via our Push Provisioning SDK on iOS or React Native. to Apple Wallet.

Information still being gathered

We have outstanding questions with Apple on a small number of points in this path. We update this page as Apple confirms its position. Speak to our support team for the latest position before committing to this route.

When this path applies

Choose this path when:

• Your end-users perform Card Lifecycle ManagementCard Lifecycle Management The set of in-app card operations Apple and Mastercard expect an issuer app to surface so cardholders can self-serve without leaving the app. Typical operations: view card number / CVV / PIN, lock and unlock, freeze and unfreeze, replace, report lost or stolen, view balance, and view transactions. Issuer apps that omit any of these are flagged at lab certification. on your primary mobile app.
• In-app provisioningIn-app provisioning The flow that adds a card to a digital wallet (Apple Pay, Google Pay) from inside an issuer's mobile app, using the issuer's own authentication. In Weavr's stack, in-app provisioning is implemented via our Push Provisioning SDK on iOS or React Native. to Apple Wallet happens on a separate, deep-linked companion app provided by us.

It is the right fallback when you want to minimize the development you take on inside your primary mobile app while still giving cardholders an in-app provisioningIn-app provisioning The flow that adds a card to a digital wallet (Apple Pay, Google Pay) from inside an issuer's mobile app, using the issuer's own authentication. In Weavr's stack, in-app provisioning is implemented via our Push Provisioning SDK on iOS or React Native. experience.

Constraints to be aware of

• Both apps must be deep-linked. A web-only entry point does not satisfy Apple in this path.
• The companion app cannot be initiated from the web alone; the primary app must be the launchpad for provisioning.
• You must obtain Apple's approval before integrating Apple Pay functionality (such as in-app provisioningIn-app provisioning The flow that adds a card to a digital wallet (Apple Pay, Google Pay) from inside an issuer's mobile app, using the issuer's own authentication. In Weavr's stack, in-app provisioning is implemented via our Push Provisioning SDK on iOS or React Native.) into any app that is not your primary card-issuer appIssuer app Apple's term for the mobile app that authenticates a cardholder and provisions their card to Apple Wallet. Apple's certification, brand, and Card Lifecycle Management requirements apply specifically to this app. In a primary + companion architecture, your primary app remains the issuer app even if the provisioning step happens in a companion app..

Apple's requirement for linking apps

Per Apple's functional requirements for issuer appsIssuer app Apple's term for the mobile app that authenticates a cardholder and provisions their card to Apple Wallet. Apple's certification, brand, and Card Lifecycle Management requirements apply specifically to this app. In a primary + companion architecture, your primary app remains the issuer app even if the provisioning step happens in a companion app.:

Card Issuers must have approval from Apple before integrating Apple Pay functionality (such as In-App ProvisioningIn-app provisioning The flow that adds a card to a digital wallet (Apple Pay, Google Pay) from inside an issuer's mobile app, using the issuer's own authentication. In Weavr's stack, in-app provisioning is implemented via our Push Provisioning SDK on iOS or React Native.) within a mobile app that is not the primary Card Issuer Mobile App.

In that case, Card Issuers must include a deep link between the primary Card Issuer Mobile App and the app offering Apple Pay In-App ProvisioningIn-app provisioning The flow that adds a card to a digital wallet (Apple Pay, Google Pay) from inside an issuer's mobile app, using the issuer's own authentication. In Weavr's stack, in-app provisioning is implemented via our Push Provisioning SDK on iOS or React Native. functionality (e.g., landing page, banner, or dedicated home page space).

• Apple, FR 3.5 – Req 4.2

In practice, this means:

1. Engage our support team early so we can prepare the Apple approval request alongside you.
2. Plan the deep link from your primary app to the companion app before lab certificationLab certification The formal test pass run by an Apple-affiliated test centre that verifies an issuer app meets Apple Pay's functional, security, and brand requirements. The test exercises every Card Lifecycle Management operation, the in-app provisioning flow, and the Wallet Extension. A successful pass is required before launching Apple Pay on a card programme; most first-time integrations fail at least one item and need a remediation round., not after.

Requirements for your primary mobile app

Use this checklist when scoping the work on your primary app. Tick items off as you complete them - your progress is saved in this browser.

• Strong password authentication available to all cardholders
• Biometric authentication enrolled and used after first login
• Complete card lifecycle management surfaced in-app (view PIN, lock/unlock, replace, freeze, report lost/stolen, view balance, view transactions)
• Apple-defined UX and controls such as a splash screen, correct branding, and 'Add to Apple Wallet' button per Apple's brand guidelines
• Deep link from the primary app to the Weavr companion app (banner, landing page, or dedicated home-page space)
• Apple approval obtained for routing Apple Pay provisioning to a non-primary app

Strong cardholder authentication

Apple requires Strong cardholder authenticationStrong cardholder authentication Apple Pay's requirement that a cardholder authenticate with at least two factors - typically a knowledge factor (password) plus an inherence factor (biometrics on a trusted device) - before adding a card to Apple Wallet or accessing sensitive card details. The principle aligns with PSD2 SCA but applies specifically to issuer-app interactions Apple inspects during certification. - a password (knowledge factor) plus biometrics (inherence factor) - before cardholders can manage cards. Our biometrics SDK - for iOS native and React Native - implements the recommended pattern: password on first login via our secure Password component, biometrics for subsequent sessions. The requirement applies the same way regardless of which SDK you use.

warning

Passcode is deprecated for biometric login flows. Use a password as the primary credential.

Card Lifecycle Management

"Complete" Card Lifecycle ManagementCard Lifecycle Management The set of in-app card operations Apple and Mastercard expect an issuer app to surface so cardholders can self-serve without leaving the app. Typical operations: view card number / CVV / PIN, lock and unlock, freeze and unfreeze, replace, report lost or stolen, view balance, and view transactions. Issuer apps that omit any of these are flagged at lab certification. means a cardholder can perform every operation Apple expects without leaving your primary app. At a minimum, surface:

• View card details (PANPAN Primary Account Number - the long card number (typically 16 digits) printed or embossed on a payment card and used to identify the card on the payment network. Weavr never returns the raw PAN to your client; `GET /managed_cards/{id}` returns the PAN in tokenized form as `cardNumber`, and the value is only detokenized inside a Secure UI card-number component (a sandboxed iframe on the web, a secure native view on mobile)., CVVCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component., expiry) using our card components - iOS native or React Native.
• Lock and unlock the card.
• Freeze and unfreeze the card.
• Replace the card (where the product allows it).
• Report the card as lost or stolen.
• View balance and transactions.

If any of these are not in your app, Apple flags the integration during lab certificationLab certification The formal test pass run by an Apple-affiliated test centre that verifies an issuer app meets Apple Pay's functional, security, and brand requirements. The test exercises every Card Lifecycle Management operation, the in-app provisioning flow, and the Wallet Extension. A successful pass is required before launching Apple Pay on a card programme; most first-time integrations fail at least one item and need a remediation round..

Mapping requirements to Weavr building blocks

Each Apple requirement on your primary app maps to a specific Weavr SDK component, secure UI component, or Weavr API endpoint.

Apple requirement	Weavr building block
Password authentication (knowledge factor)	Password secure UI component - web, iOS login components, React Native login components
Biometric authentication (inherence factor)	Biometrics SDK - iOS, React Native
View card number, CVVCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component., expiry	Card components - iOS, React Native, web
View PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component.	Show Card PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. component - iOS, React Native, web
Lock / unlock card	Weavr API: POST /managed_cards/{id}/block and POST /managed_cards/{id}/unblock
Replace card (lost / stolen / damaged)	Weavr API: POST /managed_cards/{id}/physical/replace_lost_stolen and POST /managed_cards/{id}/physical/replace_damaged - see replace a card
Report card lost or stolen	Weavr API: POST /managed_cards/{id}/physical/report_lost and POST /managed_cards/{id}/physical/report_stolen - see report a card
View balance	Weavr API: GET /managed_cards/{id} (balance is returned in the card resource)
View transactions	Weavr API: transaction list endpoints - see Transactions
Deep link to the companion app	Implemented in your primary app - see the deep-link section below

Deep link

Add a deep link from your primary app to the companion app. Apple's wording allows for several placements; choose what fits your UX:

• A banner on the home or cards screen.
• A landing page describing Apple Pay.
• Dedicated home-page space for the "Add to Apple Wallet" entry point.

The link must clearly communicate to the user that they are leaving your primary app and entering the Weavr companion app to add the card to Apple Wallet.

note

Implementation guidance for the deep link itself (universal links, App Links, custom schemes) is not yet documented here. Contact our support team for the recommended pattern.

Requirements for the Weavr companion app

The companion app is provided and operated by Weavr, but a few items depend on us coordinating with you. Use this checklist to track that coordination.

• Push provisioning integrated in the companion app (handled by Weavr)
• Apple Wallet extensions (UI and Non-UI) implemented and configured
• Apple-defined UX and controls such as a splash screen and correct branding in the companion app
• Bundle identifiers shared with Weavr support for allow-listing
• Deep link target verified end-to-end with the primary app

Mapping companion-app requirements to Weavr building blocks

Apple requirement	Weavr building block
In-app provisioningIn-app provisioning The flow that adds a card to a digital wallet (Apple Pay, Google Pay) from inside an issuer's mobile app, using the issuer's own authentication. In Weavr's stack, in-app provisioning is implemented via our Push Provisioning SDK on iOS or React Native. from the companion app	Push ProvisioningPush Provisioning A method that allows cardholders to add their card to a digital wallet (such as Apple Pay or Google Pay) directly from your app. The card details are securely tokenized and sent to the wallet provider, streamlining the process and enhancing the user experience compared to manual provisioning. This feature is currently in beta. SDK - iOS, React Native (handled by Weavr)
Wallet ExtensionWallet Extension An iOS app extension that integrates an issuer app with Apple Wallet. The UI Wallet Extension provisions a card from the issuer app into Wallet (the in-app provisioning flow). The Non-UI Wallet Extension exposes the issuer's card-management actions (such as 'View card details') from inside Wallet itself. Apple requires both for a primary issuer-app integration. (UI + Non-UI)	Apple Wallet extension guide (handled by Weavr; React Native wires the same extensions at the native iOS layer)
Card status surfaced in Wallet	Card status for iOS, Card status for React Native (handled by Weavr)

For the technical detail behind these items, see:

iOS native:

• Push provisioning overview
• Apple Wallet extension
• Card status

React Native:

• Push provisioning overview
• Push provisioning setup (covers Wallet ExtensionWallet Extension An iOS app extension that integrates an issuer app with Apple Wallet. The UI Wallet Extension provisions a card from the issuer app into Wallet (the in-app provisioning flow). The Non-UI Wallet Extension exposes the issuer's card-management actions (such as 'View card details') from inside Wallet itself. Apple requires both for a primary issuer-app integration. wiring at the native iOS layer)
• Card status

Solution mapping

Weavr solution	Companion mobile app with embedded push provisioningPush Provisioning A method that allows cardholders to add their card to a digital wallet (such as Apple Pay or Google Pay) directly from your app. The card details are securely tokenized and sent to the wallet provider, streamlining the process and enhancing the user experience compared to manual provisioning. This feature is currently in beta.
Enables	Primary + companion app certification
Provides	Push provisioningPush Provisioning A method that allows cardholders to add their card to a digital wallet (such as Apple Pay or Google Pay) directly from your app. The card details are securely tokenized and sent to the wallet provider, streamlining the process and enhancing the user experience compared to manual provisioning. This feature is currently in beta. on the companion app
Constraints	Both apps must be deep-linked; this path cannot support web-only initiation
Use case	Fallback when you want to minimize development on your primary mobile app

Next steps

1. Confirm with our support team that this path is the right fit.
2. Work the primary-app checklist into your roadmap.
3. Coordinate Apple approval and bundle-identifier allow-listing with us before lab certificationLab certification The formal test pass run by an Apple-affiliated test centre that verifies an issuer app meets Apple Pay's functional, security, and brand requirements. The test exercises every Card Lifecycle Management operation, the in-app provisioning flow, and the Wallet Extension. A successful pass is required before launching Apple Pay on a card programme; most first-time integrations fail at least one item and need a remediation round..
4. Walk through the integration during a pre-cert review with our team.