@belongnet/capacitor-pass-to-wallet

Capacitor plugin to add .pkpass files to Apple Wallet.

Overview

Adds .pkpass files to Apple Wallet from a Capacitor app, using either base64 content or a local file URI.

• addToWallet for a single pass
• addMultipleToWallet for multiple passes
• passExists to check whether a pass is already in Wallet

Quick start

bun add @belongnet/capacitor-pass-to-wallet
bunx cap sync

Basic usage

For step-by-step tutorials, see Adding Apple Wallet Passes and Creating Apple Wallet Passes.

Add pass from base64

import { CapacitorPassToWallet } from '@belongnet/capacitor-pass-to-wallet';

await CapacitorPassToWallet.addToWallet({
  base64: passBase64,
});

Add pass from local file

import { Filesystem, Directory } from '@capacitor/filesystem';
import { CapacitorPassToWallet } from '@belongnet/capacitor-pass-to-wallet';

const { uri } = await Filesystem.getUri({
  directory: Directory.Cache,
  path: 'passes/example.pkpass',
});

await CapacitorPassToWallet.addToWallet({
  filePath: uri,
});

Add multiple passes

// base64 mode
await CapacitorPassToWallet.addMultipleToWallet({
  base64: [base64Pass1, base64Pass2],
});

// file mode
await CapacitorPassToWallet.addMultipleToWallet({
  filePaths: [uri1, uri2],
});

Check if pass already exists

const result = await CapacitorPassToWallet.passExists({
  filePath: uri,
});

console.log(result.passExists);

[!NOTE] iOS is implemented. Android implementation in this repository is currently a placeholder.

Compatibility

| Capacitor Version | Plugin Version | | ----------------- | -------------- | | 7.x | package (v7) | | 8.x | 8.x |

Requirements (Capacitor 8)

• @capacitor/core >=8.0.0
• iOS deployment target: 15.0+
• Android minSdkVersion: 24+
• Android build defaults in this plugin: compileSdkVersion 36, targetSdkVersion 36, Java 21

References

• atroo/capacitor-pass-to-wallet — Capacitor 7.x fork (@atroo/capacitor-pass-to-wallet).
• NitnelavAH/capacitor-pass-to-wallet — original plugin (Capacitor 4–7).

API

• addToWallet(...)
• addMultipleToWallet(...)
• passExists(...)
• _experimental_passExistsById(...)
• _experimental_canAddPasses()
• _experimental_openPassInWallet(...)
• _experimental_removePass(...)
• _experimental_listPasses()
• Interfaces

addToWallet(...)

addToWallet(options: AddToWalletOptions) => Promise<AddToWalletResult>

Opens Apple Wallet sheet for a single .pkpass.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | AddToWalletOptions |

Returns: Promise<AddToWalletResult>

addMultipleToWallet(...)

addMultipleToWallet(options: AddMultipleToWalletOptions) => Promise<AddToWalletResult>

Opens Apple Wallet sheet for multiple .pkpass files.

| Param | Type | | ------------- | --------------------------------------------------------------------------------- | | options | AddMultipleToWalletOptions |

Returns: Promise<AddToWalletResult>

passExists(...)

passExists(options: AddToWalletOptions) => Promise<PassExistsResult>

Checks whether a pass already exists in Apple Wallet.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | AddToWalletOptions |

Returns: Promise<PassExistsResult>

_experimental_passExistsById(...)

_experimental_passExistsById(options: PassIdentifierOptions) => Promise<PassExistsResult>

Checks whether a pass exists by identifier and optional serial number.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | PassIdentifierOptions |

Returns: Promise<PassExistsResult>

_experimental_canAddPasses()

_experimental_canAddPasses() => Promise<CanAddPassesResult>

Returns whether device can add passes.

Returns: Promise<CanAddPassesResult>

_experimental_openPassInWallet(...)

_experimental_openPassInWallet(options: PassIdentifierOptions) => Promise<OpenPassInWalletResult>

Opens an existing pass in Apple Wallet by identifier.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | PassIdentifierOptions |

Returns: Promise<OpenPassInWalletResult>

_experimental_removePass(...)

_experimental_removePass(options: PassIdentifierOptions) => Promise<RemovePassResult>

Removes an existing pass from Apple Wallet by identifier.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | PassIdentifierOptions |

Returns: Promise<RemovePassResult>

_experimental_listPasses()

_experimental_listPasses() => Promise<ListPassesResult>

Lists wallet passes visible to the app.

Returns: Promise<ListPassesResult>

Interfaces

AddToWalletResult

| Prop | Type | Description | | ----------- | ------------------- | --------------------------------------------------------------------- | | value | string | Operation status. Returns "added" when the pass sheet is presented. |

AddToWalletOptions

| Prop | Type | Description | | -------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- | | base64 | string | Base64-encoded .pkpass file content. Optional when filePath is provided. | | filePath | string | Native file path/URI to a .pkpass file (for example from Filesystem.getUri). Optional when base64 is provided. |

AddMultipleToWalletOptions

| Prop | Type | Description | | --------------- | --------------------- | -------------------------------------------------------------------------------------- | | base64 | string[] | List of base64-encoded .pkpass file contents. Optional when filePaths is provided. | | filePaths | string[] | List of native file paths/URIs to .pkpass files. Optional when base64 is provided. |

PassExistsResult

| Prop | Type | Description | | ---------------- | -------------------- | -------------------------------------------------------- | | passExists | boolean | true if the pass is already available in Apple Wallet. |

PassIdentifierOptions

| Prop | Type | Description | | ------------------------ | ------------------- | ------------------------------------------------------------------------ | | passTypeIdentifier | string | Wallet pass type identifier (for example pass.com.example.membership). | | serialNumber | string | Optional serial number to target a specific pass instance. |

CanAddPassesResult

| Prop | Type | Description | | ------------------ | -------------------- | ------------------------------------------------------ | | canAddPasses | boolean | true when the device can present add-to-wallet flow. |

OpenPassInWalletResult

| Prop | Type | Description | | ------------ | -------------------- | ------------------------------------------------------------------ | | opened | boolean | true when a matching pass was found and open action was started. |

RemovePassResult

| Prop | Type | Description | | ------------- | -------------------- | ---------------------------------------------------- | | removed | boolean | true when a matching pass was removed from wallet. |

ListPassesResult

| Prop | Type | Description | | ------------ | -------------------------------- | ----------------------------------------------- | | passes | WalletPassSummary[] | Passes currently visible in the wallet library. |

WalletPassSummary

| Prop | Type | Description | | ------------------------ | ------------------- | ------------------------------------------------------------------------ | | passTypeIdentifier | string | Wallet pass type identifier (for example pass.com.example.membership). | | serialNumber | string | Pass serial number. | | organizationName | string | Organization name from pass payload when available. |

License: MIT