Push provisioning to Apple Pay

Provisioning a card in Apple Pay requires your app to trigger the provisioning flow.

With Weavr Provisioning SDK, this process is simplified to 3 steps:

Initialize the SDK
Check the card status to avoid attempting to provision a card that is already provisioned
Trigger the provisioning flow via the AddToWalletButton or WPPComponents.beginPushProvisioning method.

Initialize the SDK

The first step is to initialize our Provisioning SDK by providing your UI key, obtained from the Weavr Portal.

WPPComponents.initialize(uiKey: "<MY UI KEY>")

Get the card status

Our Provisioning SDK exposes the method WPPComponents.getCardStatusInWallet(forCardWithLastFourDigits:, deviceType:) that can be used to check the status of a given card within the Apple Pay wallet of the device.

It takes the following as arguments: a String representing the last four digits of the payment card number and a DeviceType that specifies which device the state should be checked against. Note that it is possible to have a card provisioned in your iPhone, but not in your Apple Watch.

The DeviceType enumeration supports the following values:

phone - the card state query is performed on the device being used
watch - the card state query is performed on the user's Apple Watch
either - the card state query is performed on both the phone and the watch. The result is the more relevant state, with relevance determined in the following order: requiresActivation, notAdded, activating, deactivated, suspended and alreadyAdded. For example, if the Apple Watch has a notAdded state but the iPhone has requiresActivation, it returns requiresActivation. If the iPhone had activating, it would then return notAdded.

Specify .either from your app

We recommend specifying .either as the device type. This ensures the response, which indicates whether you need to show the Add to Wallet button, is in accordance with Apple's requirements.

In the scenario where both phone and watch are available and the user taps Add to Wallet, they are given the option to select the desired device in the flow provided by Apple.

The potential states a card can have are listed in the Card Status page.

The following snippet showcases how to use this method:

import WeavrPushProvisioning

let status = WPPComponents.getCardStatusInWallet(
    forCardWithLastFourDigits: "1234", // replace with the last four digits of your card
    deviceType: .either // .phone, or .watch
)

switch status {
case .notAdded:
    print("The card is not added, therefore it can be provisioned.")
case .alreadyAdded:
    print("The card is already added")
case .unavailable:
    print("Apple Wallet is unavailable on the device. E.g. it's a simulator or an old phone.")
case .requiresActivation:
    print("The card is added but requires activation. Should transition to `alreadyAdded`.")
case .activating:
    print("The card is added but it's still being activated. Should transition to `alreadyAdded`.")
case .suspended:
    print("The card is suspended as suspicious activity was detected from Apple.")
case .deactivated:
    print("The card is deactivated.")
case .unknown:
    print("Unknown state, should not happen")
}

Provisioning a card

There are two ways to trigger the provisioning of a card using our Provisioning SDK:

Using the AddToWalletButton
Using the programmatic interface

Provision a card with `AddToWalletButton`

AddToWalletButton is a UI component that launches the push provisioning process, and adheres to Apple's brand guidelines.

note

The button should only be shown when a card can be added to Apple Pay. Follow Get the card status, and check that the status is in one of the .notAdded, or .requiresActivation states.

If the card is in other states, you should hide the AddToWalletButton and give feedback to the user as to the state of the card within Apple Pay.

Refer to Apple's Add to Apple Wallet Guidelines.

Creating `AddToWalletButton` in code

The following snippet showcases how to create and set up the AddToWalletButton for provisioning:

//Declare the AddToWalletButton
lazy var addToWalletButton: AddToWalletButton = {
    let button : AddToWalletButton = AddToWalletButton()
    button.authenticationToken = "<token>"
    button.cardDescription = "<cardDescription>"
    button.cardHolderName = "<cardHolderName>"
    button.cardId = "<cardId>"
    button.cardLastFour = "<cardLastFour>"
    button.onCompleteAction = { res in
        switch(res){
        case .success(let msg):
            print(msg)
        case .error(let err):
            print(err.description)
        }
    }

    //optional values
    button.iOSButtonStyle = PKAddPassButtonStyle.blackOutline // default is .black
    button.viewController = self

    return button
}()

Creating `AddToWalletButton` with Interface Builder

Alternatively, you can use an @IBOutlet property and initialize the AddToWalletButton in a Storyboard or nib file.

To do so:

Create a UIView within your layout
Set its class to AddToWalletButton, selecting WeavrPushProvisioning as the module.
Assign the view created to the @IBOutlet

Finally, you'll still need to configure the button when:

The view first appears
The card data changes
The user token changes

This can be done with a snippet similar to:

button.authenticationToken = "<token>"
button.cardDescription = "<cardDescription>"
button.cardHolderName = "<cardHolderName>"
button.cardId = "<cardId>"
button.cardLastFour = "<cardLastFour>"
button.onCompleteAction = { res in
    switch(res){
    case .success(let msg):
        print(msg)
    case .error(let err):
        print(err.description)
    }
}

//optional values
button.iOSButtonStyle = PKAddPassButtonStyle.blackOutline // default is .black
button.viewController = self

Provisioning the card

Once the button is properly configured, and visible to the user, tapping it will trigger the provisioning flow.

The result of the provisioning flow will be notified to the onCompleteAction callback, allowing you to react to success or failure scenarios.

Provision a card via programmatic interface

An alternative to the AddToWalletButton component, is the WPPComponents.beginPushProvisioning function from the SDK.

warning

Note that you must adhere to Apple's Add to Apple Wallet Guidelines. Apple may reject your app if you do not.

It is recommended to use PKAddPassButton when not using AddToWalletButton to ensure adherence to Apple's guidelines. You are still required to check that the card status is AddCardToWalletStatus.notAdded before displaying the button.

The following snippet showcases how your UIViewController subclass could trigger the push provisioning flow.

MyViewController.swift
class MyViewController: UIViewController {

    // ...

    func provisionCard() {
        WPPComponents.beginPushProvisioning(
            from: self,
            authenticationToken: "<token>",
            panLastFour: "<cardLastFour>",
            cardId: "<cardId>",
            cardHolderName: "<cardHolderName>",
            cardDescription: "<cardDescription>"
        ) { result in
            switch result {
            case .success(let response):
                print(response)
            case .error(let error):
                print(error.description)
            }
        }
    }
}

`AddToWalletButton` localisation

The PKAddPassButton provided by Apple is automatically localised by the system based on the user's device language settings. You do not need to provide your own translations for the button's title or appearance.

To ensure correct localisation:

Make sure your app supports the desired languages in your Xcode project settings (Info.plist > CFBundleLocalizations).
The device language must be set to one of your supported languages.
Do not override the button’s title or appearance with custom text if you want to keep system localization.

Next steps

Apple mandates integration with Apple Wallet Extensions for all apps that include push provisioning as a feature. Integration from Apple Wallet using Wallet Extensions provides a guide for it.

Initialize the SDK​

Get the card status​

Provisioning a card​

Provision a card with AddToWalletButton​

Creating AddToWalletButton in code​

Creating AddToWalletButton with Interface Builder​

Provisioning the card​

Provision a card via programmatic interface​

AddToWalletButton localisation​

Next steps​