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/.

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);

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

Usage#

Angular#

ES2015+/Typescript#

Vanilla JS#

Card Addition#

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#

`<Optional>` cardholderName#

`<Optional>` localizedDescription#

`<Optional>` paymentNetwork#

`<Optional>` primaryAccountIdentifier#

`<Optional>` primaryAccountSuffix#