Skip to main content

Mobile Wallet Loyalty Cards Setup

This guide explains how to configure Apple Wallet and Google Pay passes in Mercury.

Apple Wallet​

Apple Wallet passes (loyalty cards, coupons, etc.) are grouped under a Pass Type Identifier, a reverse-DNS string that identifies your organization and pass category (for example, com.mycompany.loyalty.tier1). Each individual pass is distinguished by a serialNumber, so the combination of passTypeIdentifier + serialNumber must be unique—adding the same pair will overwrite the existing pass on a user’s device.

Step 1: Create a Pass Type Identifier​

  1. Sign in to your Apple Developer account and navigate to Certificates, Identifiers & Profiles → Identifiers.

    Apple Certificates

  2. Click Add (+), select Pass Type ID, then click Continue.

    Pass Type ID

  3. Enter a descriptive name and your reverse-DNS identifier (e.g. com.yourcompany.loyalty.card), then register.

    Apple Certificates

Step 2: Create the Certificate (Windows)​

Install OpenSSL​

CSR files are generated using OpenSSL, which can be found here.

Download and run the most recent Light installer. The wizard will ask you to select where OpenSSL should be installed. Keep the default location. Additionally, when prompted, instruct the installer to copy OpenSSL's DLLs to The Windows system directory.

Generate a Certificate Signing Request​

CMD

  1. Open an administrator command prompt.
  2. Create a folder to place your CSR. cd to your cert folder: 
    cd C:\certificates\apple-pass
  3. Generate a private key: 
    set RANDFILE=.rnd
    openssl genrsa -out apple_pass.key 2048
  4. The file, apple_pass.key, will be output to the selected folder.
  5. Create a CSR (replace placeholders with your email and name) by running the following command: 
    openssl req -new ^
     -key apple_pass.key ^
     -out apple_pass.csr ^
     -subj "/[email protected],CN=Your Name,C=US"
  6. The CSR file, apple_pass.csr, will be output to the selected folder.

Create the Certificate​

  1. In the Apple portal under Pass Type ID → Certificates, choose to create a certificate

    Create Certificate

    of the type "Pass Type ID Certificate"

    Pass Type ID Certificate

  2. Upload newlly created CSR apple_pass.csr

    Upload CSR

  3. Download the resulting pass.cer file.

  4. Convert and bundle into PKCS#12:

    openssl x509 -in pass.cer -inform DER -out apple_pass.pem -outform PEM
    openssl pkcs12 -export ^
     -inkey apple_pass.key ^
     -in apple_pass.pem ^
     -out apple_pass.p12 ^
     -passout pass:<YOUR_P12_PASSWORD>

Step 3: Configure Mercury​

  1. In your Mercury admin console, go to Loyalty Programs and select the program you want to enable Apple Wallet for.

  2. Open the Apple Pass tab.

  3. Upload your apple_pass.p12 certificate.

  4. Fill in the following settings (replace placeholder values with your own):

    SettingValue / Notes
    Organization NameYour brand name as displayed on the pass
    Pass Type IdentifierThe reverse-DNS ID you registered (e.g. com.yourcompany.loyalty.card)
    Team IdentifierYour Apple Developer Team ID
    You can find your Team ID at https://developer.apple.com/account by clicking on the "Membership Details" icon.
    DescriptionBrief description of the loyalty program
    Logo TextAlt-text for the logo image
    Background ColorHex code for the card background (e.g. #FFFFFF)
    Label ColorHex code for field labels
    Foreground ColorHex code for field values
    Terms & ConditionsLink text and URL for your terms & conditions. In the Link field enter the entire <a href> HTML tag
    Apple WWDR CertificateApple’s intermediate (WWDR) certificate (download from Apple’s Certificate Authority).
    Select the first of the Worldwide Developer Relations certificates
    Apple Authentication TokenShared secret used to authenticate your pass-issuing API.
    Apple requests have an authentication header in the form of ApplePass XXXXXXXX
    For each loyalty program that generates Apple Wallet Passes provide a separate authentication token.
    info

    The URL of Apple requests is of the following format https://<YOUR_API_ROOT>/v1/passes/{passTypeIdentifier}/{serialNumber}
    You need setup the WebApiRootUrl Application Setting to the first part https://<YOUR_API_ROOT>.

  5. Provide required pass assets (filenames and exact dimensions):

    FilenameUseDimensions
    icon.pngDisplayed on lock screen and in Mail previews29 × 29
    [email protected]High-resolution lock-screen & mail preview58 × 58
    logo.pngDisplayed in top-left corner next to the logo text160 × 50
    [email protected]High-resolution logo320 × 100
    strip.pngBackground strip behind primary fields375 × 123
    [email protected]High-resolution strip750 × 246

Apple Pass Layout

For further information visit Apple Wallet Passes Documentation

  1. Click Save to apply your changes.

  2. Mercury will now generate .pkpass files at runtime and serve them via your API endpoint.

    Developer note

    Mercury generates Apple Wallet passes via the PassesHelper.GenerateApplePassForCard method, which produces a .pkpass package.

    To verify your pass, upload the generated file to the Pkpass Validator and confirm there are no errors.

Google Wallet​

To create Google Wallet passes you need Google Wallet API issuer account and a Google Cloud account. Google uses the concept of classes and objects. A loyalty class is a blueprint to create loyalty objects (the actual passes). You can create multiple loyalty classes, for example one for each loyalty tier.

Step 1: Setup prerequisites​

Follow the instructions on Google's onboarding guide (steps 2 & 3) to create a Google Wallet API Issuer account and Generate REST API credentials (requires a Google Cloud account).

Step 2: Configure Mercury​

Upload the .json service account key generated on the previous step to the Google Pass tab of your Loyalty Program in Mercury in the field ServiceAccount.

In your Application Settings, add or update the following keys to enable Google Wallet integration:

KeyValueNotes
GoogleWallet.ServiceAccountEmailAddress[email protected]The service account email from your Google Cloud JSON key.
GoogleWallet.ApplicationNameYour Loyalty Program NameA friendly name for your loyalty program (display only).
GoogleWallet.IssuerId<YOUR_ISSUER_ID>Your numeric Google Wallet Issuer ID.
To locate this go to Google Pay & Wallet Console select Business Profile from the menu and on the top bar you will see your merchant (issuer) ID
GoogleWallet.Originshttp://localhost, https://www.yourdomain.com, https://webapi.yourdomain.comA comma-separated list of allowed origin URLs that will serve the Wallet pass. Include your development, staging and production URLs.
VirtualFileRootWithDomainhttps://www.yourdomain.com/userfilesBase URL from which Google Wallet–related assets (images, logos, etc.) will be served.
tip

To preview your Google Wallet Pass design, try the Generic Pass Builder on Google Developers site.