/
Mobile Pass Cards

Mobile Pass Cards

THE ESSENTIALS

A mobile pass card is a virtual card that a business issues to its registered contacts. Contacts add it to a mobile wallet application on their phone - Apple Wallet, Google Wallet, or a third‑party Wallet Passes app - where it identifies the contact to the business and shows their current available balance. The look and content of the card are fully configurable from the back end, so each business can align it with its own branding.

A mobile pass card is always issued to a registered contact of a business. It represents that contact's CRM.COM Wallet with that business and is their day‑to‑day instrument for being recognised and for spending wallet funds at the point of sale.

Who this manual is for - four roles

  • 🔧 Configurator - designs the mobile pass card, activates it, and links it to a registration landing page. Works in Settings > Platform > Contact Facing Essentials > Mobile Pass Cards.

  • 🖥️ Operator - supports contacts day‑to‑day and can view their wallet balances.

  • 📱 Contact - adds the card to Apple Wallet, Google Wallet or a Wallet Passes app, and uses it to be identified and to spend wallet funds at the point of sale.

  • 🔗 Integrator - a) can create a custom mobile pass card to replace the one provided by CRM.COM, b) submits contact’s purchases using the Create Purchase API from the point of sale (or alternatively the cashier can use Merchant App if no POS integration is available).

This manual explains the key concepts and how they map to the platform. For full integration guides, step‑by‑step flows, and code examples, refer to the Integrators Hub and the Self‑Service SDK documentation.

  • One mobile pass card per business. The card is tied to the contact's Wallet for that business and reflects its current balance.

  • Configurable & branded. A system user defines the card's content and colours from the back end but cannot change the fixed layout imposed by Apple and Google.

  • Distributed at registration. A card can be provisioned automatically when a contact registers through a linked Landing Page, and reissued through the portal if lost.

  • Three wallet targets. The same card can be added to Apple Wallet, Google Wallet, or a Wallet Passes app.

Target

Format

Design used

Target

Format

Design used

Apple Wallet

Signed .pkpass

Apple design

Wallet Passes (Android)

Signed .pkpass

Apple design

Google Wallet

Google loyalty pass

Google design

ℹ️ Wallet Passes is for Android apps that read the Apple .pkpass format, so it reuses the Apple design - there is no separate Android design to configure. The Google design applies only to the Google Wallet pass.

Key Concepts

Wallet

The mobile pass card represents the contact's Wallet. Awards from Reward Offers (for example, for registering or for purchases) and redeemed financial passes (e.g. gift cards) accumulate in the Wallet and can be used for subsequent purchases. Wallet funds may be subject to spending conditions, depending on the Reward Offer they originated from.

Balance

The balance on the card is the contact's live Wallet balance, formatted with the currency symbol. The card automatically stays in step with the Wallet (see Automatic Updates & Notifications). When automatic updates aren't possible on a platform, the contact can be notified to refresh the card manually.

Identification & Spending

The card lets a contact identify themselves and consume their Wallet during a purchase. A contact can be identified in three ways:

Method

How it works

Method

How it works

Barcode / QR code

The merchant scans the code on the front of the card.

OTP

The contact requests a one‑time password from the card and reads it out to the cashier.

Human‑readable code

The contact provides the wallet code shown on the card.

Once identified, the contact states the amount to draw from their Wallet. If the purchase is successfully posted, the balance adjusts, and the card reflects the new balance.

ℹ️ Submitting the actual Purchase Event requires the CRM.COM Merchant App or a third‑party POS integration - see Reference Material.

Landing Pages

Mobile pass cards can be linked to a registration Landing Page where cotnacts can register with the business by providing the minimum requird information. When Support Mobile Pass Cards is enabled on a Register landing page, a contact is automatically provisioned with a card as soon as they register. You must create and activate the mobile pass card configuration before creating the landing page.

Managing Mobile Pass Cards

Adding the Mobile Pass Card to a Phone 📱

From the contact app or self‑service portal, the contact opens the Mobile Pass Card screen and chooses how to add the card:

Option

Result

Option

Result

Add to Apple Wallet

Downloads the signed .pkpass and opens Apple Wallet.

Add to Wallet (Wallet Passes)

Downloads a PKPass for Android Wallet‑Passes apps.

Save to phone (Google Pay)

Redirects to the Google Pay save page to add the Google Wallet pass.

If no mobile pass card has been configured and activated for the business, the contact is informed that the pass is not available.

Automatic Updates & Notifications 🔗

Once a pass is added to a phone it registers for updates, and CRM.COM keeps it updated automatically:

  1. A change is detected via a platform event - a contact update, an account update, or a wallet / journal‑entry change (award, spend, adjustment, transfer).

  2. For every registered pass belonging to that contact, CRM.COM pushes an update to the relevant wallet:

    • Apple Wallet / Wallet Passes - a push notification prompts the device to fetch the latest signed pass.

    • Google Wallet - the pass object is updated, and a scheduled Google Wallet class‑update job applies design‑level changes.

  3. The device retrieves the refreshed pass, and the contact sees the new balance/details.

Where an automatic wallet update is not possible, the contact is notified to manually refresh their mobile pass card.

Reissuing a Lost Card 🖥️ 📱

If a contact loses access to their card, it can be reissued through the portal - the contact simply re‑adds it from the Mobile Pass Card screen. Because the pass always reflects the live Wallet, no balance is lost upon reissue.

Mobile Pass Card Settings 🖥️

Configure and design the mobile pass card from Settings > Platform > Contact Facing Essentials > Mobile Pass Cards.

A preconfigured mobile pass card is Inactive by default. Choose Edit Design from the options menu to configure it, then activate it so it can be issued.

ℹ️ Set up both the Apple and Google designs. They have different technical requirements and do not necessarily correlate - a field or layout available on one platform may differ on the other. A system user can define the content of each screen but cannot change the fixed format/arrangement.

The edit screen has three panes:

  • Left - navigation menu for the configuration areas.

  • Centre - the configuration itself (text, colours, images, field selection).

  • Right - a live preview of the Front and Back of the card, updating instantly as you edit.

Apple Design

Area

What to configure

Area

What to configure

Images

Upload the images shown on the card. Follow the size guidance for best results.

Colours

Choose colours for three distinct areas of the card.

First Row

Select one field for the top row.

Second Row

Select one field for the second row.

Third Row

Select up to three fields for the third row.

Back of Pass

Select any number of fields for the back - e.g. Wallet balance, full name, loyalty number, request an OTP, phone, a portal link, reward tier, external links.

Google Design

Area

What to configure

Area

What to configure

Card Information

Provide the Mobile Pass Card Name - a recognisable title so the card is easy to find in the wallet. Complete this before designing.

Images

Upload the images - follow the recommended sizes.

Colours

Set the card background colour.

First Section

Select up to two fields (Google manages alignment).

Second Section

Select up to three fields.

Back of Pass

Select any number of fields for the back - Request OTP, portal link, external links.

Links

Optionally add other links - e.g. a URL, phone, email, the portal URL, or the option to generate an OTP to the card.

Available Fields

Any of the following can be placed on the front rows/sections or on the back of the card:

Field

Shows

Field

Shows

Wallet Balance

Live Wallet balance, formatted with the currency symbol

Reward Tier

The contact's current reward tier name

Full Name

Contact's full name

Email

Contact's email address

Phone

Contact's primary phone number

Loyalty Identifier

Contact's loyalty identifier

Contact Code

Contact's code

Contact ID

Contact's unique ID

CRM.COM Wallet Code

The wallet code (recommended for identification)

Formatted Wallet Code

Wallet code grouped in blocks of four digits for readability

Request OTP

A link that generates a one‑time password to spend money from the wallet

Portal Link

A link to the contacts portal

Link 1 / Link 2 / Link 3

Up to three custom external links

NFC / Barcodes

Configure a barcode or QR code that can be scanned at the POS for identifying the contact.

  • Type - QR Code, PDF417, Aztec, or Code 128 (or None to omit the code).

  • Linked to Value - the unique identification information the code can represent:

    • CRM.COM Wallet Code (recommended, e.g. 5533381147044338)

    • Formatted CRM.COM Wallet Code (e.g. 5533 3811 4704 4338)

    • Contact code (e.g. 5777688604411885)

    • Contact identifier (e.g. 4d776c39-9790-42d6-bffa-e435a60f1813)

    • Contact Loylty Number (e.g. L1234567)

Good to Know

  • Set up both designs. Apple and Google differ in fields, layout and image sizes. A card issued for a platform whose design isn't configured won't look right.

  • Activate before linking. The Support Mobile Pass Cards option on a landing page only appears once a mobile pass card configuration exists and is activated.

  • Empty values show N/A. Any selected field that has no data for the contact renders as N/A.

  • Change messages (Apple). When a field value changes, Apple Wallet surfaces a "Your <field> has changed to …" message to the contact.

  • Live and Test mode. Passes are generated for contacts in both live and test mode, so cards can be validated before go‑live.

  • No card configured → not available. If no activated card exists for the business, pass retrieval returns not found and the contact sees a "pass not available" message.

  • Wallet Code recommended for barcodes. Linking the barcode to the CRM.COM Wallet Code gives the smoothest POS identification.

Integrations

This section covers how the mobile pass card connects to external wallet providers, APIs and systems - primarily relevant to integrators and administrators.

Apple Wallet (PassKit)

  • CRM.COM generates a signed .pkpass served as application/vnd.apple.pkpass.

  • Passes implement the Apple PassKit Web Service so devices stay in sync: register a device for updates, list updatable serial numbers, fetch the latest version of a pass, and unregister. These are authenticated with an ApplePass token and are called by Apple Wallet, not directly.

  • Balance/detail changes are pushed to devices so Apple Wallet refreshes the pass.

Google Wallet

  • CRM.COM builds a Google Wallet loyalty pass and returns an HTTP 307 redirect to the Google Pay save URL (<https://pay.google.com/gp/v/save/{jwt}),> which adds the pass to the contact's Google Wallet.

  • A pass record is created on first save and updated on subsequent saves.

  • A scheduled Google Wallet class‑update job propagates design/class‑level changes to already‑issued Google passes.

Wallet Passes (Android)

  • For Android apps that read the Apple PKPass format, CRM.COM issues a signed .pkpass (reusing the Apple design) and supports the same register/update/unregister lifecycle, authenticated with an AndroidPass token.

POS / Merchant App

Identification and spending against the wallet from the mobile pass card (barcode/QR, OTP, wallet code) can also be submitted through the CRM.COM Merchant App or a third‑party POS integration. See Integrators Hub - POS Integrations.

Reference Material

Landing Pages · Passes · Wallet · Customer Events · Integrations

TABLE OF CONTENTS