capacitor-apple-wallet

In-App Provisioning payment cards within an app, without having to go through the process of manually entering payment card details.

Install

npm install capacitor-apple-wallet
npx cap sync

Quick Example

import { AppleWallet } from 'capacitor-apple-wallet';

const status = await AppleWallet.isTokenized({
  primaryAccountIdentifier: '6854707',
});

if (status.isTokenized) {
  console.log('Card is already available in Apple Wallet');
}

API

• startProvisioning(...)
• completeProvisioning(...)
• cancelProvisioning(...)
• isTokenized(...)
• syncExtensionState(...)
• clearExtensionState()
• getExtensionAuthToken()
• addListener('walletProvisioningData', ...)
• removeAllListeners()
• getButtonText()
• checkWalletStatus()
• addPass(...)
• Interfaces
• Type Aliases
• Enums

startProvisioning(...)

startProvisioning(options: StartProvisioningOptions) => Promise<AddCardResult>

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | StartProvisioningOptions |

Returns: Promise<AddCardResult>

completeProvisioning(...)

completeProvisioning(options: CompleteProvisioningOptions) => Promise<void>

| Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | options | CompleteProvisioningOptions |

cancelProvisioning(...)

cancelProvisioning(options?: CancelProvisioningOptions | undefined) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | CancelProvisioningOptions |

isTokenized(...)

isTokenized(options: IsTokenizedOptions) => Promise<IsTokenizedResult>

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | IsTokenizedOptions |

Returns: Promise<IsTokenizedResult>

syncExtensionState(...)

syncExtensionState(options: { state: AppleWalletExtensionState; }) => Promise<SyncExtensionStateResult>

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------- | | options | { state: AppleWalletExtensionState; } |

Returns: Promise<SyncExtensionStateResult>

clearExtensionState()

clearExtensionState() => Promise<void>

getExtensionAuthToken()

getExtensionAuthToken() => Promise<GetExtensionAuthTokenResult>

Returns: Promise<GetExtensionAuthTokenResult>

addListener('walletProvisioningData', ...)

addListener(eventName: 'walletProvisioningData', listenerFunc: (event: ProvisioningDataEvent) => void) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------- | | eventName | 'walletProvisioningData' | | listenerFunc | (event: ProvisioningDataEvent) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

getButtonText()

getButtonText() => Promise<{ value: string; }>

Returns: Promise<{ value: string; }>

checkWalletStatus()

checkWalletStatus() => Promise<CheckWalletStatusResult>

Returns: Promise<CheckWalletStatusResult>

addPass(...)

addPass(options: AddPassOptions) => Promise<AddPassResult>

| Param | Type | | ------------- | --------------------------------------------------------- | | options | AddPassOptions |

Returns: Promise<AddPassResult>

Interfaces

AddCardResult

| Prop | Type | | -------------------------------- | ---------------------------------- | | status | 'added' | 'canceled' | | primaryAccountIdentifier | string | | primaryAccountNumberSuffix | string | | deviceAccountIdentifier | string | | deviceAccountNumberSuffix | string |

StartProvisioningOptions

| Prop | Type | | ------------------------------ | --------------------------------------------------------- | | primaryAccountSuffix | string | | cardholderName | string | | cardId | string | | paymentNetwork | PaymentNetwork | | primaryAccountIdentifier | string | | localizedDescription | string |

CompleteProvisioningOptions

| Prop | Type | | ------------------------ | ------------------- | | activationData | string | | encryptedPassData | string | | ephemeralPublicKey | string |

CancelProvisioningOptions

| Prop | Type | | ------------ | ------------------- | | reason | string |

IsTokenizedResult

| Prop | Type | | ----------------- | -------------------- | | isTokenized | boolean |

IsTokenizedOptions

| Prop | Type | | ------------------------------ | -------------------- | | primaryAccountIdentifier | string | | includeRemote | boolean |

SyncExtensionStateResult

| Prop | Type | | ----------- | ------------------------- | | cards | WalletCard[] |

WalletCard

| Prop | Type | | -------------------------------- | -------------------- | | primaryAccountIdentifier | string | | primaryAccountNumberSuffix | string | | deviceAccountIdentifier | string | | deviceAccountNumberSuffix | string | | isRemote | boolean |

AppleWalletExtensionState

| Prop | Type | | --------------- | ----------------------------------------------------------------------------------- | | session | AppleWalletExtensionSession | | updatedAt | number |

AppleWalletExtensionSession

| Prop | Type | | ------------------------ | ------------------- | | extensionAuthToken | string | | lang | string | | deviceId | string | | securedToken | string |

GetExtensionAuthTokenResult

| Prop | Type | | ------------------------ | ------------------- | | extensionAuthToken | string |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

ProvisioningDataEvent

| Prop | Type | | ------------------------------ | --------------------- | | primaryAccountIdentifier | string | | cardId | string | | certificates | string[] | | nonce | string | | nonceSignature | string |

CheckWalletStatusResult

| Prop | Type | | ----------------- | ---------------------------------- | | iphone | AppleWalletCardData[] | | watch | AppleWalletCardData[] | | watchPaired | boolean |

AppleWalletCardData

| Prop | Type | | -------------------------------- | ------------------------------------------------------------- | | serialNumber | number | | primaryAccountIdentifier | string | | primaryAccountNumberSuffix | number | | activationState | ACTIVATION_STATE | | deviceName | string |

AddPassResult

| Prop | Type | | ------------------------ | ---------------------------------- | | status | 'added' | 'canceled' | | serialNumber | string | | passTypeIdentifier | string |

AddPassOptions

| Prop | Type | Description | | -------------- | ------------------- | ------------------------------------------------- | | passData | string | Base64-encoded contents of a signed .pkpass file. |

Type Aliases

ACTIVATION_STATE

'ACTIVATED' | 'REQUIRES_ACTIVATION' | 'SUSPENDED' | 'DEACTIVATED' | 'INACTIVE'

Enums

PaymentNetwork

| Members | | ------------------ | | interac | | JCB | | mada | | maestro | | masterCard | | mir | | privateLabel | | quicPay | | suica | | visa | | vPay | | barcode | | girocard | | waon | | nanaco | | postFinance | | tmoney |

Adding .pkpass

addPass accepts a ready-made, signed .pkpass file encoded as base64. Apple Wallet does not accept the raw JSON payload directly, so the pass package must be assembled and signed on your backend first.

import { AppleWallet } from 'capacitor-apple-wallet';

await AppleWallet.addPass({
  passData: pkpassBase64,
});

What backend should build

Your backend should build a .pkpass archive with at least these files:

• pass.json
• icon.png
• [email protected]
• logo.png and [email protected] if you want a header logo
• manifest.json
• signature

The high-level flow is:

1. Build pass.json.
2. Add required images.
3. Compute SHA-1 hashes for every file and write them to manifest.json.
4. Sign manifest.json with your Apple Wallet Pass Type ID certificate.
5. Zip the files into a .pkpass.
6. Return the .pkpass bytes as base64 to the app.

Example pass.json

This is a minimal generic pass with a QR code:

{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.yourcompany.app",
  "serialNumber": "1234567890",
  "teamIdentifier": "YOUR_TEAM_ID",
  "organizationName": "Your Company",
  "description": "QR Pass",
  "logoText": "Your App",
  "foregroundColor": "rgb(255,255,255)",
  "backgroundColor": "rgb(0,0,0)",
  "barcode": {
    "message": "https://your-link-or-data",
    "format": "PKBarcodeFormatQR",
    "messageEncoding": "iso-8859-1"
  },
  "generic": {
    "primaryFields": [
      {
        "key": "title",
        "label": "QR",
        "value": "Scan me"
      }
    ]
  }
}

Notes:

• passTypeIdentifier must match the Pass Type ID certificate used to sign the pass.
• teamIdentifier must be your Apple Developer Team ID.
• serialNumber must uniquely identify this pass within that passTypeIdentifier.
• For new projects, Apple documents pass creation under Wallet Passes: Building a Pass, Creating a generic pass, Create Wallet identifiers and certificates.

How to get the Apple Wallet certificate

Apple requires a dedicated certificate for signing Wallet passes.

1. Sign in to your Apple Developer account.
2. Open Certificates, Identifiers & Profiles.
3. Create a new Pass Type ID, for example pass.com.yourcompany.app.
4. Create a new certificate of type Pass Type ID Certificate.
5. During certificate creation, upload a CSR file.
6. Download the generated .cer certificate from Apple.

Official Apple instructions: Create Wallet identifiers and certificates

How to get the private key

The private key is created on the machine where you generated the CSR.

Typical flow on macOS:

1. Open Keychain Access.
2. Create a Certificate Signing Request from Keychain Access.
3. Finish certificate issuance in Apple Developer and download the .cer.
4. Double-click the downloaded .cer to import it into Keychain.
5. In Keychain Access, find the imported Pass Type ID certificate and expand it.
6. You should see the matching private key under that certificate.
7. Export the certificate together with the private key as .p12.

Your backend will usually use:

• pass certificate as .pem or .p12
• private key from that certificate export
• WWDR intermediate certificate from Apple

In practice, many backend libraries expect one of these setups:

• a .p12 file plus its password
• or extracted .pem certificate and .pem private key

What the app receives

Once the backend has generated and signed the pass, it should return either:

• raw .pkpass bytes encoded as base64
• or a downloadable .pkpass file that your app converts to base64 before calling the plugin

Then call:

await AppleWallet.addPass({
  passData: pkpassBase64,
});