MPP iOS SDK

Provides API for Push Provisioning functionality on iOS devices.

Requirements

Implementing Apple In-App Provisioning requires the following pre-requisites to be met:

  • Signed agreement with Apple.
  • Special Apple Pay In-App Provisioning entitlement distributed to the Team ID by Apple – Enabling app for Apple Pay In-App Provisioning.
  • App Store app Adam ID whitelisted by Apple.
  • The device must be able to connect to the Internet.
  • iOS version must be 10.0 or above.

Installation

It is recommended to use Xcode to develop and build the project.

iOS Framework

1. Download mpp---.zip.

2. Unzip the archive and find XCFramework – MeaPushProvisioning.xcframework.

3. Select Xcode project app target.

4. Add MeaPushProvisioning.xcframework to Frameworks, Libraries, and Embedded Content section of General settings for app target.

5. Add Apple PassKit.framework to Frameworks, Libraries, and Embedded Content.

6. Set ApplePay.entitlements for Code Signing Entitlements in iOS project Build Settings for iOS Device target.



Enabling app for Apple Pay In-App Provisioning

Requesting Apple Pay In-App Provisioning entitlement

Issuers need to apply for Apple Pay In-App Provisioning entitlements to develop and test the complete push provisioning flow.

Getting Started with Apple Pay In-App Provisioning documentation:

Note about Team ID and Adam ID

Only production Team ID and Adam ID can receive the entitlement and can be whitelisted. To request the entitlement and whitelist for your App(s), please send the following information by email to apple-pay-provisioning@apple.com:

  • Issuer Name and Country Code
  • App Name
  • Team ID (e.g. 1ABCD2FGHI)
  • Adam ID (e.g. 123456789)

Find Team ID on Apple Developer Account Membership website.
Find Adam ID (App Apple ID) on App Store Connect App Information website.

Once Apple Pay In-App Provisioning entitlements have been granted, the distribution entitlement should be included into a Provisioning Profile, and the same Provisioning Profile shoud be used to develop the app in Xcode.
Entitlements drop down will appear for Provisioning Profiles in Apple Developer website.


 

Configuring ​Associated Application Identifier

PassKit framework can be fully used only if the card profile sent by MDES is configured with a correct ​Associated Application Identifier (​App ID​) value. This allows the issuer application to see and access active payment passes.

App ID​ is constructed by combining the ​Team ID​ with the​ ​App Bundle ID​, for example, 1ABCD2FGHI.com.bank.app. This value should be set in CIS Interview Preperation Guide​ document provided by the Mastercard. Go to sheet Product Configuration, scroll to row 59 and fill in the appropriate Issuer Response column.

Apple Pay push provisioning guide

Before starting implementation you should have completed the installation of the MPP library.

The MPP library helps the Issuer with Apple Pay In-App Provisioning implementation. Apple Pay In-App Provisioning provides a credit or debit card issuer the ability to initiate the card provisioning process for Apple Pay directly from the issuer’s iOS app.

Cardholders will find the In-App Provisioning feature an extremely convenient method to provision their payment details into their iOS devices by avoiding the need to input card details manually. Apple Pay Wallet needs to be setup before payment card is provisioned to it. This is done via the PassKit framework. PassKit in Apple Developer Documentation.

Card data parameters

Push provisioning flow is started by initializing MppCardDataParameters object with CardIdCardSecret or EncryptedPan.
Initialize MppCardDataParams.

or

Guide for encryptedCardData generation can be found in the How To section.

Initialize Apple Pay In-App provisioning

The MPP library provides MeaPushProvisioning class with initializeOemTokenization method to initiate Apple Pay In-App provisioning.

Initiate in-app push provisioning by using MeaPushProvisioning.initializeOemTokenization method and MppCardDataParameters parameter. Check if the payment card can be added to Apple Pay by using primaryAccountIdentifier in response. Go to Show or hide “Add to Apple Wallet” button.

primaryAccountIdentifier
  1. Value is always empty for the very first push provisioning of the specific card. Empty value indicates that card can be added to Apple Pay.
  2. Users may have different passes installed on different paired devices (for example, on an iPhone and an Apple Watch). This property allows to filter out the devices that already contain a matching pass.
  3. Once the value is fetched for a specific card app should cache primaryAccountIdentifier to avoid unnecessary MeaPushProvisioning.initializeOemTokenization calls every time when Add to Apple Wallet button should be shown or hidden.
associatedApplicationIdentifiers

Correct configuration of associatedApplicationIdentifiers allows the respective app to see, access and activate your payment passes. [[PKPassLibrary new] passes][[PKPassLibrary new] remotePaymentPasses] and [passLibrary canAddPaymentPassWithPrimaryAccountIdentifier:] will ONLY return passes if App ID (TeamID.BundleID) is specified in associatedApplicationIdentifiers on service provider side.

 

App ID is constructed by combining the Team ID with the App bundle ID, for example, A1B2C3D4E5.com.thebank.mobileapp.

 

TeamID is the Apple Developer team which is used to distribute your app via App Store. BundleID is the ID of your app.

Caching primaryAccountIdentifier for future use

App should cache primaryAccountIdentifier value for the specific card to avoid unnecessary MeaPushProvisioning.initializeOemTokenization calls every time when Add to Apple Wallet button should be shown or hidden.

Add to Apple Wallet button

Use PKAddPassButton class to create an Add to Apple Wallet button. iOS SDK provides a control with the correct appearance.

Show or hide Add to Apple Wallet button

The app is responsible to check and decide if “Add to Apple Wallet” should be shown or hidden for the user using primaryAccountIdentifier. The button should be shown only when the card is not added to Apple Pay already.
Use - PKPassLibrary.canAddPaymentPass(withPrimaryAccountIdentifier:) to check whether the card can be added to Apple Wallet. The return value indicates whether the app can add a card to Apple Pay for the provided primary account identifier. This function does not provide specific information about Apple Wallet on iPhone or Apple Watch.

Detect if PKPaymentPass can be added specifically to Apple Wallet on iPhone or Apple Watch

Important

Read further only when app needs to detect if PKPaymentPass can be added specifically to Apple Wallet on iPhone or Apple Watch. Use for Apple Watch only when it is paired to iPhone.

  1. Use - PKPassLibrary.canAddPaymentPass(withPrimaryAccountIdentifier:) to check whether the card can be added to Apple Wallet on iPhone or Apple Watch. The return value of the function indicates if the card can be added, however, it does not provide specific information about Apple Wallet on iPhone or Apple Watch.
  2. Detect if Apple Watch is paired with iPhone.

3. Check if PKPaymentPass is already in Apple Wallet on iPhone or Apple Watch:

  • Get the list of passes in Apple Wallet on iPhone - PKPassLibrary.passes()
  • Get the list of passes on Apple Watch (if there is a paired device) - PKPassLibrary.remotePaymentPasses()

4. If any of the two lists contain items, use the PKPaymentPass properties primaryAccountIdentifier and optionally primaryAccountSuffix to confirm whether the pass in the list matches.

5. Detect if PKPaymentPass is already added specifically to Apple Wallet on iPhone.

6. Detect if PKPaymentPass is already added specifically to Apple Watch.

Add Payment Pass View Controller

Mobile application has to create an instance of PKAddPaymentPassViewController class, which lets your app prompt the user to add the pass to the pass library.

PKAddPaymentPassViewController have to be initialized using data retrieved in initializeOemTokenization:completionHandler: handler and a delegate that implements PKAddPaymentPassViewControllerDelegate protocol.

Complete Apple Pay In-App provisioning

For completion of provisioning, MeaPushProvisioning class provides completeOemTokenization method. This method exchanges Apple certificates and signature with Issuer Host.

Delegate should implement PKAddPaymentPassViewControllerDelegate protocol to call completeOemTokenization:completionHandler: method, once the data is exchanged PKAddPaymentPassRequest is passed to the handler to add the payment card to Apple Wallet. In the end and delegate method is invoked to inform you if request has succeeded or failed.

Attention

Adding payment passes requires a special entitlement issued by Apple. MPP SDK installation step 7.

Testing in sandbox mode

Apple Pay In-App Provisioning entitlement com.apple.developer.payment-pass-provisioning only works with distribution provisioning profiles, which means that even after you obtain it, the only way to test the end-to-end push provisioning flow is by first distributing the app via TestFlight or the App Store.

Apple Pay Sandbox Testing: Sandbox Testing

Issuer Extensions

To push-provision a card, the cardholder needs to specifically open the issuer application. A better solution is to show available card to push-provision in the Apple Wallet. Apple introduced Issuer Extensions starting from iOS 14.0. Issuer application needs to implement extensions for Apple Wallet to be able to request available cards.

Supporting issuer extensions:

  • App must have a non-UI extension that reports status
  • Extension pricinipal object must subclass PKIssuerProvisioningExtensionHandler
  • Requires non-UI extension entitlement

What if app requires authentication?

  • Add support for a UI extension
  • Extension principal object is view controller that conforms to PKIssuerProvisioningExtensionAuthorizationProviding
  • Requires UI extension entitlement

Flow diagramm below describes cardholder data flow.

Contact Apple to apply for entitlements: apple-pay-inquiries@apple.com


 

Changelog

1.0.0

2020-07-02

MODIFIEDBuilt with iphoneos13.5.

0.8.0

2020-04-16

FIXEDFixed response parsing.

ADDEDAdded helper MeaPushProvisioning.canAddPaymentPassWithPrimaryAccountIdentifier(...).
ADDEDAdded helper MeaPushProvisioning.paymentPassExistsWithPrimaryAccountIdentifier(...).
ADDEDAdded helper MeaPushProvisioning.remotePaymentPassExistsWithPrimaryAccountIdentifier(...).

0.7.1

2019-08-06

FIXEDFixed Xcode 10 compatibility issue for App Store app submission and exporting. Framework is built with iphoneos12.4.

MODIFIEDBoth Simulator and device MeaPushProvisioning.framework use the same CFBundleIdentifier.

0.7.0

2019-07-31

ADDEDPublic paymentAppInstanceId method.

 

ADDEDXCFramework to simultaneously support devices and Simulator.

MODIFIEDSet Architectures and Valid Architectures to $(ARCHS_STANDARD), which result to armv7 arm64.
MODIFIEDUse unique CFBundleIdentifier for Simulator MeaPushProvisioning.framework.
MODIFIEDRemoved -iphonesimulator postfix for Simulator MeaPushProvisioning.framework bundle name.

0.6.0

2019-04-18

Public stable version of MeaWallet Push Provisioning iOS SDK.

On this page