Apple Pay, Google Pay, and Samsung Pay wallets (collectively colloquially known as the "xPays") allow users to tokenize a card. Such a token held within an xPay wallet may subsequently be used to make payments online and by contactless tap in-store.
To tokenize a card within an xPay wallet, a card must first be issued to a cardholder. Follow the Issue a Virtual Card or Issue a Physical Card guide for more information on how to create and issue a card.
Whereas the card itself holds a primary account number (PAN) which is usually depicted on the card, a device PAN (DPAN) is assigned to the card as a pseudonym during tokenization. A DPAN is associated with a particular device (such as a smartphone) that emulates the card virtually when stored in the xPay wallet. If the same card is stored virtually in another wallet it will have DPAN which differs from the one held by the other wallet. Immersve assigns a DPAN at the time of adding the virtual card to the xPay wallet.
The complexity of managing DPANs is opaque to the cardholder and the process to provision a card to an xPay wallet is rather simple from their perspective.
Apple Pay In-App Provisioning
When your application runs on an iOS device, you can add the card directly from within your app using Apple's PassKit push provisioning. The cardholder taps an "Add to Apple Wallet" button in your app and Apple Pay handles the rest — they do not need to leave your app to enter card details into the Wallet app. The same flow can provision the card to a paired Apple Watch.
This requires entitlement from Apple for in-app provisioning. See Apple's Wallet Developer Guide for details on requesting the entitlement and integrating PKAddPaymentPassViewController.
The flow is:
- Present a
PKAddPaymentPassViewControllerfrom your app, configured with aPKAddPaymentPassRequestConfigurationwhoseprimaryAccountIdentifieris set to theseriesIdfield of the card resource and whose cardholder name is set to the card'scardholderNamefield. - When PassKit invokes your delegate to request the provisioning payload, forward the
certChain,nonce, andnonceSignaturevalues it supplies to the Provision Card Apple Pay endpoint. - Pass the
encryptedPassData,ephemeralPublicKey, andactivationDatafields from the endpoint response back to the PassKit completion handler as the corresponding fields ofPKAddPaymentPassRequest.
PassKit then finalizes tokenization with Apple and the card becomes available in the cardholder's Apple Pay wallet.
Manual Provisioning for Other Wallets
In-app push provisioning for Google Pay and Samsung Pay will be supported soon. Until then, cardholders add the card to a Google Pay or Samsung Pay wallet manually.
Where your application (within which the virtual card is presented) is co-located with the xPay wallet then the user can simply copy/paste and/or manually enter the card details from your application into the xPay wallet. Where your application resides on a device other than the one that holds the target xPay wallet then the user can scan the virtual card with their camera to add it to their xPay wallet.
Manual provisioning is not permitted for Apple Pay under Immersve's agreement with Apple. Apple Pay must always be provisioned via the in-app flow above.
See the Google guide for more details on how manual provisioning operates from the user's perspective.
OTP Security Challenge
Whether the card is loaded manually or via in-app push provisioning, the network may require a one-time password (OTP) challenge before the token is activated. This is dynamic and driven by risk scoring on the card load, so the challenge is not always presented.
When a challenge is required, the xPay wallet prompts the cardholder to choose a delivery method (SMS or email). The available destinations come from the cardholder's contact details set via the Update Contact Details endpoint, so ensure a phone number and email address are recorded against the cardholder account before provisioning.
By default, Immersve delivers the OTP to the chosen destination. To deliver the OTP from your own sender instead, subscribe to the XPay Card Load OTP webhook. The webhook payload includes the verification code and the delivery option selected by the cardholder; your handler is responsible for sending the code to the cardholder and returning the delivery channel and destination it used.