Guides
Cards on the phone

Google Wallet for a loyalty card

Google Wallet builds the card differently from Apple, and if you design only with the iPhone in mind, it looks wrong on Android. Here are both.

Updated 10 August 2026 · we keep it up to date because we use it ourselves.

The fundamental difference from Apple

Before getting to the sizes, it helps to understand why you can’t just “export the same thing” to both systems:

Apple WalletGoogle Wallet
What the card isA signed .pkpass file downloaded to the phoneAn object that lives on Google’s servers; the phone receives a link
The imagesGo inside the fileAre linked by URL: they must be published on your server
To update itYou send a notification and the phone downloads the new passYou update the object through Google’s API
Prior permissionApple certificate, paid yearlyIssuer account and Google review
The practical consequence that catches everyone out. With Google, your images must be publicly accessible by URL. If you keep them in a private folder, or if the URL changes with every deployment, the card ends up with no image on the customer’s phone — and you won’t notice, because it looks perfect on your iPhone.

The two images

A Google Wallet loyalty card shows two images:

ImageSizeWhere it appearsWhat to use
Programme logo
programLogo
660 × 660 px
minimum, 1:1
At the top, next to the name, on the card detail and in the list. Cropped into a circle. Your symbol, centred, on a square with a full-bleed background.
Header image
heroImage
1032 × 812 px
recommended
A band on the front of the card. Displayed at 100% of the width. On a stamp card, the stamp slots. Otherwise, a photo of your venue.

Both as PNG. And with the logo there’s a detail Google actually puts in writing, which ruins half of the ones that get uploaded: leave a 15% safe margin all round. Anything touching that edge gets eaten by the circular crop.

Google’s header is NOT the same shape as Apple’s strip. Apple asks for a very wide band (about 2.6:1). Google recommends 1032 × 812, which is almost square. That said, the API reference only says the image “is displayed at 100% width”: a wide band also fits, and that’s what we do here — the same stamp image that goes inside the Apple pass is linked as the heroImage on Google. It works; it just isn’t the ratio they recommend for a purpose-designed hero. If you’re going to look after both separately, this is the one to redo.

The logo is cropped into a circle (and that’s where your wordmark dies)

This is the detail that ruins the most designs. On Apple, the logo sits in a wide box and your long wordmark fits in full. On Google, it’s cropped round.

If you send the same file to both, on Android your wordmark loses its ends and is left with the three letters in the middle. The fix isn’t technical, it’s design:

  • Prepare a square version of the logo just for Google.
  • Centre it and give it breathing room: anything touching the edge of the square is lost in the crop.
  • If your brand is a long piece of text, use the symbol or the initial, not the full wordmark.

The visible fields

Google lays out the card differently: there are no “rows” as on Apple, but fields with their own names.

FieldWhat it isWhat to put there
issuerNameWho issues itThe name of the club, not just the business
programNameThe pass titleThe customer’s name, if you have it
accountNameThe holderThe member’s first name and surname
loyaltyPointsThe big counter“7/10” on a stamp card, the balance if you use points
textModulesDataFree text blocksTier, next reward, short terms
hexBackgroundColorThe card colourA hex #rrggbb. If you leave it empty, it’s taken from the dominant colour of your header (and failing that, from the logo)
If you don’t set a colour, Google makes one up — and it gets it right less often than you think. On Apple you set the background and text separately. On Google you provide hexBackgroundColor in #rrggbb format, and if you leave it empty the system uses the dominant colour of your header image; if there’s no header either, the dominant colour of your logo. A photo with lots of brown leaves you with a brown card. Set it yourself.

The scan code

The card carries a code for your team to scan. The usual choice, and the one that works best at a counter, is a QR code: any phone can read it, it copes with a dirty or dim screen, and you don’t have to buy a scanner.

A small detail with consequences: the text under the code. If you leave the member ID there, the customer sees a jumble of characters under their card. It’s better to leave it empty or put something that means something to them.

Messages

To notify a customer on Android, you add a message to their card. It works differently from Apple, where the notification is the update of the pass itself.

This has two consequences to keep in mind:

  • The same notice looks different on each system. Always test on an iPhone and an Android before sending anything to your whole base.
  • Messages pile up on the card. They aren’t notifications that disappear: they stay there. Sending one a week turns the card into a noticeboard of old announcements.

On what to write and when, we have a whole guide: pass notifications.

Google’s review

Unlike Apple — where once you have the certificate you can start issuing — in Google Wallet pass classes go through a review before they can be issued at scale. It isn’t instant, so factor it into your timelines: if you promise a client their card will be ready “tomorrow”, make that tomorrow on iPhone and a few days on Android.

Both systems, or neither. In Spain and Portugal, Android makes up more than half of all phones. Building only for Apple because “it’s easier” means leaving out half your customers — and they’re exactly the ones who won’t understand why it works for their friend and not for them.

Frequently asked questions

Can I have the same loyalty card on iPhone and Android?

Yes, but it is not the same file. Apple uses a .pkpass package that gets downloaded; Google Wallet uses an object that lives on Google’s servers and is linked to. You have to build both, and the design does not carry over as it is.

What images appear on a Google Wallet card?

Two: the programme logo (programLogo), at least 660 × 660 px and square, shown at the top cropped into a circle; and the header image (heroImage), which Google recommends at 1032 × 812 px and displays at 100% of the card’s width. Both as PNG.

Why does my logo look cut off on Android?

Because Google masks it into a circle. A wide logo loses its ends. You need to upload a square version of at least 660 × 660 px, centred and with a 15% safe margin all round: anything touching the edge gets eaten by the crop.

How do you notify a customer in Google Wallet?

You add a message to the card object. This differs from Apple, where the notification is the update of the pass itself. That is why the same notice can look different on each phone, and you need to test it on both.

If you’re coming from Apple or heading there, the size table is in Apple Wallet pass sizes.

And if you’d rather not build any of this

etlas does everything on this page for you: it generates the images at the right size, builds the pass for Apple and Google, and updates it on your customer’s phone every time they get a stamp. You choose the colours and the rewards.