PARQORE Wallet Passes Plugin for NativePHP Mobile#
Add Google Wallet passes from a NativePHP Mobile app on Android.
Overview#
partek/wallet-passes is the on-device half of Google Wallet passes. Your Laravel backend (or any pass generator) produces a signed save link. This plugin opens Google Wallet's save flow from your NativePHP app and tells your app what actually happened.
Android and Google Wallet only. There is no Apple Wallet support. An iOS build of an app that includes this plugin still works: the plugin adds no native code to it, and PHP calls answer unsupported_platform (see "In an app that also ships on iOS").
use PARTek\WalletPasses\Facades\WalletPasses; $response = WalletPasses::addGooglePass('https://pay.google.com/gp/v/save/eyJ...'); // $response->accepted only means "the wallet UI is being shown".// The real result arrives as one event carrying $response->requestId:// WalletPassAdded, WalletPassAddCancelled or WalletPassAddFailed.
What it does:
- Reports what the device can do (
capabilities()), with a stable reason when it cannot (Google Play services missing, wallet unavailable, unsupported platform). - Adds a Google Wallet pass with the official Google Wallet Android SDK (
play-services-pay) and reports Google's result. - Checks the save token's shape in PHP before anything crosses the native bridge.
- Ships a test fake (
WalletPasses::fake()) and a JavaScript module for Inertia, Vue, React and plain JS.
What this is not#
- Not a pass generator. It does not sign Google Wallet JWTs or call the Google Wallet REST API. Those are server tasks. Use whichever tool you like; this plugin accepts the finished save link or JWT from any of them, including
spatie/laravel-mobile-pass(not required or installed by this package). See "Feeding passes from a generator" below. - Not Google Pay. Payments and payment cards are a different system. NativePHP's core
MobileWalletcovers those. This plugin is only for wallet passes such as tickets, memberships, loyalty cards, coupons and boarding passes. - Not able to read Google Wallet. Google offers no API to list, check or remove a user's passes, so this plugin has no such methods.
Support matrix#
| Android (Google Wallet) | |
|---|---|
| Minimum OS | Android 10 / API 29 (this plugin's nativephp.json) |
| Native API | Google Wallet API: com.google.android.gms:play-services-pay:16.5.0 |
| Pass input | Save-to-wallet JWT, or a https://pay.google.com/gp/v/save/{jwt} URL |
| Add outcome reported | Added, cancelled, failed |
| Runtime permission | None |
| Extra manifest entries | One transparent, non-exported activity (WalletSaveActivity) |
| iOS | Not supported. Calls answer unsupported_platform |
Installation#
composer require partek/wallet-passes
Register the plugin:
php artisan native:plugin:register partek/wallet-passes
If you have not published NativePHP's plugin provider yet:
php artisan vendor:publish --tag=nativephp-plugins-provider
Publish the config (optional):
php artisan vendor:publish --tag=wallet-passes-config
Rebuild after installing or after a manifest change:
php artisan native:run android
nativephp.json declares no Android permissions. It adds the Google Wallet SDK dependency and one transparent activity that receives the save result (see "How Google Wallet is integrated").
Google Wallet console setup#
The plugin cannot do any of this for you.
- Create a Google Wallet API issuer account in the Google Pay & Wallet Console and note the issuer ID.
- Create a Google Cloud service account with access to the Google Wallet API and give it the Wallet Object Issuer role for your issuer. Keep its key on your server only.
- Create your pass classes (and, for full JWTs, objects) with the Google Wallet API, or use a generator that does. Until Google approves your issuer for production, only the test accounts you list in the console can save passes.
- Have your server sign a save-to-wallet JWT (RS256) with the service-account key and give the app the JWT or the
https://pay.google.com/gp/v/save/{jwt}URL. This plugin does not sign or verify JWTs.
Adding passes#
addGooglePass(GooglePassSource|string $source): AddPassResponse#
Pass the signed JWT or the full save URL.
WalletPasses::addGooglePass($jwt);WalletPasses::addGooglePass('https://pay.google.com/gp/v/save/'.$jwt);
PHP checks the token's shape: three base64url segments, an RS256 header, aud of google, typ of savetowallet, an issuer, and at least one *Objects collection. It does not verify the signature, and Google can still reject a well-formed token (wrong issuer, unknown class). Only the pay.google.com/gp/v/save/ URL form is accepted.
add(array $sources): AddPassResponse#
The same add, for a source that may be absent: WalletPasses::add(['google' => $saveUrl]). Without a source, the response is accepted: false with reason missing_source.
The response and the outcome#
Every add returns an AddPassResponse:
| Property | Meaning |
|---|---|
requestId |
Correlates the eventual outcome event. |
accepted |
true when native code accepted the request. It does not mean the pass is in the wallet. |
platform |
DevicePlatform::Android, DevicePlatform::Ios, or null when no native bridge answered. |
reason |
A WalletFailureReason when accepted is false. No event follows. |
After accepted: true, exactly one of these events follows for that requestId:
| Event | Constructor properties | Meaning |
|---|---|---|
WalletPassAdded |
requestId, platform, ?passTypeIdentifier, ?serialNumber |
The pass is in the wallet. Google reports no identifiers, so the last two are always null. |
WalletPassAddCancelled |
requestId, platform |
The user closed the UI and nothing was added. A normal outcome, never an error. |
WalletPassAddFailed |
requestId, platform, reason, message |
Failed after acceptance. reason is a stable string, message a short safe description. |
WalletPassAddStarted (requestId, provider) is a PHP-only event dispatched synchronously just before a validated request crosses the bridge. Native code never sends it, so it is not in the manifest.
Add failures that are input problems (an empty, oversize or malformed token) throw InvalidPassSourceException with a machine-readable ->reason before any native call. An unsupported platform, an unavailable wallet, or a native refusal is a response with accepted: false, never an exception.
Failure reasons#
| Value | Where | Meaning |
|---|---|---|
invalid_request |
native | Missing or malformed input. |
invalid_token |
PHP, native | Not a well-formed Google save token. |
missing_source |
PHP | No Google source was supplied. |
too_large |
PHP, native | Over the size limit. |
unsupported_platform |
PHP | Google Wallet does not exist on this platform, for example an iPhone. |
play_services_missing |
native | Google Play services is missing, disabled or out of date. |
wallet_unavailable |
native | The Google Wallet API says this device or account cannot save passes. |
already_in_progress |
native | Another wallet request is still open. |
presentation_failed |
native | The wallet UI could not be shown. |
save_error |
native | Google Wallet reported an error while saving. |
service_error |
native | A platform wallet service failed or timed out. |
native_unavailable |
PHP | No native bridge (a browser or plain PHP), or the bridge call failed. |
unknown |
any | Anything unrecognised. |
Capabilities#
$capabilities = WalletPasses::capabilities(); // WalletCapabilities $capabilities->platform; // DevicePlatform::Android, ::Ios or null$capabilities->google->available; // bool$capabilities->google->reason; // ?WalletFailureReason$capabilities->current(); // Google Wallet's status, or null when the platform is unknown WalletPasses::isAvailable();WalletPasses::isAvailable(WalletProvider::Google);
capabilities() never throws. It checks Google Play services, then the Google Wallet API's getPayApiAvailabilityStatus. The result is cached per instance; pass true to refresh.
In an app that also ships on iOS#
A NativePHP app is usually built for both platforms, and this plugin is safe to leave in the iOS build. nativephp.json declares "platforms": ["android"], which NativePHP Mobile's iOS compiler honours: the plugin adds no Swift code, no bridge functions, no Info.plist keys and no entitlements to the iOS project.
Your PHP code stays the same. No WalletPasses.* bridge function exists on iOS, so the plugin asks NativePHP for the platform and answers with typed results:
| Call on iOS | Result |
|---|---|
capabilities() |
platform: DevicePlatform::Ios, google->available: false, google->reason: unsupported_platform |
isAvailable() |
false |
addGooglePass(), add() |
accepted: false, reason: unsupported_platform, no event |
JavaScript capabilities() |
{ platform: 'ios', google: { available: false, reason: 'unsupported_platform' } } |
JavaScript add(), addGooglePass() |
{ request_id: null, accepted: false, platform: 'ios', reason: 'unsupported_platform' }, even with the routes off |
Hide your Add to Google Wallet button when WalletPasses::isAvailable() is false. To test that path, use WalletPasses::fake()->onIos().
How Google Wallet is integrated#
The plugin uses the official Google Wallet Android SDK (PayClient.savePassesJwt) rather than opening the save URL in a browser, because the SDK reports a result.
The SDK returns its result through the calling activity's onActivityResult, and NativePHP's host activity is not something a plugin can change. So the plugin declares one small transparent activity, WalletSaveActivity, in its manifest (not exported, translucent, handles configuration changes). It calls savePassesJwt, receives RESULT_OK, RESULT_CANCELED or SAVE_ERROR, dispatches the matching event and finishes. The JWT is held in memory only, is passed by request id rather than in an Intent extra, and is never logged.
What Google reports and what it does not:
- Known: saved, dismissed, error (with an optional error message).
- Not reported: which object was saved, or whether an equivalent pass already existed.
WalletPassAddedtherefore hasnullidentifiers, and the plugin cannot tell you a pass was already saved. - Closing the flow without a result (for example backing out before Google Wallet appears) is reported as
WalletPassAddCancelled. - If the app process is killed mid-flow there is no event. Handle that case by letting the user try again.
- You can still hand a
pay.google.com/gp/v/save/URL to a browser yourself (for example NativePHP'sBrowserfacade) if you want the no-SDK route. You then get no outcome.
Front ends#
Livewire and Blade#
use Livewire\Component;use Native\Mobile\Attributes\OnNative;use PARTek\WalletPasses\Events\WalletPassAdded;use PARTek\WalletPasses\Events\WalletPassAddCancelled;use PARTek\WalletPasses\Events\WalletPassAddFailed;use PARTek\WalletPasses\Exceptions\InvalidPassSourceException;use PARTek\WalletPasses\Facades\WalletPasses; class AddToWallet extends Component{ public ?string $requestId = null; public string $status = 'idle'; public function add(): void { try { $response = WalletPasses::addGooglePass($this->ticket->google_save_url); } catch (InvalidPassSourceException $e) { $this->status = 'invalid: '.$e->reason->value; return; } $this->requestId = $response->requestId; $this->status = $response->accepted ? 'waiting' : 'unavailable: '.$response->reason->value; } #[OnNative(WalletPassAdded::class)] public function added(string $requestId): void { if ($requestId === $this->requestId) { $this->status = 'added'; } } #[OnNative(WalletPassAddCancelled::class)] public function cancelled(string $requestId): void { if ($requestId === $this->requestId) { $this->status = 'cancelled'; } } #[OnNative(WalletPassAddFailed::class)] public function failed(string $requestId, string $reason): void { if ($requestId === $this->requestId) { $this->status = 'failed: '.$reason; } }}
Listener parameters are bound by name from the native payload, so use the exact camelCase names above (requestId, platform, reason, message). In a NativePHP native UI (NativeComponent) screen use Native\Mobile\Attributes\On the same way. A complete component and view are in examples/AddToWalletButton.php and examples/add-to-wallet.blade.php.
Inertia, Vue, React and plain JavaScript#
Import resources/js/index.js (copy it into your front-end, or import it from vendor/partek/wallet-passes/resources/js/index.js through your bundler alias). Adds go through this package's optional routes, because a save token must be validated by PHP first. They are off by default; enable them with:
WALLET_PASSES_REGISTER_ROUTES=true
That registers POST /wallet-passes/add and /google (prefix and middleware are configurable; publish wallet-passes-routes to customise). Unusable input returns 422 with {error: <reason>, message}. Protect the routes with your own auth middleware if your app has users.
import { addGooglePass, capabilities, waitForOutcome, Events } from './wallet-passes'; const caps = await capabilities(); // { platform, google: {available, reason?} } const response = await addGooglePass(props.googleSaveUrl); if (!response.accepted) { showMessage(response.reason); // for example "wallet_unavailable"} else { const { type, payload } = await waitForOutcome(response.request_id); // type: 'WalletPassAdded' | 'WalletPassAddCancelled' | 'WalletPassAddFailed'}
waitForOutcome() also resolves if the event arrived before you called it. capabilities uses the native bridge directly and needs no routes. The bridge functions are WalletPasses.GetCapabilities and .AddGooglePass. An Inertia example is in examples/InertiaWallet.vue.
Feeding passes from a generator#
The plugin only needs the finished save link or JWT. Serve it from an authenticated endpoint on your server and pass it to the app. With spatie/laravel-mobile-pass, $mobilePass->addToWalletUrl() returns a pay.google.com save link for Google passes, which is exactly what this plugin takes.
examples/IssuePassController.php shows this. Check the generator's own documentation for the exact method names in the version you install. Pass updates after installation (Google object patches) are handled by those libraries and are out of scope here.
Testing#
There are two ways to test code that uses this plugin. WalletPasses::fake() replaces the facade, which suits service classes and plain PHP tests. The test helpers work with NativePHP's component test harness (Native::test()), which suits screens: the screen calls the real facade, the helpers answer the bridge the way the device does, and they deliver the native events.
Testing with the fake#
WalletPasses::fake() swaps the manager for FakeWalletPasses. Nothing crosses the native bridge. Token validation still runs for real, so a test catches an unusable token. Defaults: an Android phone with Google Wallet available, and accepted adds that report no outcome.
use Illuminate\Support\Facades\Event;use PARTek\WalletPasses\Enums\WalletFailureReason;use PARTek\WalletPasses\Enums\WalletOutcome;use PARTek\WalletPasses\Events\WalletPassAdded;use PARTek\WalletPasses\Facades\WalletPasses; it('adds a ticket to Google Wallet', function () { Event::fake([WalletPassAdded::class]); $fake = WalletPasses::fake()->reporting(WalletOutcome::Added); $response = WalletPasses::addGooglePass($this->jwt); expect($response->accepted)->toBeTrue(); $fake->assertGoogleAdded(fn ($request) => $request->jwt === $this->jwt); Event::assertDispatched(WalletPassAdded::class, fn ($e) => $e->requestId === $response->requestId);}); it('handles a phone without Google Play services', function () { WalletPasses::fake()->unavailable(WalletFailureReason::PlayServicesMissing); expect(WalletPasses::addGooglePass($this->jwt)->reason)->toBe(WalletFailureReason::PlayServicesMissing);}); it('hides the button on an iPhone', function () { WalletPasses::fake()->onIos(); expect(WalletPasses::isAvailable())->toBeFalse();});
| Method | Purpose |
|---|---|
onAndroid(), onIos(), usingPlatform($platform) |
Simulate the device. On iOS everything answers unsupported_platform. |
unavailable($reason), available() |
Simulate an unavailable or available wallet. Adds are then refused with that reason. |
rejecting($reason) |
Make native code refuse every add. |
reporting($outcome, ?$failureReason) |
Make each accepted add dispatch the matching outcome event with the request id. |
assertGoogleAdded($callback) |
The callback receives the AddPassRequest (requestId, jwt). |
assertNothingAdded() |
Negative assertion. |
added(), calls() |
Raw recorded requests and bridge calls. |
Test helpers#
On NativePHP Mobile 4.0 or later, the plugin registers these helpers on Native::fakeBridge() and on the Native::test() harness whenever the app runs under a test runner (APP_ENV=testing). Production boots never register them, and there is nothing extra to install.
use App\NativeComponents\TicketScreen;use Native\Mobile\Testing\Native; it('adds the ticket to Google Wallet', function () { Native::fakeBridge()->withWalletSupport(); Native::test(TicketScreen::class) ->tap('Add to Google Wallet') ->assertGooglePassAdded() ->confirmWalletPass() ->assertSee('In your wallet');});
Script the bridge first. With nothing scripted, the fake bridge answers null and the facade treats that as no native bridge: capabilities() has no platform and every add is refused with native_unavailable. The bridge assertions would still pass while your screen runs its failure branch.
| Helper | Called on | What it does |
|---|---|---|
withWalletSupport(string $platform = 'android', bool $available = true, array $extra = []) |
bridge | Answers as a working Android phone. capabilities() reports Android, and adds are accepted, one at a time. With $available = false the wallet is unavailable (wallet_unavailable) and adds are refused with that reason. $extra is merged over the capabilities answer, e.g. ['google' => ['available' => false, 'reason' => 'play_services_missing']]; adds follow it. Only 'android' is accepted: use WalletPasses::fake()->onIos() for the iPhone path. |
assertGooglePassAdded(?string $jwt = null) |
bridge | addGooglePass() reached the bridge, for any token or $jwt (the JWT or its save URL). |
confirmWalletPass(?string $requestId = null) |
harness | Delivers WalletPassAdded. Its identifiers are empty, as Google reports none. |
cancelWalletPass(?string $requestId = null) |
harness | Delivers WalletPassAddCancelled, as when the user closes the wallet UI. |
failWalletPass(string $reason = 'error', string $message = '', ?string $requestId = null) |
harness | Delivers WalletPassAddFailed. An empty $message becomes the reason's standard message, as native always sends one. |
Bridge helpers work on Native::fakeBridge() or straight off the harness. Called off the harness, they return the harness, so the chain continues.
- Request ids. The harness helpers use the
request_idof the lastaddGooglePass()call unless you pass$requestId. They fail with a message naming the helper if nothing was added, or if native refused that add (no event follows a refusal). - One add at a time. As on a device, an add is refused with
already_in_progresswhile an earlier accepted add has had no outcome yet. Deliver one with a harness helper before the next add. - Reasons. The default
erroris a placeholder that maps toWalletFailureReason::Unknown. Pass the reason your screen handles:presentation_failed,save_error,wallet_unavailable,service_errororinvalid_request. - Capabilities are cached. The facade caches the first answer that has a platform, so script
withWalletSupport()before the screen first checks the wallet. - With
WalletPasses::fake(). The fake replaces the facade, so nothing reaches the bridge while it is active: the bridge helpers see no calls, and the harness helpers can't find a request id. The harness helpers still work if you pass the id, e.g.->confirmWalletPass(requestId: $screen->get('requestId')). The fake'sreporting()outcomes go through Laravel'sevent()and never reach a screen's#[On]handler.
Configuration#
config/wallet-passes.php, environment variables in brackets:
| Key | Default | Purpose |
|---|---|---|
max_google_jwt_length [WALLET_PASSES_MAX_GOOGLE_JWT_LENGTH] |
65536 | Character cap on the save JWT. Google recommends short "skinny" JWTs. |
register_routes [WALLET_PASSES_REGISTER_ROUTES] |
false | Enable the optional HTTP routes. |
route_prefix, route_middleware |
wallet-passes, ['web'] |
Route options. |
No secret is read or stored by this plugin.
Security#
- Every token is checked for shape in PHP before the native bridge, and again natively.
- Tokens are never logged and never appear in exception messages or events.
- Error
messagestrings on failure events are fixed short descriptions (plus, for Googlesave_error, Google's own message truncated to 200 characters).
Report a vulnerability privately: email [email protected] with impact, repro steps and plugin and NativePHP versions. Do not open a public GitHub issue. Please allow reasonable time for a fix before disclosure.
Privacy#
The plugin processes passes on the device and in your app's PHP runtime. It sends nothing to PARQORE and makes no network requests of its own. Google receives the pass as part of the normal save flow.
Troubleshooting#
accepted: false with native_unavailable. No native bridge answered. You are in a browser, in plain PHP, or the plugin is not registered or the app was not rebuilt. Run php artisan native:plugin:register partek/wallet-passes and php artisan native:run android.
accepted: false with unsupported_platform. The app is running on iOS. This plugin supports Android only; hide the button when WalletPasses::isAvailable() is false.
wallet_unavailable. The Google Wallet API reports the device or account cannot save passes (Wallet not available in the region, unsupported device, or an ineligible account). play_services_missing means Google Play services is absent or needs updating.
Google says the pass cannot be saved. Check the token on your server: issuer ID, service-account role, class ID, and (before production approval) that the account is a listed test account. This plugin only checks the token's shape.
Platform behavior and verification status#
The PHP layer (validation, DTOs, events, fake) is covered by the package's own Pest suite, and the JavaScript module's iOS answers by a small node --test file. The manifest, bridge function classes, event names and payload keys are checked against the Kotlin source by the same suite, and the iOS path is tested by running the real class with no WalletPasses.* bridge functions registered. The Kotlin sources compile against the real Google Wallet SDK and NativePHP's bridge interfaces, using stand-in host code. That is compile-level evidence only.
Physical Galaxy A54, on version 1.0.x: capabilities(), PHP-side rejection of a garbage token, and two consecutive Google Wallet adds each opening Google Wallet and each producing their own event (an already_in_progress lockup bug found and fixed in this testing). An unsigned save token reached the real Google Wallet SDK and came back as WalletPassAddFailed. A real issuer-signed save URL (issuer in demo mode, device account listed as a test account) opened Google's "Add pass" sheet and tapping Add showed Google's "Added to Wallet" confirmation (2026-09-23).
Physical Galaxy A54, full round trip, on version 1.0.x (2026-09-29): with the issuer approved for publishing (out of demo mode since 2026-09-24) and a save URL freshly signed by the issuer's service account (generic class), capabilities() returned google: available=true; addGooglePass() returned accepted: true; Google's "Add pass" sheet appeared; tapping Add showed "Added to Wallet" and, back in the app, WalletPassAdded (platform android, same request id). A second freshly signed URL, then Cancel and Exit on Google's "Are you sure you want to exit?" prompt, gave WalletPassAddCancelled with that request's id. The device account is still listed as a Wallet test account, so this run does not show whether a non-test account can save now that publishing is approved. Demo video recorded.
Physical Galaxy A54, version 2.0.0 (2026-10-30): capabilities() returned google: available=true; addGooglePass() opened the Google Wallet sheet; cancelling fired WalletPassAddCancelled; adding showed "Added to Wallet" and fired WalletPassAdded; a garbage token returned invalid_token; an unsigned JWT fired WalletPassAddFailed with service_error. No iOS app with this plugin has been built with 2.0.0.
Not yet verified: the JWT (non-URL) input form on device, a Google-rejected token after publishing approval, already_in_progress while the sheet is open, rotation, and a non-test account. Before you ship, run the rest of the matrix in CONTRIBUTING.md.
Upgrade notes#
From 1.x to 2.0#
2.0.0 removes Apple Wallet and iOS. On Android, adding a Google Wallet pass works as before.
addApplePass(),hasPass(),containsPass(),listPasses(),removePass(),syncCheck()andpurgeTemporaryFiles()are gone, with the DTOs behind them. They only ever worked on iOS.add()reads only thegooglekey.WalletPassAlreadyExistsis gone. Android never sent it.$capabilities->appleis gone.WalletPasses::fake()now defaults to Android, andwithWalletSupport()defaults to'android'and refuses'ios'.confirmWalletPass()now takes only$requestId.- The
/wallet-passes/appleand/wallet-passes/containsroutes are gone. If you publishedroutes/wallet-passes.php, remove those two lines. - The
max_pkpass_bytes,downloadandfilesconfig keys are gone.
Bridge function names, event names and payload keys, and the failure reason strings are the compatibility contract and will not change within a major version.
Support policy#
Supported: the current major version of the plugin on NativePHP Mobile 4.x (^4.6.1), PHP 8.2 or newer, and Laravel 10 to 13. Bug reports with reproduction steps go to the support address on the Marketplace listing. Security issues: [email protected], not public issues. Google Wallet behavior (approval processes, quotas and policies) is outside the plugin's control.
License#
Proprietary commercial. All rights reserved (c) 2026 PARTek. Unauthorized copying or redistribution is prohibited except under a written license with PARTek. The full license text ships in the LICENSE file included with this package.