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:

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.

  • 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:

  1. The cardholder obtains a card from you.
  2. The cardholder manually inputs the PAN, CVV, and expiry in the mobile wallet interface, as well as other identifying information that the wallet requests.
  3. The wallet provider performs some initial checks. If the checks do not pass, the wallet provider informs the cardholder that the provisioning has failed.
  4. 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.
  5. The card network forwards the authorization request to Galileo.
  6. Galileo performs the following checks. If any of these checks fail, Galileo returns response code 46 (Visa) or 05 (all other networks):
    • CVV2 verification
    • Card or account in wrong status
    • Card not instant issue
  7. 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
  8. If all checks pass Galileo returns response code 00 along with the AVS result.
  9. 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.
  10. The network creates the card token and sends it to the wallet provider.
  11. 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:

  1. The cardholder requests a tokenized card in your mobile app.
  2. You send a provisioning request to the mobile wallet provider.
  3. The wallet provider returns certificates, keys, and other data.
  4. 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.
  5. Galileo encrypts the payload and returns the response to you.
  6. You create a tokenization request with the encrypted payload and send it to the wallet provider via its SDK.
  7. The wallet provider decrypts the payload and verifies whether the tokenization request is valid.
  8. 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.
  9. The card network creates the card token and sends it to the wallet provider.
  10. The wallet provider activates the token to provision the card to the wallet.

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. These values can be added to your Authorized Transactions RDF by request.

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
CodesNameDescription
ATCN
GTCN
STCN
mobile_activation TCNA card was successfully provisioned to a mobile wallet.
AYLP
GYLP
SYLP
mobile_activation YLPAn attempt to provision a card to a mobile wallet was unsuccessful and entered the yellow path.
AACN
GACN
SACN
mobile_activation ACNMastercard sent an activation code after an activation attempt entered the yellow path.
VAPImobile_activation APIVisa 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 TVNMastercard only. An activation attempt using the mobile activation code was unsuccessful.
ARDP
GRDP
SRDP
mobile_activation RDPAn attempt to provision a card to a mobile wallet has failed and entered the red path.
TKUPtoken_updateMastercard 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.

ParameterLevelDescription
APPAYProgram
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
CHITRProductSet for Digital First cards to be provisioned to wallets.
IPCIDProductMastercard 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).
PPBBIProductVisa 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.
PPNProgramVisa 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.
PPUPCProductTokenize this card. Required for any product with a card that is to be tokenized.
TOKUPProductMastercard 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.
XAACTProductSet this parameter to YNN to automatically activate the account and card upon creation.