• ⚛️ Card In-App Provisioning seamless integration
• ♻️ Universal solution (Apple Wallet and Google Wallet)
• 💳 Easy and secure addition of payment cards from your app directly
• 💰 Supports Visa, MasterCard, Amex and Discover payment cards
• 🔐 UAPP (Unified Android Push Provisioning) support for enhanced security
• 🎉 Expo support (expo-plugin)

Using the react-native-wallet Push Provisioning features requires proper configuration and access from both Google and Apple. Please follow the instructions below before installing the library:

To be able to interact with the Google Wallet on the Android please make sure to complete all of the steps below following the Google Push Provisioning documentation:

1. Visit the Google Pay Android Push Provisioning API documentation and request access to it.

2. Once getting an approval from the Google team

   1. Download the TapAndPay SDK. The library uses the UAPP APIs (PaymentCredentialsGenerator, PushTokenizeResult), so older SDK versions without them will not compile. Tested with 18.10.1.
   2. Unzip it and extract the SDK into the /android/libs folder in your React Native project (if there is no libs folder, create one).
   3. Add /android/libs to .gitignore.

3. Then connect the SDK to your project in build.gradle, for example like in example/android/build.gradle:

allprojects {
	repositories {
		google()
		maven { url "file://${rootDir}/libs" }
	}
}

To use the Google SDK in your app, you will need to whitelist your app details. Without it, calling some functions will result in a Not verified error. To resolve it, please follow the instructions from the official Google documentation.

For your builds, you will need to prepare your app's package name and fingerprint following these steps. The values should, for example, look like this:

Package name: com.app.package.name

Fingerprint: SHA256: 36:38:63:59:6E:...:00:82:16:4E:FF

With all the required data, submit the form and wait for Google's response. After successfully whitelisting your app you will be able to use Google SDK within our library.

To enable In-App Provisioning in your app, you must request activation of the appropriate Apple Pay entitlements for your developer Team ID. Enterprise Team IDs are not supported. This entitlement is not available by default in our panel; you will need to request it.

Submit your request through the In-App Provisioning Submission Form. Only Account Holders can access this form — if you are unable to access it, coordinate with the Account Holder of your team. Alternatively, you can email iap_entitlements@apple.com with the following format:

Subject: Apple Pay Entitlements and Allow List Request - [Issuer Name] - [Country Code]

Body:

• Issuer Name
• Country [Country Code]
• Team ID
• Adam ID
• App Name

Once Apple verifies your identity, you should get documentation named Getting Started with Apple Pay In-App Provisioning, Verification & Security. In this confidential document you will find all the relevant information about:

• Prerequisites for your project
• Best practices to follow
• How In-App Provisioning works
• UX requirements
• Testing process
• and more...

Make sure to familiarize yourself with that document before deploying your app.

After getting a positive response from Apple, open the developer portal panel and search Certificates, Identifiers & Profiles -> Profiles -> Our distribution profile -> Edit and add the ApplePay In-App Provisioning Distribution entitlement. It’s available only for the production environment so your QA must work with physical devices and cards.

Add com.apple.developer.payment-pass-provisioning entitlement to your project. Find or create .entitlements file in your project and add the entitlement like below (similarly to WalletExample.entitlements):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	...
	 <!-- In-App Provisioning special entitlement-->
	<key>com.apple.developer.payment-pass-provisioning</key>
	<true/>
</dict>
</plist>

After completing the setup from the section above, install the react-native-wallet package from npm:

npm install @expensify/react-native-wallet

or

yarn add @expensify/react-native-wallet

To use @expensify/react-native-wallet with expo, you will need to use the expo-plugin.

In your app.json file, add the following configuration:

{
  "expo": {
    "plugins": [
      [
  			"@expensify/react-native-wallet",
  			{
  				enableApplePayProvisioning: true,
  				googleTapAndPaySdkPath: "./libs/tapandpay-v18.10.1.zip", // path to the Google Tap & Pay SDK zip file
  			},
      ],
    ]
  }
}

You will need to rebuild your app after that since the lib has native files.

npx expo prebuild --clean
npx expo run:ios
npx expo run:android

Here you can find data elements used in the library, essential to work with Google Wallet and Apple Wallet APIs.

• Opaque Payment Card (OPC) - a binary blob of information Google Pay receives from the issuer app that could be presented to TSP to receive a token.
• Google Opaque Payment Card (Google OPC) - an encrypted version of the OPC required for UAPP (Unified Android Push Provisioning) flow. This is generated by your backend using Google's encryption keys during the provisioning process. Learn more about UAPP →
• Token Service Provider (TSP) - a service that enhances payment security by replacing a credit card number during transactions with a unique digital identifier - token. The TSP specifies the tokenization service used to create a given token e.g. Visa, MasterCard, American Express.
• Token Reference ID - a unique identifying number to refer to a DPAN (Dynamic Personal Account Number). Token Providers will assign each DPAN an issuer token ID at the time of tokenization.

• Nonce - a one-time nonce value generated by Apple’s servers. This nonce must be included in the add payment request’s encrypted data.
• Nonce Signature - the device-specific signature for the nonce. This signature must be included in the add payment request’s encrypted data.
• Certificates - an array of NSData objects. Each object contains a DER encoded X.509 certificate, with the leaf first and root last. You must download the root CA to validate the entire chain.
• Encrypted Pass Data- an encrypted JSON file containing the sensitive information needed to add a card to Apple Pay (Base 64 encoded). More details here.
• Ephemeral Public Key - a key used by elliptic curve cryptography (ECC) (Base 64 encoded).
• Primary Account Identifier - an opaque issuer id (also called the FPAN ID) that PassKit uses to recognize the same card across reissues and devices. Pass it in IOSCardData and to canAddCardToAppleWallet. getCardStatusByIdentifier matches this value exactly and does not fall back. addCardToAppleWallet, the inferred deviceType, and canAddCardToAppleWallet when you also pass lastDigits share one lookup: an exact id match wins, and otherwise the library uses the id of the only pass that is not deactivated and has the same last digits. A different card that is still active and ends in the same digits can be picked. Pass the id PassKit stored on the pass (the primaryAccountIdentifier from listAppleWalletPasses) to skip that lookup.
• Device type - the device the card is being provisioned to: phone or watch. PassKit does not report the device the user selected, so the library infers it from where the card is already provisioned. When it cannot tell, the value is unknown.

The library offers functions for seamless integration and use of the Apple Wallet and Google Wallet APIs. Additionally, it includes listeners and handlers for managing provisioning events. Below, these functions are described along with the data types involved.

addCardToAppleWallet resolves IOSAddCardResult instead of TokenizationStatus. Read result.status.

A Wallet decline resolves { status: 'error', errorDomain, errorCode } instead of rejecting. A cancel after the issuer step resolves { status: 'canceled' } instead of rejecting. An error thrown by the issuer callback still rejects, and the Add Payment Pass sheet is closed.

The AndroidCardData type includes two optional boolean fields that provide additional information about the card being provisioned:

Indicates whether the card being provisioned is a virtual card. Virtual cards are digitally-generated card numbers that are linked to a physical card account. They provide enhanced security by:

• Allowing users to make online purchases without exposing their physical card number
• Enabling easy cancellation and regeneration without affecting the physical card
• Providing transaction-specific or merchant-specific card numbers

When set to true, this flag informs Google Wallet that the card being provisioned is a virtual card, which may affect how the card is displayed and managed in the wallet interface.

Indicates whether the card has been provisioned through "bounce provisioning". Bounce provisioning is a two-step provisioning flow where:

1. The user initially provisions a card directly through Google Wallet (outside your app)
2. Your app later "bounces" or redirects the user back to complete additional verification or setup steps

This flag helps Google Wallet track cards that were initially added through the Google Wallet app but require additional app-specific configuration or verification. When set to true, it signals that this card was previously provisioned through the Google Wallet interface and is now being completed or updated through your application.

A ready-to-use component that simplifies the addition of payment cards to Google Wallet and Apple Wallet. The button automatically adapts its appearance according to the platform and language specified. It uses official assets provided by Google and Apple in their Wallet-related branding guidelines.

Adhering to these guidelines is crucial not only to comply with legal requirements but also to reassure users of the authenticity and security of your application.

<AddToWalletButton
	onPress={() => console.log('Button pressed!')}
	style={styles.longButton}
	buttonStyle="blackOutline"
	buttonType="badge"
	borderRadius={4}
/>

Android	iOS

This library use base64 encoding to encode the data. Yours might use hex encoding.

If that is the case, you will need to convert the data in the proper format.

This is an example of how to convert data to hex format:

import { Buffer } from "buffer"
const base64ToHex = (base64: string): string => Buffer.from(base64, "base64").toString("hex")

[...]

	const issuerEncryptPayloadCallback = async (
		nonce: string,
		nonceSignature: string,
		certificate: string[],
		deviceType: IOSDeviceType,
	): Promise<IOSEncryptPayload> => {
		try {
			const payload = {
				encryptionDetails: {
					nonce: base64ToHex(nonce),
					nonceSignature: base64ToHex(nonceSignature),
					wspCertificates: certificate,
				},
				deviceType,
				serialNumber,
				wspId: "APPLE" as const,
			}
[...]

This will depend on the implementation of your backend/issuer so make sure to check with them otherwise IOS might fail to provision the card.

For Android applications that require enhanced security for card provisioning, this library supports UAPP (Unified Android Push Provisioning) flow with Google Wallet.

📖 Read the complete UAPP documentation →

The UAPP guide covers:

• What UAPP is and how it works
• Step-by-step setup instructions
• Backend implementation requirements
• Error handling and troubleshooting
• Complete code examples

To successfully publish your app, you will need to navigate through a series of mandatory test cases on both platforms.

Before deploying your app to the Google Play Store, make sure you have taken care of the security when implementing Push Provisioning and properly tested your code. To accomplish it, please familiarize yourself with the Google's App Push Provisioning best practices.

The latest information about deploying apps with Google TapAndPay SDK can be found in the pre-launch process and beta tests sections in Google documentation. Make sure to complete all of the steps specified by Google connected to the Google's branding, API safety, and app stability.

The app will need to be reviewed by Google. During this process, it will need to pass 4 mandatory test cases that are specified in the official Google testing documentation. They verify how your app handles card state tracking in different scenarios.

Key testing criteria include:

• Proper handling of card states (active, pending, suspended, etc.)
• Correct UI behavior when cards are already provisioned
• Secure handling of sensitive payment data
• Compliance with Google's branding guidelines
• Proper error handling and user feedback

Please refer to the complete testing criteria documentation before submitting your app for review.

When implementing the In-App Push Provisioning feature in your App make sure that your app follows Apple's branding guidelines connected to Apple Wallet. Remember that you must not create your own buttons or your app could be rejected at revision. You can use the AddWalletButton component instead! Keep the Add to Apple Wallet button visible while canAddCardToAppleWallet(primaryAccountIdentifier, lastDigits) returns true, including after the card is added to the iPhone but not yet to a paired Apple Watch. Show text like Added to Apple Wallet only once that call returns false. Pass primaryAccountIdentifier in IOSCardData so the next attempt targets the remaining device, and pass the same lastDigits to both calls so they agree. This matches Apple's in-app provisioning guidance.

Next to branding guidelines, please follow the instructions and best practices from the In-App provisioning documentation provided by Apple.

The In-App Provisioning feature must be reviewed and verified by Apple's certification team before submitting your app to the App Store. Below are some key scenarios that may be tested during the review process:

• Enrolling a card into Apple Wallet
• Enrolling a card into the Apple Watch
• Attempting to enroll a card that has already been added via the Wallet app
• Manually adding a card using its IBAN
• Adding multiple cards from the same issuer
• Adding and removing the same card
• Handling an incoming call during the provisioning process
• ...

Apple may request a demonstration of certain test scenarios, such as verifying the ability to add up to twenty different cards for a single user. Be prepared to provide validation for such cases.

Additionally, when submitting your app to the App Store, you must include:

• A demo account for testing.
• A demo video showcasing the In-App Provisioning experience.

@expensify/react-native-wallet is compatible with the five latest minor releases of React Native (≥0.76.0) and works exclusively with the new architecture.

Contributions to this library are done under https://github.com/Expensify/App. Please refer to that repo and all its guidelines for contributing.

MIT

This library is co-developed by Expensify, the fastest way to do expenses, travel, and corporate cards, in collaboration with Software Mansion, React Native core contributors and experts in building high-performing mobile solutions.