Setup for Mobile Wallets
This section describes developer implementation for mobile wallets. For general information, see Mobile wallet support in the Choose a Card Strategy guide.
Initial setup
Each card network has its own service for mobile wallets:
- Mastercard Digital Enablement Services (MDES)
- Visa Digital Enablement Program (VDEP)
This is the contact information for each wallet provider to obtain their documentation and SDK:
- Apple Pay — Send an email to
[email protected]
- Google Pay — Go to the Google Pay developer portal
- Samsung Pay — Go to the Samsung Pay developer portal
Galileo will provide you with the full list of items to provide to Galileo and actions to perform before Galileo sends all of the information to the card network for processing. Below are some of the important setup items.
Manual provisioning
As a first step, you must set up manual provisioning for mobile wallets in general. If you desire also to provide push-provisioning, you will perform additional steps, as described in Push provisioning.
Availability
Coming soon: Mobile wallet support for instant-issue cards.
- Ensure that there are contractual arrangements between the issuing bank, the wallet providers and card networks that are specific to mobile wallets.
- Provide these things to Galileo:
- Customer service number for yellow-path (partial success) verification, if Galileo is not handling yellow-path calls.
- BIN range to tokenize
- Terms and conditions documents as required by the networks and wallet providers, in TXT format.
- Network-specific metadata, as shown below
- Which mobile wallet events to set up
Mastercard metadata
For a Mastercard program you must provide these items to Galileo:
- BPMS (Business Process Management System) Guide — An Excel document that contains questions to answer for setup
- The card template — See Tokenized card design in Design a Card for specifications
- Your logo (1372 x 283 pixels) in PNG format
- Mobile notification elements:
- Smaller icon (100 x 100 pixels) in PNG format. Should be the primary brand associated with the card
- A short card description (max 32 characters)
Visa metadata
For a Visa program you must provide these items to Galileo:
- The card template — See Tokenized card design in Design a Card for specifications
- Mobile notification elements:
- Smaller icon (100 x 100 pixels) in PNG format. Should be the primary brand associated with the card
- A short card description (max 32 characters)
- Contact information to put on the back of the card:
- Contact name
- Customer service phone number
- Email address
- Contact website
Manual provisioning workflow
The manual provisioning process involves these entities:
- The cardholder's mobile wallet
- The card network
- The mobile wallet provider
- Galileo (or you, if you are using the Auth API)
This is the workflow when cardholders provision their cards manually:
- The cardholder obtains a card from you.
- The cardholder manually inputs the PAN, CVV, and expiry in the mobile wallet interface, as well as other identifying information that the wallet requests.
- The wallet provider performs some initial checks. If the checks do not pass, the wallet provider informs the cardholder that the provisioning has failed.
- If the initial checks pass, the wallet provider sends an authorization request to the card network. The request contains a one-time password (OTP), depending on how your program is set up.
- The card network forwards the authorization request to Galileo.
- Galileo performs the following checks. If any of these checks fail, Galileo returns response code
46
(Visa) or05
(all other networks):- CVV2 verification
- Card or account in wrong status
- Card not instant issue
- Galileo performs further checks. If any of these checks fail, Galileo returns response code
85
along with either the cardholder's mobile number or email or a customer service number, depending on your setup.- AVS for address and zip
- Last 4 digits of mobile
- If all checks pass Galileo returns response code
00
along with the AVS result. - Based on Galileo's response and its own algorithms, the wallet provider determines whether the provisioning attempt should be on the red, yellow, or green path.
- Red path means hard fail. The wallet provider presents a message to the cardholder, depending on how you are set up with the network. The message may tell the cardholder to contact the card issuer or it may contain a customer-service number to call.
- Yellow path means partial verification success. The wallet provider may send an OTP by the method that you have set up (email or text), or it may send a customer-service number.
- If the additional verification is not successful, the provisioning attempt fails.
- If the additional verification is successful, the provisioning request moves onto the green path.
- Green path means that all verification checks are passed. The provider forwards the provisioning request to the card network.
- The network creates the card token and sends it to the wallet provider.
- The wallet provider activates the token to provision the card to the wallet.
Push provisioning
If you will be push-provisioning cards to mobile wallets, you must perform all of the steps in the manual provisioning section, and then you must obtain the SDKs and in-app provisioning documentation from each wallet provider.
Push provisioning workflow
The push-provisioning process involves these entities:
- The cardholder's mobile wallet
- The card network
- The mobile wallet provider
- Your mobile app interface
- Galileo (and you, if you are using the Auth API)
This is the workflow when you push-provision cards to mobile wallets:
- The cardholder requests a tokenized card in your mobile app.
- You send a provisioning request to the mobile wallet provider.
- The wallet provider returns certificates, keys, and other data.
- You send a Create Provisioning Request call to Galileo with the data supplied by the wallet provider. Follow the instructions in the Creating a Provisioning Request guide.
- Galileo encrypts the payload and returns the response to you.
- You create a tokenization request with the encrypted payload and send it to the wallet provider via its SDK.
- The wallet provider decrypts the payload and verifies whether the tokenization request is valid.
- Because the cardholder's identity has already been verified in your app, there are no red, yellow, or green-path checks. All provisioning attempts are by-definition on the green path.
- The card network creates the card token and sends it to the wallet provider.
- The wallet provider activates the token to provision the card to the wallet.
Enhanced provisioning security
Galileo offers additional security measures to help prevent provisioning abuses, such as provisioning a zero-balance card to a wallet and using it for transit fare—taking advantage of the delay in authorizations—and then reprovisioning the card later and repeating the fraud.
These new security measures can deny provisioning requests that exceed limitations on deleting and reprovisioning during a specified period. Other rules that you can enable will leverage information from the card network about the wallet, suspicious transactions, and device risk scores. Many of these rules are based on the information in the tar_info
object in the Auth API message.
These enhanced rules are fully configurable. You can choose from among various rules to enable that will send the provisioning request along either the red or yellow path, which can help reduce provisioning abuses and fraud.
See Enhanced Provisioning Rules for your options.
Reissuing and replacing tokenized cards
When you reissue or replace a card that has been provisioned to a mobile wallet, the card in the wallet may not be automatically updated. For example, a cardholder provisions a physical card to a mobile wallet. Later, the card expires, the cardholder receives a new card (with new CVV and expiry date) in the mail, and activates it. Because the card in the wallet has the old CVV and expiry, it cannot be used for transactions until the card network updates the information for tokenized cards, which may be several hours or a day later.
When you replace a Digital First card that has been provisioned to a mobile wallet, the digital card in the mobile wallet is not automatically replaced—you must either push-provision the new card to the wallet or the cardholder must enter it manually.
Viewing mobile-wallet transactions
To distinguish mobile-wallet transactions from other transactions, the token_type
field in the Auth API and token_requester_id
field in Authorization Events are populated for mobile-wallet transactions. For example, token_type: PayPal
and token_requestor_id: 400100xxxxx
.
Events API messages
You can make arrangements with Galileo to receive these mobile wallet–related Account Events messages, which you can then relay to your customers. For these events you can arrange with Galileo to customize the message that is displayed to the cardholder, provided that you are doing the messaging instead of Galileo.
The first letter of the message code indicates the wallet provider:
- A — Apple Pay
- G — Google Pay
- S — Samsung Pay
Codes | Name | Description |
---|---|---|
ATCN GTCN STCN | mobile_activation TCN | A card was successfully provisioned to a mobile wallet. |
AYLP GYLP SYLP | mobile_activation YLP | An attempt to provision a card to a mobile wallet was unsuccessful and entered the yellow path. |
AACN GACN SACN | mobile_activation ACN | Mastercard sent an activation code after an activation attempt entered the yellow path. |
VAPI | mobile_activation API | Visa sent an activation code after an activation attempt entered the yellow path. The message code is VAPI for all wallet providers. |
ATVN GTVN STVN | mobile_activation TVN | Mastercard only. An activation attempt using the mobile activation code was unsuccessful. |
ARDP GRDP SRDP | mobile_activation RDP | An attempt to provision a card to a mobile wallet has failed and entered the red path. |
TKUP | token_update | Mastercard only. A tokenized card was frozen, unfrozen, reissued, or cancelled, and the updated tokens have been synchronized with Mastercard. |
Galileo setup
These internal parameters are set at Galileo according to your use case.
Parameter | Level | Description |
---|---|---|
APPAY | Program Product | Required. When this parameter is set, the provisioning request is approved with response code 00 (green path) only if the following conditions are true: Account is active and contains sufficient funds, AVS check matches ZIP and address, Last 4 digits of phone number match, Is not an instant-issue card, CVV2 is present and matches |
CHITR | Product | Set for Digital First cards to be provisioned to wallets. |
IPCID | Product | Mastercard only. Specifies the product configuration ID to be used for activation code distribution (ACN) methods for mobile wallet authorization. When this parameter is not set, Mastercard mobile wallet transactions are declined with response code 05 (do not honor). |
PPBBI | Product | Visa only. Required. Specifies which encryption key was used to encrypt provisioning data when performing a key exchange with Visa. This parameter should be set only after the key exchange has taken place. Set this parameter on the product that is to be tokenized. |
PPN | Program | Visa only. Contains the number that Visa cardholders can call to perform manual provisioning to a mobile wallet when a failed provisioning attempt is on the yellow path and Galileo is not providing yellow-path customer service. |
PPUPC | Product | Tokenize this card. Required for any product with a card that is to be tokenized. |
TOKUP | Product | Mastercard only. Controls whether Galileo synchronizes tokens with MDES when cards are frozen, unfrozen, reissued, or canceled. This parameter must be enabled to trigger the TKUP event. |
XAACT | Product | Set this parameter to YNN to automatically activate the account and card upon creation. |
Updated 16 days ago