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

#import <WatchConnectivity/WatchConnectivity.h>

@interface ViewController : UIViewController <TPCSDKProvisionDelegate, WCSessionDelegate>
@property BOOL isWatchPaired;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    if ([WCSession isSupported]) {
        WCSession* session = [WCSession defaultSession];
        session.delegate = self;
        [session activateSession];
    }
}

// MARK: WCSessionDelegate
- (void)session:(nonnull WCSession *)session activationDidCompleteWithState:(WCSessionActivationState)activationState error:(nullable NSError *)error { 
    if (error != nil) {
        // handle error
    } else if (activationState == WCSessionActivationStateActivated && session.isPaired == TRUE)  {
        _isWatchPaired = TRUE;
    }
}

- (void)sessionDidBecomeInactive:(nonnull WCSession *)session { 
    // handle sessionDidBecomeInactive
    _isWatchPaired = FALSE;
}

- (void)sessionDidDeactivate:(nonnull WCSession *)session { 
    // handle sessionDidDeactivate
    _isWatchPaired = FALSE;
}

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

- (void)getCardDigitizationResultWithFundingCardWithSchemeAndPayload {
    CardScheme scheme = CardSchemeMastercard;
    NSString* payload = @"PKCS7 encrypted PAN";

    FundingCard* card = [[FundingCard alloc] initWithScheme:scheme
                                            encryptedPayload:payload];

    [TPCSDK getCardDigitizationResultWithCard:card
                     primaryAccountIdentifier:nil
                   primaryAccountNumberSuffix:nil
                                   completion:^(NSString* primaryAccountIdentifier, CardDigitizationResult* _Nullable sdkResult, NSError* _Nullable error) {
        [self updateUIForResult:sdkResult sdkError:error];
    }];
}

- (void)getCardDigitizationResultWithPrimaryAccountIdentifier {
    NSString* primaryAccountIdentifier = @"primaryAccountIdentifier";

    [TPCSDK getCardDigitizationResultWithCard:nil
                     primaryAccountIdentifier:primaryAccountIdentifier
                   primaryAccountNumberSuffix:nil
                                   completion:^(NSString* primaryAccountIdentifier, CardDigitizationResult* _Nullable sdkResult, NSError* _Nullable error) {
        [self updateUIForResult:sdkResult sdkError:error];
    }];
}

- (void)getCardDigitizationResultWithPrimaryAccountNumberSuffix {
    CardScheme scheme = CardSchemeMastercard;
    NSString* payload = @"PKCS7 encrypted PAN";
    NSString* primaryAccountNumberSuffix = @"Last 4 Digits of PAN";

    FundingCard * card = [[FundingCard alloc] initWithScheme:scheme
                                            encryptedPayload:payload];

    [TPCSDK getCardDigitizationResultWithCard:nil
                     primaryAccountIdentifier:nil
                   primaryAccountNumberSuffix:primaryAccountNumberSuffix
                                   completion:^(NSString* primaryAccountIdentifier, CardDigitizationResult* _Nullable sdkResult, NSError* _Nullable error) {
        [self updateUIForResult:sdkResult sdkError:error];
    }];
}

- (void)updateUIForResult:(CardDigitizationResult* _Nullable)sdkResult sdkError:(NSError * _Nullable) error {
    if (error != nil ) {
        // handle the error
    } else if(sdkResult != nil){
        if ( sdkResult.localPKPass.secureElementPass.passActivationState == PKSecureElementPassActivationStateRequiresActivation ) {
            // Refer to Token life cycle management for Activate action. 
            // There is pending card activation on iPhone.
        } else if ( sdkResult.remotePKPass.secureElementPass.passActivationState == PKSecureElementPassActivationStateRequiresActivation ) {
            // 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 ( [self 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.
        }
    }
}

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

- (void)getTokenWithInputByLast4 {
    // Last four digits of the physical card (FPAN).
    NSString *last4 = @"1234";

    GetTokenInput *tokenInput = [[GetTokenInput alloc] initWithLast4:last4];

    [TPCSDK getTokenWithInput:tokenInput completion:^(PKPass *_Nullable localPass, PKPass *_Nullable remotePass, NSError *_Nullable error) {
        [self updateUIForLocalPass:localPass remotePass:remotePass sdkError:error];
    }];
}

// - Since: 2.3.0
- (void)getTokenWithInputBySerialNumber {
    // Serial number provided by Apple Pay.
    NSString *serialNumber = @"Serial number";

    GetTokenInput *tokenInput = [[GetTokenInput alloc] initWithSerialNumber:serialNumber];

    [TPCSDK getTokenWithInput:tokenInput completion:^(PKPass *_Nullable localPass, PKPass *_Nullable remotePass, NSError *_Nullable error) {
        [self updateUIForLocalPass:localPass remotePass:remotePass sdkError:error];
    }];
}

- (void)updateUIForLocalPass:(PKPass *_Nullable)localPass remotePass:(PKPass *_Nullable)remotePass sdkError:(NSError *_Nullable)error {
    if (error != nil) {
        // Handles the error.
    } else {
        if (localPass != nil && localPass.secureElementPass.passActivationState == PKSecureElementPassActivationStateRequiresActivation) {
            // Refer to Token life cycle management for Activate action. 
            // There is a pending card activation on iPhone.
        } else if (remotePass != nil && remotePass.secureElementPass.passActivationState == PKSecureElementPassActivationStateRequiresActivation) {
            // Refer to Token life cycle management for Activate action. 
            // There is pending card activation on Apple Watch.
        } else if (localPass != nil && remotePass == nil) {
            if ([self 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.
        }
    }
}

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

- (void)onProvisionCompletionWithPass:(PKPaymentPass * _Nullable)pass
                                error:(NSError * _Nullable)error {
    if (error != nil) {
        // TODO: problem with provisioning
        // Refer to Swift code for more information
    }
}

- (void)provision {
  NSString * suffix = @"1234";
  NSString * cardholderName = @"John Doe";
  NSString * scheme = CardSchemeMastercard;
  NSString * payload = @"PKCS7 encrypted PAN";
  NSString * code = @"code";

  [TPCSDK provisionFromController:self
             primaryAccountSuffix:suffix
                   cardholderName:cardholderName
                           scheme:scheme
                 encryptedPayload:payload
                authorizationCode:code
                provisionDelegate:self];
}

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

- (void)onProvisionCompletionWithPass:(PKPaymentPass * _Nullable)pass
                                error:(NSError * _Nullable)error {
    if (error != nil) {
        // TODO: problem with provisioning
        // Refer to Swift code for more information
    }
}

- (void)provision {
  NSString * suffix = @"1234";
  NSString * cardholderName = @"John Doe";
  NSString * scheme = @"SCHEME"; // VISA, MASTERCARD, AMEX, DISCOVER
  NSString * payload = @"PKCS7 encrypted PAN";
  NSString * code = @"code";
  NSString * productId = @"productId"; // Only applicable for domestic schemes. This can be retrieved from Bank's Card Management System.
  NSString * primaryAccountIdentifier = @"primaryAccountIdentifier";

  [TPCSDK provisionFromController:self
             primaryAccountSuffix:suffix
                   cardholderName:cardholderName
                     schemeString:scheme
                 encryptedPayload:payload
                authorizationCode:code
                        productId:productId
         primaryAccountIdentifier:primaryAccountIdentifier                
                provisionDelegate:self];
}