How wallet passes actually work

Start with the counter. You need to recognise a card, record an eligible purchase and show the member the resulting balance. Keep those jobs in view when assessing a wallet programme. A polished card is a useful demonstration of appearance; ask for a separate demonstration of what happens when you award a stamp, correct a mistake and redeem a reward.

Apple’s developer guide describes a pass as a copy of records held on your server, with a barcode commonly pointing back to those records. That is a useful starting point: treat the card as a view of the membership, and the shop’s record as the place to check it. See Apple’s explanation of barcodes and records.

Adding the card is a customer action

Apple documents distribution through a website or email without requiring the shop’s own app. It also requires the user to see and approve the pass before it is added. A link is therefore an invitation to save a card, rather than evidence that the card has been saved. The distinction is explicit in Distributing Passes.

Google documents an Add to Google Wallet link that can be placed on a website, in email or in an SMS. Saving through that link requires a logged-in Google identity. Keep that account requirement separate from any account your own programme asks someone to create; they are different steps in the join journey. See Google’s web issuance guide.

For your counter, plan a joining page with a clear explanation of the reward and the appropriate add button. If you put a QR code beside the till, use it to lead to that page. In your trial, follow the whole route on a customer-facing phone, including opening the saved card again. Judge the completed journey, not just whether the joining page loads.

Make the wording useful to someone standing in a queue. Say what the card earns, where it can be used and what to present on the next visit. Keep help within reach for anyone who stops midway. Do not make the staff member guess whether a page view, an issued membership and a saved pass all mean the same thing in your reporting.

What the shop issues

Apple’s pass package contains structured information and artwork. Its pass type identifier and serial number together identify a particular pass; an updated version uses the same pair. Google describes a shared Class and an individual Object: the template and the particular pass. These are different platform arrangements for distinguishing a programme from a member’s card. See Apple’s pass format guide and Google’s development flow.

Ask whoever supplies the programme to show where the member record sits and how it relates to each issued card. Include replacement cards in that discussion. Write down how staff should recover an existing membership, and how they should distinguish a recovery from a new enrolment. Make preservation of the correct balance something you verify in the implementation.

Give the visible card a similarly precise brief. Put the shop name, current progress and the next reward where the member can understand them without a staff explanation. Decide how the display changes when a reward is ready and after it has been used. Read the wording at each stage. If the card shows a balance but leaves the guest guessing what that balance buys, revise the explanation before spending more time on the artwork.

Follow the membership record from the counter to the card. Every handover should have an answer you can inspect.

How an Apple pass changes

For an updatable Apple pass, the issuer supplies a web service URL and an authentication token. The device registers for updates. When information changes, the server sends a push signal; the device then asks the server for the changed passes and downloads their latest versions. The balance itself is fetched afterwards. Apple sets out that sequence in Adding a Web Service to Update Passes.

The archived protocol guide explains why the push is a signal: delivery is not guaranteed, and notifications can be combined. It separately describes change messages attached to fields. A field update and a visible message are therefore different things to assess. See Updating a Pass. Avoid building your counter procedure around a promised delivery time that your own trial has not established.

For a trial purchase, first confirm that the award appears in the shop’s record. Then inspect the pass. If they disagree, ask how staff can check the latest balance without issuing another stamp. Practise the explanation you would give at the counter. The important acceptance criterion is a correct, traceable award and a workable response to a delayed display.

How a Google pass changes

Google lets the issuer update a pass class or a pass object through its API. A class change affects the passes using that class; an object change addresses the individual pass. Its guide distinguishes update, which replaces the resource, from patch, which changes supplied fields. For a member balance, ask to see the individual object being changed. See Google’s update guide.

Google also documents notifications for supported field changes, including a loyalty points balance. Those notifications require the relevant notification setting and the user’s notification permission; they are not implied by every edit. The documented distinction is between updating data and asking Wallet to notify the user about it. See Trigger Push Notifications.

Test the same operations on each platform. Award a stamp, undo an accidental award and redeem a completed reward. For each operation, compare what the till shows with what the pass shows. Use the same written expectations for both. Leave room for different presentation, but require the underlying reward rule and resulting balance to agree.

The lock screen is governed by relevance

Apple: a place, an appropriate date, or both

Apple allows relevance information to help the system show a pass on the lock screen. Its current guide describes locations and relevant dates, with date relevance for boarding passes, event tickets and generic passes. It requires locations for store cards when relevance information is supplied. See Showing a Pass on the Lock Screen.

Apple’s current format also documents relevantDates, which can describe a relevant date or an interval. This is context for when a pass is useful, not a promise to deliver a promotional message at a chosen hour. Do not sell a store card’s location relevance as a scheduled alarm. The fields are described in Pass.RelevantDates.

Google: nearby notifications with permissions

Google’s nearby feature requires notifications to be enabled and precise, always-on location access for Wallet. Google decides the radius, dwell time and notification text. Its merchantLocations field supplies the shop locations; the issuer does not choose a guaranteed notification moment. See the nearby notification requirements.

The MerchantLocation reference describes a notification while the user is nearby and its disappearance after they leave. The older locations field is deprecated and does not support triggering geo notifications. Google states that explicitly in the LoyaltyObject reference. A location in a data record is not sufficient evidence that this feature has been configured.

During setup, check the shop coordinates and describe the expected behaviour carefully. Ask your provider to distinguish a relevance suggestion, a balance-change notification and a separate promotional message. Record which settings the demonstration used. That gives you a useful explanation to share with staff instead of an instruction to keep walking past the door until something appears.

What scanning the barcode does

Google’s barcode reference separates the format, the encoded value and optional alternative text. The code is data that your redemption system must interpret. Apple likewise describes using a barcode identifier to look up a record. Choose a value your system can resolve, and test it with the scanner you intend to use. See Google’s Barcode reference and Apple’s barcode guidance.

Specify what a successful scan should do before choosing the hardware. Should it open the member record, add an eligible stamp after staff confirmation, or present a reward for redemption? Keep those actions deliberate. Include an accidental repeat scan in the trial and check that the programme does not award or spend a reward twice merely because the operator tries again.

Write a fallback procedure as part of the same exercise. Ask how staff should proceed when a code will not scan or the connection is unavailable. If you allow a later correction, decide what evidence to keep and who can authorise it. Treat any proposed offline operation as a separate capability to demonstrate with a subsequent reconciliation of the records.

Also agree who will look after the programme once the initial demonstration is over. Nominate a contact for incorrect balances and failed updates, and ask the supplier what information helps them investigate. Keep a test membership available for checking a revised reward rule or a changed scanner. Make those checks part of an actual change to the programme, with the expected outcome written down. Give staff a short route for reporting a problem, including the action they attempted and the result they saw, without asking them to diagnose the platform.

A useful acceptance test at the counter

1. Join through the actual counter link, save a pass and find it again without a reminder.
2. Make a test award, compare the member record with the displayed balance, then reverse the award.
3. Earn and redeem a test reward, including an attempted repeat redemption.
4. Try the agreed fallback and recovery procedures. Check which actions require a manager.
5. Review nearby behaviour with its settings recorded, separately from whether the card works at the till.

Ask for those demonstrations before signing off the programme. Your final brief should explain who issues the card, who stores the reward record, what a scan authorises and how a changed balance reaches the phone. With those answers written down, you can train the next person behind the counter without asking them to understand the platform underneath it.