A React Native library for integrating with Apple Wallet (iOS) and Google Wallet (Android), providing a unified API for adding passes to mobile wallets.

• Cross-platform - Apple Wallet (iOS) and Google Wallet (Android) under a unified TypeScript API.
• Input validation - Pass data is validated at the JS layer before reaching native code; invalid inputs fail fast with stable error codes.
• Native UI components - Platform-specific "Add to Wallet" buttons (PKAddPassButton on iOS, the official Google Wallet button on Android) with localized branding.
• Event handling - Subscribe to AddPassCompleted to learn the outcome of an add-pass flow.
• Multiple passes on iOS - addPasses presents multiple .pkpass files in a single Apple Wallet sheet. Google Wallet accepts a single combined JWT per call; see Platform Differences.
• Stable error taxonomy - A single set of error codes (INVALID_PASS, ERR_WALLET_NOT_AVAILABLE, ERR_WALLET_UNKNOWN, etc.) shared across platforms; see Error Codes. User cancellation is reported through the AddPassCompleted event, not as a Promise rejection.

• API Reference — full API documentation.
• Usage Examples — code examples and patterns.
• Troubleshooting — common issues and solutions.

npm install @azizuysal/wallet-kit
# or
yarn add @azizuysal/wallet-kit

The 1.x series is a stabilization line focused on correctness, error handling, and input validation. It does not publish a formal React Native compatibility matrix — your React Native version determines the iOS and Android floors (see iOS Setup and Android Setup).

The 2.x series will introduce a tested compatibility matrix, published iOS/Android floors, a narrower peerDependencies range, and New Architecture support via TurboModule/Fabric. If you need a specific React Native version guarantee, pin to a 2.x release when it ships.

1. Run pod install in the ios directory
2. Add the Wallet capability to your app:
   • Open your project in Xcode
   • Select your project target
   • Go to "Signing & Capabilities" tab
   • Click "+ Capability"
   • Add "Wallet"

1. Ensure your app's minSdkVersion is compatible with the React Native version you use (React Native 0.74 requires minSdkVersion=23, 0.76+ requires minSdkVersion=24). @azizuysal/wallet-kit inherits the floor from your React Native version.
2. Add the following to your app's AndroidManifest.xml:

<application>
  <!-- Other configurations -->
  <meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />
</application>

import WalletKit, {
  WalletButton,
  WalletButtonStyle,
  createWalletEventEmitter,
  type WalletError,
} from '@azizuysal/wallet-kit';

// Check if device can add passes
const canAddPasses = await WalletKit.canAddPasses();
if (canAddPasses) {
  console.log('Device supports adding passes to wallet');
}

// Add a single pass
try {
  // For iOS: pass base64-encoded .pkpass file
  // For Android: pass JWT token string
  await WalletKit.addPass(passData);
  console.log('Pass addition UI shown');
} catch (error) {
  const walletError = error as WalletError;
  if (walletError.code === 'INVALID_PASS') {
    console.error('Pass data was rejected:', walletError.message);
  } else {
    console.error('Failed to present wallet sheet:', walletError);
  }
}
// User cancellation is reported via the AddPassCompleted event, not via a
// rejection. See the "Listening to Events" section below.

// Add multiple passes (iOS accepts any count; Android requires a single combined JWT)
try {
  await WalletKit.addPasses([pass1, pass2, pass3]);
} catch (error) {
  const walletError = error as WalletError;
  if (walletError.code === 'ERR_WALLET_MULTIPLE_NOT_SUPPORTED') {
    // Android: combine your passes into a single JWT server-side and call addPass instead.
  } else {
    console.error('Failed to add passes:', walletError);
  }
}

import { WalletButton, WalletButtonStyle } from '@azizuysal/wallet-kit';

function MyComponent() {
  const handleAddPass = async () => {
    try {
      await WalletKit.addPass(passData);
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <WalletButton
      style={{ width: 200, height: 48 }}
      addPassButtonStyle={WalletButtonStyle.primary}
      onPress={handleAddPass}
    />
  );
}

import { createWalletEventEmitter } from '@azizuysal/wallet-kit';

const eventEmitter = createWalletEventEmitter();

const subscription = eventEmitter.addListener(
  'AddPassCompleted',
  (success: boolean) => {
    console.log('Pass added successfully:', success);
  }
);

// Don't forget to remove the listener when done
subscription.remove();

For complete API documentation, see the API Reference.

All methods reject with an Error whose code property is one of:

• INVALID_PASS — Pass data is missing, empty, or not in a recognized wallet pass format (neither a base64-encoded .pkpass nor a JWT). This can be raised either by the JS layer (before the native call) or by the native layer.
• UNSUPPORTED_VERSION — The pass version is not supported (iOS only).

• ERR_WALLET_NOT_AVAILABLE — The wallet app is not available on the device.
• ERR_WALLET_ACTIVITY_NULL — Android only: no activity was attached when the call was made.

• ERR_WALLET_MULTIPLE_NOT_SUPPORTED — Android only: addPasses was called with more than one entry. The Google Wallet API only accepts a single JWT per call; combine multiple passes into one JWT on your server.
• ERR_WALLET_IN_PROGRESS — Android only: another add-pass call is already in flight. Wait for it to resolve or reject before issuing another.

• ERR_WALLET_UNKNOWN — An unexpected error occurred.

User cancellation is not reported as a Promise rejection on either platform. The addPass / addPasses promise resolves when the wallet sheet is presented; the final outcome (added vs. cancelled) is delivered via the AddPassCompleted event. See Listening to Events for the correct pattern.

iOS requires base64-encoded .pkpass files:

const passData = await RNFS.readFile('path/to/pass.pkpass', 'base64');

Android requires JWT tokens:

const passData = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';

The native buttons follow platform-specific design guidelines:

• iOS: Uses Apple's PKAddPassButton
• Android: Uses official Google Wallet button layouts

1. "The package doesn't seem to be linked"

   • Run cd ios && pod install
   • Rebuild the app

2. "Can't add passes"

   • Ensure Wallet capability is added in Xcode
   • Check that the device has Wallet app installed

1. "Google Wallet is not available"

   • Ensure Google Play Services is up to date
   • Check that the device has Google Wallet installed
   • Verify the meta-data is added to AndroidManifest.xml

2. "Activity is null"

   • Ensure you're calling the methods after the app is fully initialized

The example app includes sample .pkpass files in example/ios/Samples/ directory. These are automatically loaded when running the iOS example app.

To test the Android implementation, you will need to generate a signed JWT. For detailed instructions on how to generate a test JWT, please see the JWT Generation Guide.

Check the example directory for a complete working example with both iOS and Android implementations.

cd example
yarn install
cd ios && pod install && cd ..
yarn ios # or yarn android

Found a security vulnerability? Please refer to our security policy for reporting procedures.

See the contributing guide to learn how to contribute to the repository and the development workflow.

This package uses automated releases via GitHub Actions. See RELEASING.md for details on the release process.

MIT