Push Provisioning

Step 1: Showing the Add to Wallet button

When the end user first launches the issuer application, it must determine whether to show or hide the Add to Apple Wallet button for a specific card.

As early as possible, determine whether the end user has an iPhone or an iPhone paired with an Apple Watch.

Then combine this pairing status with the Push Provisioning SDK getToken API result to decide whether to show or hide the Add to Apple Wallet button.

Swift

import WatchConnectivity

class ViewController: UIViewController, TPCSDKProvisionDelegate, WCSessionDelegate {    
    // To store the isWatchPaired value before calling TPC function
    var isWatchPaired = false

    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        if WCSession.isSupported() {
            let session = WCSession.default
            session.delegate = self
            session.activate()
        }
    }
    
    // MARK: WCSessionDelegate
    func session(_ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState, error: Error?) {
        if error != nil {
            //handle error
        } else if activationState == .activated && session.isPaired {
            isWatchPaired = true
        }
    }
    
    func sessionDidBecomeInactive(_ session: WCSession) {
        // handle sessionDidBecomeInactive
        isWatchPaired = false
    }
    
    func sessionDidDeactivate(_ session: WCSession) {
        // handle sessionDidDeactivate
        isWatchPaired = false
    }
}

Objective-C

Then call the getToken API to update the result.

Note

Refer to the PKAddPassButton guidelines for using the Add to Apple Wallet button in your issuer application.

The following applies to iOS SDK 2.0.0 and earlier.

Swift

func getCardDigitizationResultWithFundingCardWithSchemeAndPayload() {
    let scheme = CardScheme.Mastercard
    let payload = "PKCS7 encrypted PAN"
    
    let card = FundingCard(scheme: scheme,
                            encryptedPayload: payload)
    
    TPCSDK.getCardDigitizationResult(card: card) { [weak self]
        (primaryAccountIdentifier, sdkResult, error) in
        self?.updateUI(for: sdkResult, sdkError: error)
    }
  }

  func getCardDigitizationResultWithPrimaryAccountIdentifier() {
    let primaryAccountIdentifier = "primaryAccountIdentifier"

    TPCSDK.getCardDigitizationResult(primaryAccountIdentifier: primaryAccountIdentifier) { [weak self]
        (primaryAccountIdentifier, sdkResult, error) in
        self?.updateUI(for: sdkResult, sdkError: error)
    }
  }

  func getCardDigitizationResultWithPrimaryAccountNumberSuffix() {
      let scheme = "SCHEME" // VISA, MASTERCARD, AMEX, DISCOVER
      let encryptedPayload = "PKCS7 encrypted PAN"
      let primaryAccountNumberSuffix = "Last 4 Digits of PAN"

      let card = FundingCard(schemeString: scheme,
              encryptedPayload: encryptedPayload)

      TPCSDK.getCardDigitizationResult(card: card, primaryAccountNumberSuffix: primaryAccountNumberSuffix) { [weak self]
          (primaryAccountIdentifier, sdkResult, error) in
          self?.updateUI(for: sdkResult, sdkError: error)
      }
  }

func updateUI(for sdkResult: CardDigitizationResult?, sdkError: Error?) {
    if let error = sdkError {
      // handle error
    } else if let sdkResult = sdkResult {
      if sdkResult.localPKPass?.secureElementPass?.passActivationState == .requiresActivation {
        // Refer to Token life cycle management for Activate action. 
        // There is pending card activation on iPhone.
      } else if sdkResult.remotePKPass?.secureElementPass?.passActivationState == .requiresActivation {
        // Refer to Token life cycle management for Activate action. 
        // There is pending card activation on Apple Watch.
      } else if sdkResult.localPKPass != nil && sdkResult.remotePKPass == nil {
        if isWatchPaired {
          // display "Add to Apple Wallet" button for Apple watch.
        } else {
          // Hide "Add to Apple Wallet" button.
        }
      } else if sdkResult.localPKPass == nil {
        // display "Add to Apple Wallet" button.
      } else if sdkResult.localPKPass != nil && sdkResult.remotePKPass != nil {
        // card is already provisioned. Hide "Add to Apple Wallet" button.
      }
    }
  }

Objective-C

The following applies to iOS SDK 2.1.0 and later.

Swift

func getTokenWithInputByLast4() {
    // Last four digits of the physical card (FPAN).
    let last4 = "1234" 
    let tokenInput = GetTokenInput(last4: last4)
    TPCSDK.getToken(input: tokenInput) { [weak self]
        (localPass, remotePass, error) in
        self?.updateUI(for: localPass, remotePass: remotePass, sdkError: error)
    }
}

// - Since: 2.3.0
func getTokenWithInputBySerialNumber() {
    // Serial number provided by Apple Pay.
    let serialNumber = "Serial number"
    let tokenInput = GetTokenInput(serialNumber: serialNumber)
    TPCSDK.getToken(input: tokenInput) { [weak self]
        (localPass, remotePass, error) in
        self?.updateUI(for: localPass, remotePass: remotePass, sdkError: error)
    }
}

func updateUI(for localPass: PKPass?, remotePass: PKPass?, sdkError: Error?) {
    if let error = sdkError {
        // Handles the error.
    } else {
        if localPass?.secureElementPass?.passActivationState == .requiresActivation {
            // Refer to Token life cycle management for Activate action. 
            // There is a pending card activation on iPhone.
        } else if remotePass?.secureElementPass?.passActivationState == .requiresActivation {
            // Refer to Token life cycle management for Activate action. 
            // There is pending card activation on Apple Watch.
        } else if localPass != nil && remotePass == nil {
            if isWatchPaired {
                // Displays the "Add to Apple Wallet" button for Apple watch.
            } else {
                // Hides the "Add to Apple Wallet" button.
            }
        } else if localPass == nil {
            // Displays the "Add to Apple Wallet" button.
        } else if localPass != nil && remotePass != nil {
            // Card is already provisioned. Hide the "Add to Apple Wallet" button.
        }
    }
}

Objective-C

Caution

• If the card still appears as "NOT_DIGITIZED" after provisioning, verify that the issuer application is configured correctly in the TSP portal.

• The TPCSDK.isCardDigitized API is deprecated and not recommended. Use the getToken API instead. The isCardDigitized API does not indicate whether the card is pending activation or whether it is on an iPhone or Apple Watch.

Step 2: Provision a card

The provisioning delegate returns a PKPass after provisioning completes. Use it to check the card digitization status. If the delegate returns nil, the SDK also returns an error.

Before using the PKPass class, make sure to add the PassKit.framework to your project.

Warning

You must add the Push Provisioning entitlement to the issuer application before calling this API. Otherwise, the API returns an error. To get the entitlement, follow the Push Provisioning Access guidelines.

Use the getToken API to obtain localPKPass or remotePKPass. If either localPKPass or remotePKPass is not nil, access the primaryAccountIdentifier property of the PKSecureElementPass object. Pass the retrieved primaryAccountIdentifier to the provision API.

Provisioning with standard scheme enum values for Visa, Mastercard, Amex, and Discover

Swift

func onProvisionCompletion(pass: PKPaymentPass?, error: Error?) {
    if let error = error {
      if let tpcError = error as? TPCError {
          // handle TPCError
      } else {
          let provisionError = error as NSError
          if provisionError.domain == PKPassKitErrorDomain  {
              // error from Apple
              // https://developer.apple.com/documentation/passkit/pkaddpaymentpasserror
              switch provisionError.code {
                  case PKAddPaymentPassError.unsupported.rawValue:
                      print("The app cannot add cards to Apple Pay.")
                  case PKAddPaymentPassError.userCancelled.rawValue:
                      print("The user canceled the request to add a card to Apple Pay.")
                  case PKAddPaymentPassError.systemCancelled.rawValue:
                      print("The system canceled the request to add a card to Apple Pay.")
                  default:
                      break
              }
          }
      }
    } else if let pass = pass {
        // handle successful result with pass object
    }
  }
  
  func provision() {
    let suffix = "1234"
    let cardholderName = "John Doe"
    let scheme = CardScheme.Mastercard
    let payload = "PKCS7 encrypted PAN"
    let code = "code"
    
    TPCSDK.provision(fromController: self,
                     primaryAccountSuffix: suffix,
                     cardholderName: cardholderName,
                     scheme: scheme,
                     encryptedPayload: payload,
                     authorizationCode: code,
                     provisionDelegate: self)
  }

Objective-C

Provisioning with a scheme string (standard)

Swift

func onProvisionCompletion(pass: PKPaymentPass?, error: Error?) {
    if let error = error {
      if let tpcError = error as? TPCError {
          // handle TPCError
      } else {
          let provisionError = error as NSError
          if provisionError.domain == PKPassKitErrorDomain  {
              // error from Apple
              // https://developer.apple.com/documentation/passkit/pkaddpaymentpasserror
              switch provisionError.code {
                  case PKAddPaymentPassError.unsupported.rawValue:
                      print("The app cannot add cards to Apple Pay.")
                  case PKAddPaymentPassError.userCancelled.rawValue:
                      print("The user canceled the request to add a card to Apple Pay.")
                  case PKAddPaymentPassError.systemCancelled.rawValue:
                      print("The system canceled the request to add a card to Apple Pay.")
                  default:
                      break
              }
          }
      }
    } else if let pass = pass {
        // handle successful result with pass object
    }
  }
  
  func provision() {
    let suffix = "1234"
    let cardholderName = "John Doe"
    let scheme = "SCHEME" // VISA, MASTERCARD, AMEX, DISCOVER
    let payload = "PKCS7 encrypted PAN"
    let code = "code"
    let productId = "productId" // Only applicable for domestic schemes. This can be retrieved from Bank's Card Management System.
    let primaryAccountIdentifier = "primaryAccountIdentifier"
    
    TPCSDK.provision(fromController: self,
                     primaryAccountSuffix: suffix,
                     cardholderName: cardholderName,
                     schemeString: scheme,
                     encryptedPayload: payload,
                     authorizationCode: code,
                     productId: productId,
                     primaryAccountIdentifier:primaryAccountIdentifier,
                     provisionDelegate: self)
  }

Objective-C