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:

• Initialise the SDK
• Check the card status so that the flow is only triggered if the card is not yet provisioned
• 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 since 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.

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

func checkCardStatus(panLastFour: String, onDeviceType deviceType: DeviceType) {
    let status = WPPComponents.getCardStatusInWallet(forCardWithLastFourDigits: panLastFour, deviceType: deviceType)

    switch status {
    case .unavailable:
        print("Unavailable")
    case .alreadyAdded:
        print("Already added")
    case .notAdded:
        print("Not added")
    case .requiresActivation:
        print("Requires activation")
    case .activating:
        print("Activating")
    case .suspended:
        print("Suspended")
    case .deactivated:
        print("Deactivated")
    case .unknown:
        print("Unknown")
    }
}

// Check the state of the card ending in 1234 on the phone:
checkCardStatus(panLastFour: "1234", onDeviceType: .phone)

// Check the state of the card ending in 1234 on the watch:
checkCardStatus(panLastFour: "1234", onDeviceType: .watch)

// Check the state of the card ending in 1234 on either the phone, or watch:
checkCardStatus(panLastFour: "1234", onDeviceType: .either)

Provisioning a card

There are two ways to provision a card using the Weavr Provisioning SDK:

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

In general you'll want to use AddToWalletButton so as 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 of the state of the card in Apple Pay. Please refer to Apple's Add to Apple Wallet Guidelines.

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

    return button
}()

When the user taps on the button, the provisioning process is triggered. Upon completion, the onCompleteAction callback notifies of its result.

Provision a card via programmatic interface

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

danger

Please 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's recommended using 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)
            }
        }
    }
}

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.