All articles
developers

Add a Wallet Pass From a React Native or Expo App: the Link, the Native Sheet, and the Expo Go Wall

Two ways to hand a pass from your app to Wallet, what each costs you in native code, and why the button works on the web but not in Expo Go.

Julio Song
13 min read

Marco has the web version working by lunch. His climbing gym sells memberships through a Next.js site, and the confirmation page has an Add to Apple Wallet badge that links to a signed .pkpass. Two lines of JSX. Tap, preview, done.

The mobile app is the afternoon's job. It's an Expo project, so he reaches for the obvious thing and calls fetch on the same URL from a button handler. The request returns 200. The response is about four kilobytes of binary. Nothing happens on screen, because nothing in JavaScript knows what to do with a pass.

On the web, the browser does the work for you. It reads a MIME type and hands the file to Wallet. Inside your app there is no browser, so that handoff is yours to arrange. You have two ways to do it, and they differ mostly in how much native code you're willing to own.

The app's job is smaller than you think

Some teams start by looking for a way to build the .pkpass on the phone. Don't. Your app should never build or sign a pass.

Signing a .pkpass needs the private key from your Pass Type ID certificate. Anything you ship inside an app bundle can be pulled back out of it, and a leaked signing key lets a stranger mint passes under your name until the certificate is revoked. If you haven't decided where that key lives yet, where to store your signing certificate covers the options. A phone isn't one of them.

So the split is fixed. A server issues the pass. The app asks for it and passes it along. With a hosted API, the server half is one request:

// server: called by your app after a membership is purchased
export async function issuePass(member: { id: string; email: string; name: string }) {
  const res = await fetch('https://api.passmint.com/v1/passes', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PASSMINT_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `membership-${member.id}`,
    },
    body: JSON.stringify({
      template_id: 'tmpl_xxx',
      holder_email: member.email,
      holder_name: member.name,
      field_values: { memberNumber: member.id },
    }),
  })

  if (!res.ok) {
    throw new Error(`Pass API returned ${res.status}`)
  }

  const pass = await res.json()

  return { url: pass.url, downloadUrl: pass.download_url }
}

Two fields in that response matter to a mobile app. url is a web page that shows the right button for whatever device opens it. download_url is the .pkpass file itself. The first is for the link path, the second is for the native sheet. The API key stays on the server either way, and the full parameter list is in the API reference.

If you sign passes yourself, the shape is the same. Your server exposes one route that returns HTML and one that returns application/vnd.apple.pkpass. The Next.js guide builds exactly that pair.

Apple's documentation lists four ways to distribute a pass: add it automatically during an in-app action, add it from an app with a button, offer a download on a web page, or attach it to an email. The cheapest thing a React Native app can do is borrow the third one.

import { Linking } from 'react-native'

export async function openPassPage(passUrl: string) {
  await Linking.openURL(passUrl)
}

That's the whole integration. Linking.openURL hands an https URL to the phone's browser. The browser loads the pass page, the user taps the wallet button there, and the system preview slides up. On Android the same page offers Save to Google Wallet instead, so one line covers both platforms.

It also runs in Expo Go, because Linking ships with React Native. You install nothing and rebuild nothing.

You pay for that in three places.

The user leaves your app. They land in a browser, add the pass, and have to find their way back. For a membership they just bought, that's a strange place to end the purchase.

You never learn what happened. openURL resolves when the browser opens. It can't tell you whether the pass was added, dismissed, or never loaded.

The browser is the user's choice, not yours. If their default on iPhone is Chrome or Firefox, you inherit the long-running reports on Apple's developer forums that those browsers don't reliably hand a downloaded .pkpass to Wallet. Linking to a pass page with its own button is safer than linking straight to the file, but you can't test every browser your users have set as default.

For a first release, or an app where the pass is a side feature, this is a reasonable place to stop. If the pass is the point of the app, keep going.

The native sheet: stay inside your app

The second path is the one Apple designed for apps. PassKit has a view controller, PKAddPassesViewController, that its documentation describes as letting your app show a pass and prompt the user to add it. Your app downloads the .pkpass, gives the bytes to that controller, and the familiar preview appears over your own screen with Add in the corner.

React Native doesn't expose PassKit, so you need a native module. One maintained option is react-native-wallet-manager. Its 2.2.0 release landed in October 2026, and it wraps both wallets behind one import.

import { Linking, Platform } from 'react-native'
import WalletManager from 'react-native-wallet-manager'

type PassLinks = { url: string; downloadUrl: string }

export async function addToWallet(pass: PassLinks) {
  if (Platform.OS !== 'ios') {
    await Linking.openURL(pass.url)
    return 'opened'
  }

  try {
    await WalletManager.addPassFromUrl(pass.downloadUrl)
    return 'added'
  } catch (error) {
    const code = (error as { code?: string }).code

    if (code === 'USER_CANCELLED') return 'cancelled'
    if (code === 'PASS_ALREADY_EXISTS') return 'already-added'

    throw error
  }
}

Compare the return values with the link path. You now know when the user backed out, and you know when the pass was already there. That's enough to change the button to "View in Wallet", log a real conversion, or skip the prompt next time.

A few things in that library's README are worth reading before you install it.

Version 2 needs the New Architecture. It's a TurboModule. On a project that still runs the old bridge, every call rejects with native module NativeWalletManager not found. The README points old-architecture apps at version 1.1.3.

One add at a time. A second call while the sheet is up rejects with ADD_PASS_IN_PROGRESS. Disable your button while the first promise is pending, or a double tap turns into an error toast.

Headers go to every URL. addPassFromUrl takes an optional headers object, which is how you'd send a session token to your own pass route. If you later switch to the batch method, that token goes to every URL in the list. Don't mix your own routes with third-party ones in a single call.

Adding needs no entitlement. The README is explicit that adding a pass doesn't depend on the Wallet capability. The capability is for the other half of the API: hasPass, viewInWallet and removePass. Those only see passes whose Pass Type ID belongs to your Apple team. A pass signed under someone else's certificate is invisible to your app, even though your app just added it. That includes test passes from a hosted provider that signs with its own certificate until you go live, so expect hasPass to return false in test mode and don't file it as a bug.

Where Expo Go stops

Consider a representative two-person team, based on an anonymized example. They build a studio booking app in Expo and test everything in Expo Go on their own phones. The link path ships in a day. A month later they want the native sheet, install the wallet library, reload, and tap the button.

The error is native module NativeWalletManager not found. They read the README, see the New Architecture note, and spend an hour checking a flag that was already on.

The flag wasn't the problem. Expo Go is a prebuilt app from the App Store. It contains the native modules Expo chose to bundle and no others. Installing a package with npm changes your JavaScript. It can't change the binary already sitting on your phone. Expo's own documentation calls Expo Go "a limited playground", and describes a development build as your own version of it where you're free to use any native library.

So the fix is a different app on the phone, not a different line of code:

npx expo install expo-dev-client react-native-wallet-manager
npx expo run:ios --device

That compiles your project with the wallet module inside it and installs the result on a connected iPhone. From then on you reload JavaScript the way you did in Expo Go. You only rebuild when native code changes.

The team's second surprise came a week later. One of them had opened the generated ios folder in Xcode and added the Wallet capability by hand, so hasPass would work. Then a teammate ran npx expo prebuild --clean, and the capability disappeared. Expo regenerates the native projects from app.json and package.json, and its docs warn that prebuild overwrites direct native edits.

In an Expo project, entitlements belong in config:

{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.example.studio",
      "entitlements": {
        "com.apple.developer.pass-type-identifiers": ["$(TeamIdentifierPrefix)*"]
      }
    }
  }
}

That key is the entitlement behind the Wallet capability. Apple documents it as the list of pass types your app can access, and the wildcard value means every pass type on your team. Your provisioning profile has to carry the capability too, so expect one more build after you add it.

The lesson that team took away is a useful rule of thumb. If a wallet feature gives your app information back, it needs native code, and native code means a development build. If it only sends the user somewhere, a link will do, and Expo Go is fine.

Android gets a different pass

Nothing above puts a pass on an Android phone. Google Wallet doesn't read .pkpass files. It saves an object described by a signed JWT, which is a separate integration with its own issuer account. The JWT flow covers the server side.

On the device, Google gives you the same two choices Apple does.

The link. A signed JWT appended to https://pay.google.com/gp/v/save/ is a save link. Open it with Linking.openURL and Google Wallet takes over. Google's docs say Android apps may use this web method directly.

The SDK. The Google Wallet Android SDK is the play-services-pay library. You ask getPayApiAvailabilityStatus whether saving is possible, show the button only if the answer is AVAILABLE, then call savePassesJwt with the token. The save sheet appears over your app and you get a result code back: saved, cancelled, or an error with a message.

react-native-wallet-manager wraps the SDK calls, so the Android branch can look like this:

import { Linking } from 'react-native'
import WalletManager from 'react-native-wallet-manager'

export async function saveToGoogleWallet(jwt: string) {
  const sdkAvailable = await WalletManager.canAddPasses().catch(() => false)

  if (sdkAvailable) {
    await WalletManager.addPassToGoogleWallet(jwt)
    return
  }

  await Linking.openURL(`https://pay.google.com/gp/v/save/${jwt}`)
}

The fallback isn't optional. Google's documentation says the API can be unavailable when Android or Google Play services is out of date, or when Google Wallet isn't offered in the user's country. Its advice is to hide the button and fall back to a JWT link.

Two Google-side details catch React Native teams late. The SDK has a second call, savePasses, that takes an unsigned object and lets the SDK sign it for you. Google's guide for that route has you register your app's package name and the SHA-1 fingerprint of its signing certificate in the Google Pay and Wallet Console. A debug build and a store build are usually signed with different keys, so a fingerprint taken from one won't match the other. Sending a JWT your server already signed, as the code above does, keeps the signing key off the phone. And until Google approves your issuer account, every pass says "[TEST ONLY]" and only saves for accounts on your tester list. Demo mode explains both the label and the request that removes it.

If you'd rather not sign Google JWTs yourself, the pass page from the first section already does. On Android, Linking.openURL(pass.url) lands on a page with the save button, and you skip the SDK entirely.

Two buttons you don't get to draw

A Pressable with a wallet icon and your brand color is the natural React Native move. Both platforms rule it out.

Apple's guidelines separate the two surfaces. The Add to Apple Wallet badge artwork is for web pages, emails and print. For apps, Apple says to use the PKAddPassButton class, a system control that picks the right appearance and language for you. The general rules still apply: don't create your own version, don't use the Wallet icon alone, don't animate it, and don't dim it to show a disabled state.

Google is stricter about measurements. The Add to Google Wallet button has a minimum height of 48 dp and needs 8 dp of clear space on every side. You can't change its color, font, corner radius or padding. If other buttons share the screen, Google says the wallet button must be equal or larger in size. Google publishes the button in dozens of locales and tells you not to make your own translation.

In practice that means two image assets or native views, chosen by Platform.OS, with nothing of your own design on top. It's less work than designing a button, and users already know what both of them mean.

What the app still can't see

Getting the pass into Wallet is the visible half. A few things happen afterwards that your app has no part in.

Updates don't go through your app. When a membership tier changes, Wallet fetches the new pass from a web service using a token stored in the pass. Your app can be deleted and the pass will keep updating. It also means an app release can't fix a pass that has gone stale. The update protocol is where that work lives.

Not every device can add passes. Call canAddPasses before you render the button. PassKit answers that question per device, and showing a button that does nothing is worse than showing none.

Removal is silent. A user can delete the pass from Wallet without opening your app. If your UI says "Added" forever, it will be wrong for some of them. With the Wallet capability and a pass signed by your own team, check hasPass when the screen mounts. Without it, word the button so it's still true on a second tap.

Marco's fix, in the end, was two decisions. He shipped the link path that afternoon, since it ran in Expo Go and covered Android for free. The native sheet followed a sprint later, behind a development build, once the team wanted to know how many members had added the card.

If you want the server half out of the way first, Passmint's quickstart issues a signed test pass in a few minutes and returns both URLs the code above expects. Open one from your app and you'll know which path you want.

Primary sources

Common questions

Only by opening a link. Linking.openURL hands the pass URL to the browser, which works in Expo Go. Showing the native Add to Wallet sheet inside your app needs a native module, and that needs a development build.
No. Presenting the add sheet works without it. The Wallet capability is what lets your app check whether a pass is already in Wallet, open it, or remove it, and only for pass types that belong to your own Apple team.
It should not. Signing needs the private key of your Pass Type ID certificate, and anything shipped inside an app bundle can be extracted. Sign on a server and send the app a URL or the finished file.
Sign a Google Wallet JWT on your server, then either pass it to the Google Wallet Android SDK through a native module or open the https://pay.google.com/gp/v/save/ link with Linking.openURL. Google recommends the link as the fallback when the SDK is unavailable.
Julio Song

Technical content writer, Passmint

Julio is a technical content writer at Passmint. He writes about Apple PassKit, the Google Wallet API, and what breaks when wallet passes meet production traffic.

More from Julio Song →

Related reading

Share this article