Download the PHP package laulamanapps/google-wallet without Composer

Google Wallet

Generate Google Wallet passes from PHP. The Google counterpart of laulamanapps/apple-passbook.

Passes are distributed via "Add to Google Wallet" links: an RS256-signed JWT whose payload embeds the pass classes and objects (a so-called "fat JWT"). Because the classes and objects travel inside the JWT, no Google Wallet REST API call is needed — the only dependency is ext-openssl for signing.

Installation

Or use one of the framework integrations, which wire the service account and save-URL factory from configuration:

• Symfony: laulamanapps/google-wallet-symfony
• Laravel: laulamanapps/google-wallet-laravel

Service account setup

1. Sign up for a Google Wallet issuer account in the Google Pay & Wallet Console and note your issuer id.
2. Create a Google Cloud service account with the Wallet Object Issuer role and download its JSON key file.
3. Link the service account to your issuer account in the console.

Quickstart

Render the url as an Add to Google Wallet button and you are done.

Pass types

Next to GenericClass/GenericObject the same pattern is available for:

• EventTicketClass / EventTicketObject
• OfferClass / OfferObject
• LoyaltyClass / LoyaltyObject
• TransitClass / TransitObject

Add them to the PassPayload with the matching add*Class()/add*Object() methods.

Location-triggered notifications

Google Wallet shows a Nearby Passes notification when a pass holder is close to one of the pass's merchant locations (the user must have granted always-on location access; Google controls the notification text and timing). Add up to 10 locations per object:

Updating passes

Once a pass is saved to a wallet you can change it through the Google Wallet REST API. Unlike Apple Passbook there are no push tokens or APNs involved: Google pushes updates to devices automatically after an API call. The API client uses ext-curl by default (or bring your own HttpClient implementation); an OAuth2 access token is obtained and cached for you via the service-account JWT-bearer grant.

The same pattern works for classes (insertClass(), updateClass(), patchClass()) and for all pass types. Errors surface as LauLamanApps\GoogleWallet\Exception\ApiException.

Receiving save/delete callbacks

Google can notify you whenever a user saves or deletes a pass. Set a callback url on the pass class (available on all five class types) and Google will POST a signed message to that endpoint on every save and delete:

Google signs every callback with the ECv2SigningOnly scheme (ECDSA over NIST P-256 with SHA-256, sender GooglePayPasses, your issuer id as recipient). Verify the raw request body with CallbackVerifier; it fetches Google's root signing keys, checks the intermediate signing key against them, checks the message signature against the intermediate key and rejects expired keys and messages:

[!WARNING] Never act on a callback without running it through CallbackVerifier. The endpoint is public and anyone can POST to it; only the signature chain proves the request came from Google. verify() never returns unverified data — every failure throws a CallbackException.

Callbacks are best-effort and may arrive more than once: use getNonce() to deduplicate. Reuse one CallbackVerifier/GoogleKeyProvider instance where possible — the root signing keys are cached per GoogleKeyProvider instance. GoogleKeyProvider::test() points at Google's test root keys for integration testing.

Signing a JWT yourself

SaveUrlFactory covers the common case. If you need the raw JWT, use JwtSigner directly:

Credits

• Laurens Laman

License

The MIT License (MIT). Please see License File for more information.