Skip to main content

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:

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

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

Classes

Interfaces

Type aliases


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:

NameTypeDescription
optionsAddPassOptionsThe 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.

NameType
primaryAccountIdentifierstring

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

Ƭ ActivationState: "activated" | "activating" | "suspended" | "deactivated" | "requires-activation" | "unknown"

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

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.