Apple Payment Pass

This plugin provides support for adding credit/debit cards to Apple Wallet. It also can check if the credit/debit card exists in Wallet.

Important Note

Adding payment passes requires a special entitlement issued by Apple. Your app must include this entitlement before you can use this class. For more information on requesting this entitlement, see the Card Issuers section at https://developer.apple.com/apple-pay/.

Installation

If you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.

Next, install the plugin:

Capacitor
Cordova

npm install @ionic-enterprise/apple-payment-pass
npx cap sync

ionic cordova plugin add @ionic-enterprise/apple-payment-pass

Usage

Angular

...
import { Platform } from '@ionic/angular';
import { ApplePaymentPass, RequestTemplate } from '@ionic-enterprise/apple-payment-pass/ngx';
...

class MyService {
  constructor(private platform: Platform, private paypass: ApplePaymentPass) { }

  addCardToWallet() {
    try {
      const response = await this.paypass.addPaymentPass({
        userId: 1,
        appleWalletData: {
          certificates: [
            RequestTemplate.CERTIFICATE_0,
            RequestTemplate.CERTIFICATE_1,
          ],
          nonce: RequestTemplate.NONCE,
          nonceSignature: RequestTemplate.NONCE_SIGNATURE
      },
    });
  } catch (e) {
    if (e.type === "ServerError") {
      console.error(`Server Responded with status: ${e.statusCode} and body ${e.body}`);
    }
  }
}

ES2015+/Typescript

...
import { ApplePaymentPass, RequestTemplate } from '@ionic-enterprise/apple-payment-pass';
...

try {
  const response = await ApplePaymentPass.addPaymentPass({
    userId: 1,
    appleWalletData: {
      certificates: [
        RequestTemplate.CERTIFICATE_0,
        RequestTemplate.CERTIFICATE_1,
      ],
      nonce: RequestTemplate.NONCE,
      nonceSignature: RequestTemplate.NONCE_SIGNATURE
    },
  });
} catch (e) {
  if (e.type === "ServerError") {
    console.error(`Server Responded with status: ${e.statusCode} and body ${e.body}`);
  }
}

Vanilla JS

ApplePaymentPass.addPaymentPass({
  userId: 1,
  appleWalletData: {
    certificates: [
      ApplePaymentPass.template.CERTIFICATE_0,
      ApplePaymentPass.template.CERTIFICATE_1,
    ],
    nonce: ApplePaymentPass.template.NONCE,
    nonceSignature: ApplePaymentPass.template.NONCE_SIGNATURE
  },
}).then( (cardStatus) => { console.log("Success Adding Card: ", cardStatus); })
  .catch( (e) => {
    if (e.type === "ServerError") {
      console.error(`Server Responded with status: ${e.statusCode} and body ${e.body}`);
    }
  });

Card Addition

Call with the configuration data needed to instantiate a new PKAddPaymentPassViewController object and complete the HTTP request to do the handshake with your server.

This method provides the data needed to create a request to add your payment pass (credit/debit card).

    const card = {
      cardholderName: 'Test User',
      primaryAccountSuffix: '1234',
      localizedDescription: 'Description of payment card',
      paymentNetwork: 'VISA'
    }
    const options = {
      headers: {
        'Authorization': 'Bearer xxxxxx',
        'Content-Type': 'application/json'
      },
      url: 'https://my.api.com/v1/cards',
      method: 'POST',
      // This is a hybrid template with the data you need prefilled
      // and the ApplePaymentPass.CONSTANTS will be filled in during the handshake.
      body: {
        userId: 1,
        appleWalletData: {
          certificates: [
            ApplePaymentPass.CERTIFICATE_0,
            ApplePaymentPass.CERTIFICATE_1,
          ],
          nonce: ApplePaymentPass.NONCE,
          nonceSignature: ApplePaymentPass.NONCE_SIGNATURE
        },
      },
      card: card,
    };

    const passData = await ApplePaymentPass.addPaymentPass(options);

API Response

The response from your API is expected to be valid JSON with 3 fields in the body (activationData, encyptedPassData, ephemeralPublicKey). These are the fields expected by the PKAddPaymentPassRequest that iOS requires be used to add the card to the wallet.

// expected response
{
    "activationData": "xxxx",
    "encryptedPassData": "xxxx",
    "ephemeralPublicKey": "xxxx",
}

Index

Enumerations

RequestTemplate

RequestTemplate:

Constants used to define the shape of the body used during the request to the server

CERTIFICATE_0

CERTIFICATE_0: = "$certificates.0"

Constant used in the body template that represents the first item in the certificates array returned by the PKAddPaymentPassViewController.

CERTIFICATE_1

CERTIFICATE_1: = "$certificates.1"

Constant used in the body template that represents the second item in the certificates array returned by the PKAddPaymentPassViewController.

NONCE

NONCE: = "$nonceString"

Constant used in the body template that represents the nonce returned by the PKAddPaymentPassViewController.

NONCE_SIGNATURE

NONCE_SIGNATURE: = "$nonceSignature"

Constant used in the body template that represents the nonceSignature returned by the PKAddPaymentPassViewController.

Classes

ApplePaymentPass

ApplePaymentPass:

This plugin provides support for adding credit/debit cards to Apple Wallet. It also can check if the credit/debit card exists in Wallet.

template

● template: RequestTemplate = RequestTemplate

addPaymentPass

▸ addPaymentPass(options: AddPassOptions): Promise<AddPassResponse>

This function accepts both the card data and information required to make the http request to the server in order to use PKAddPaymentPassViewController object to add a payment pass to the apple wallet.

throws: * ServerError DelegateError

Parameters:

Name	Type	Description
options	AddPassOptions	The AddPassOptions object to configure the PKAddPaymentPassViewController and setup the call to the server.

Returns: Promise<AddPassResponse>

An object with the pass information

available

▸ available(): Promise<boolean>

A function to determine if the current device supports adding a payment pass

Returns: Promise<boolean> whether or not a pay pass can be added

availableProvider

▸ availableProvider(options: object): Promise<boolean>

A function to determine if the card has already been provisioned for the device.

Parameters:

options: object

An object with the primary account identifier for the card.

Name	Type
primaryAccountIdentifier	`string`

Returns: Promise<boolean> whether or not a pay can be added, throws an error if the card is already added

Interfaces

AddPassOptions

AddPassOptions:

The options interface to pass to the addPaymentPass function.

body

● body: any

A templated request body to send to your server. include any additional fields and use the constansts CERTIFICATE_0, CERTIFICATE_1, NONCE, NONCE_SIGNATURE

usage:

const body = {
 userId: 1,
 cardId: 'xxxxx',
 appleWalletData: {
   certs: [
     RequestTemplate.CERTIFICATE_0,
     RequestTemplate.CERTIFICATE_1
   ],
   nonce: RequestTemplate.NONCE,
   nonceSignature: RequestTemplate.NONCE_SIGNATURE,
 }
}

card

● card: CardData

The card data

headers

● headers: Headers

An object with the headers required for the server request.

method

● method: string

The HTTP method to use ex. POST

url

● url: string

The url to hit ex. https://my.api.com/v1/add/applepay/card

AddPassResponse

AddPassResponse:

The response from adding the pass with the pass data

activationState

● activationState: ActivationState

The activation state of the card

deviceAccountIdentifier

● deviceAccountIdentifier: string

The device account identifier.

deviceAccountNumberSuffix

● deviceAccountNumberSuffix: string

The device account number suffix

deviceName

● deviceName: string

The device name.

primaryAccountIdentifier

● primaryAccountIdentifier: string

The primary account identifier

primaryAccountNumberSuffix

● primaryAccountNumberSuffix: string

The primary account number suffix

CardData

CardData:

The card data for the PKAddPaymentPassViewController

`<Optional>` cardholderName

● cardholderName: undefined | string

The cardholder name

`<Optional>` localizedDescription

● localizedDescription: undefined | string

A short description of the card.

`<Optional>` paymentNetwork

● paymentNetwork: undefined | string

Filters the networks shown in the introduction view to this single network. ex.VISA \| MASTERCARD

`<Optional>` primaryAccountIdentifier

● primaryAccountIdentifier: undefined | string

Filters the device and attached devices that already have this card provisioned. No filter is applied if the parameter is omitted

`<Optional>` primaryAccountSuffix

● primaryAccountSuffix: undefined | string

Last 4/5 digits of PAN. The last four or five digits of the PAN. Presented to the user with dots prepended to indicate that it is a suffix.

DelegateError

DelegateError:

Error thrown by addPaymentPass when the PKAddPaymentPassViewController fails to add the card to the wallet

body

● body: object

The error message

Type declaration

message: string

statusCode

● statusCode: number

The error code

type

● type: "DelegateError"

The type of the error

Headers

Headers:

An object with the headers required for the server request.

usage:

const headers = {
'Authorization': 'Bearer xxxxx',
'Content-Type': 'application/json',
...
}

ServerError

ServerError:

Error thrown by addPaymentPass when server responds with a HTTP status code >= 400

body

● body: any

The body return by the server

statusCode

● statusCode: number

The status code returned from the server

type

● type: "ServerError"

The type of the error

Type aliases

ActivationState

The activation state of the provisioned card

Change Log

[1.1.0] (2020-07-28)

Features

support for Angular Ivy

[1.0.2] (2019-04-27)

Bug Fixes

Fixed issue where cordova plugin id was being incorrectly set by release script.

[1.0.0] (2019-04-27)

Bug Fixes

iOS: Fix issues where nonce string could be incorrectly replaced and errors from server weren't properly handled

Features

Added typed imports for Angular, ES2015+/Typescript, and Vanilla JS , closes [#es2015]

BREAKING CHANGES

Changed package name from @ionic-enterprise/apple-wallet to @ionic-enterprise/apple-payment-pass and the main class from AppleWallet to ApplePaymentPass. See updated usage docs.

Important Note

Installation​

Usage​

Angular​

ES2015+/Typescript​

Vanilla JS​

Card Addition​

API Response​

Index​

Enumerations​

Classes​

Interfaces​

Type aliases​

Enumerations​

RequestTemplate​

CERTIFICATE_0​

CERTIFICATE_1​

NONCE​

NONCE_SIGNATURE​

Classes​

ApplePaymentPass​

template​

addPaymentPass​

available​

availableProvider​

Interfaces​

AddPassOptions​

body​

card​

headers​

method​

url​

AddPassResponse​

activationState​

deviceAccountIdentifier​

deviceAccountNumberSuffix​

deviceName​

primaryAccountIdentifier​

primaryAccountNumberSuffix​

CardData​

<Optional> cardholderName​

<Optional> localizedDescription​

<Optional> paymentNetwork​

<Optional> primaryAccountIdentifier​

<Optional> primaryAccountSuffix​

DelegateError​

body​

Type declaration​

statusCode​

type​

Headers​

ServerError​

body​

statusCode​

type​

Type aliases​

ActivationState​

Change Log​

[1.1.0] (2020-07-28)​

Features​

[1.0.2] (2019-04-27)​

Bug Fixes​

[1.0.0] (2019-04-27)​

Bug Fixes​

Features​

BREAKING CHANGES​

Installation

Usage

Angular

ES2015+/Typescript

Vanilla JS

Card Addition

API Response

Index

Enumerations

Classes

Interfaces

Type aliases

Enumerations

RequestTemplate

CERTIFICATE_0

CERTIFICATE_1

NONCE

NONCE_SIGNATURE

Classes

ApplePaymentPass

template

addPaymentPass

available

availableProvider

Interfaces

AddPassOptions

body

card

headers

method

url

AddPassResponse

activationState

deviceAccountIdentifier

deviceAccountNumberSuffix

deviceName

primaryAccountIdentifier

primaryAccountNumberSuffix

CardData

`<Optional>` cardholderName

`<Optional>` localizedDescription

`<Optional>` paymentNetwork

`<Optional>` primaryAccountIdentifier

`<Optional>` primaryAccountSuffix

DelegateError

body

Type declaration

statusCode

type

Headers

ServerError

body

statusCode

type

Type aliases

ActivationState

Change Log

[1.1.0] (2020-07-28)

Features

[1.0.2] (2019-04-27)

Bug Fixes

[1.0.0] (2019-04-27)

Bug Fixes

Features

BREAKING CHANGES