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:

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

Initialise the SDK

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

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

Get the card status

The Weavr 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 be performed on the device being used
• watch - The card state query is be performed on the user's Apple Watch
• either - The card state query is be performed on both the phone and the watch. The result is notAdded if the Apple Watch has that state. In all other cases it behaves the same as using phone.

Specify "Either" from your app

It is recommended that you specify either as the device type. This ensures that the response, which indicates whether you need to show the Add To Wallet button or not, 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 endpoint:

import WeavrPushProvisioning

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

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 the Weavr Provisioning SDK:

1. Using the AddToWalletButton (recommended)
2. Using the programmatic interface

In general, you should use the AddToWalletButton to adhere to Apple Pay's brand guidelines.

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 AddCardToWalletStatus.notAdded.

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 programmatically

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 initialise the AddToWalletButton in a Storyboard or nib file.

To do so:

1. Create a UIView within your layout
2. Set its class to AddToWalletButton, selecting WeavrPushProvisioning as the module.
3. 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.

If not using AddToWalletButton, it is recommended to use PKAddPassButton 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)
            }
        }
    }
}

AddToWallet button 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 localisation.

Summary

Just use PKAddPassButton as provided, and the system will handle localisation for you. No extra steps are needed.

Next steps

Apple mandates integration with Apple Wallet Extensions for all apps that include push provisioning as a feature. Follow: Integration from Apple Wallet using Wallet Extensions to do this.