Getting Started With Apple Pay In-App Provisioning, Verification & Security (3.0)


Getting Started with Apple Pay

In-App Provisioning, Verification
& Security
Version 3.0
June 2020
 Apple Confidential - Do Not Distribute - Not to be Used or Disclosed Without Permission from Apple Copyright 1
© 2020 Apple Inc. All rights reserved.
Confidentiality
The contents of this document, as well as any appendices, supplements, or follow up
communications, are confidential and proprietary. They should be shared only with disclosed
individuals, and on a need to know basis within Apple, and with disclosed partners.
Any diagrams, specifications, APIs, schemas, code, or other material contained herein are the
intellectual property of Apple Inc., unless otherwise indicated. Copyright © 2020 Apple Inc. All
rights reserved.
If you are not certain that you are disclosed, or that you should have access to this document,
please stop reading now, and consult the appropriate legal resource within your company before
proceeding.
Version Information
Date Version Changes
08/31/2015 Draft Initial
01/06/2016 1.1 Added language regarding Adam ID submission.
Added FPAN/DPAN suffix, passesOfType, remotePaymentPasses as methods to determine

01/27/2016 1.11
whether to present the Add to Apple Wallet button.
Updated In-App Provisioning Flow to include cryptography details and added to/formatted
the issuer host development step.
Updated the testing process section for clarity, payment data configuration table,
07/14/2016 1.2 references to PNO to include service provider.
Added description for PKAddPaymentPassRequestConfiguration, details to cryptography
section, Appendix A for the provisioning flow sample, pass metadata to prerequisites,
description of test vector usage, and additional details on entitlements.
Added advice on replacing Add to Apple Wallet Button after a payment pass is provisioned.
Also added “name” to payment data configuration 3 - encrypted FPAN.
10/03/2016 1.21
Added language to clarify Enterprise Team IDs aren’t supported, and clarified numeric
nature of Adam ID.
Added clarification on Crypto OTP formats, sample JSON dictionary, alternative to Add to
02/21/2017 1.22 Apple Wallet button.
Updated font, formatting.
03/02/2017 1.23 Added link to Apple Pay acceptance mark and cleaned up version information.
Minor wording changes.

06/05/2017 1.24
Added TestFlight testing [Sec 12] and certificate validation [Sec 8].
New major version with several new sections including test vectors and logging.
10/09/2019 2.0
Updated test vectors with the latest certificate.
Clarified the value for Associated Application Identifiers and fixed an issue in the JSON
dictionary format for Version 1.
19/02/2019 2.1
Other minor editorials changes as well.
Updated links, comments, fonts and formatting.
Consolidated separate documentation: ’In-App Provisioning Security Guidelines’ (now

Section 4.2), ‘In-App Provisioning Flow’ (now Section 7.9), and ’Getting Started with In-
App Verification' (now various sections, including Section 1.2, Section 6.2 and Section 7.2).
Introduced ‘Verification’ (red) and ‘Provisioning’ (blue) tags to clearly identify which
sections are relevant to either In-App Verification, In-App Provisioning, or both.
Reorganized document structure to improve reader understanding and experience by
integrating content from previous Appendices into relevant sections, including Appendix 1
(now Section 3.2), Appendix 2 (now Section 8.3), Appendix 3 (now Section 5.6), Appendix
4 (now Section 3.3), Appendix 5 (now Section 3.3) and Appendix 6 (now Section 9).
02/06/2020 3.0 Added new APIs for iOS 13.4+ and watchOS 6.2+ (including PKSecureElementPass), and
provided equivalents for all deprecated APIs from iOS 9.0-13.4 and watchOS 2.0-6.2.
Updated JSON payload requirements: the ‘name’ key/value pair is now required in Version
1 for all PNOs and service providers as specified in the encryptedPassData specification.
Updated references to App Store Connect for Team ID, Adam ID, App ID, and Bundle ID.
Added the required email format for Team ID entitlement and Adam ID whitelisting.
Added clarification with scenarios for presenting the ‘Add to Apple Wallet' button and
scenarios for understanding the .PassActivationState.
Updated Provisioning Flow and Verification Flow diagrams and step-by-step instructions.
Abbreviations and Acronyms
Name Definition
AES Advanced Encryption Standard
API Application Programming Interface
APP (or app) Card Issuer Mobile App that implements Apple Pay In-App Provisioning or In-App Verification
CA Certification Authority
CTA Call to Action
DPAN Device PAN
E2E End to End
ECC Elliptic Curve Cryptography
FPAN Funding PAN
GCM Galois/Counter Mode
HEX Hexadecimal Format (e.g. 0x0102AABF)
ID Identifier
IDE Integrated Development Environment
IV Initialization Vector
JSON JavaScript Object Notation
MAC Message Authentication Code
MFA Multi Factor Authentication
NIST National Institute of Standards and Technology
OID ISO Object Identifier
OTP One Time Password
PAN Primary Account Number
POST HTTP POST request
PNO Payment Network Operator
RSA Rivest–Shamir–Adleman algorithm
SEID Secure Element ID
T&Cs Terms and Conditions
UI User Interface
URL Universal Resource Link
UTF-8 8-bit Unicode Transformation Format
Table of Contents
1. Introduction VERIFICATION PROVISIONING 6
1.1. In-App Provisioning PROVISIONING 6
1.2. In-App Verification VERIFICATION 7
2. Checklist VERIFICATION PROVISIONING 8
3. In-App User Experience PROVISIONING 9
3.1. Promoting Apple Pay Availability PROVISIONING 9
3.2. Splash Screens, Banners & Links PROVISIONING 10
3.3. Buttons & Marks PROVISIONING 11
4. Security VERIFICATION PROVISIONING 13
4.1. Requirements & Recommendations VERIFICATION PROVISIONING 13
4.2. Security Guidelines VERIFICATION PROVISIONING 14
4.3. Additional Security VERIFICATION PROVISIONING 18
5. Requirements & Configurations VERIFICATION PROVISIONING 19
5.1. Prerequisites VERIFICATION PROVISIONING 19
5.2. Entitlement & Whitelisting Request VERIFICATION PROVISIONING 20
5.3. Entitlement Configuration VERIFICATION PROVISIONING 21
5.4. PNO Pass Metadata Configuration VERIFICATION PROVISIONING 23
5.5. PNO Payment Data Configurations PROVISIONING 26
5.6. PNO Payment Data Examples PROVISIONING 28
5.7. Issuer Server Enablement Flag VERIFICATION PROVISIONING 30
6. Backend Implementation VERIFICATION PROVISIONING 31
6.1. In-App Provisioning Backend Overview PROVISIONING 31
6.2. In-App Verification Backend Overview VERIFICATION 32
6.3. Certificates PROVISIONING 35
6.4. Communication VERIFICATION PROVISIONING 36
6.5. PNO Activation Data VERIFICATION PROVISIONING 37
7. Frontend Implementation VERIFICATION PROVISIONING 38
7.1. In-App Provisioning Frontend Overview PROVISIONING 38
7.2. In-App Verification Frontend Overview VERIFICATION 39
7.3. Get Passes VERIFICATION PROVISIONING 40
7.4. Pass Properties VERIFICATION PROVISIONING 41
7.5. Present ‘Add to Apple Wallet’ Button PROVISIONING 42
7.6. Initialize ViewController PROVISIONING 43
7.7. Deep Link from Apple Wallet VERIFICATION PROVISIONING 44
7.8. Additional Implementation VERIFICATION PROVISIONING 45
7.9. In-App Provisioning Flow Technical Overview PROVISIONING 46
8. Testing VERIFICATION PROVISIONING 48
8.1. Sandbox Environment VERIFICATION PROVISIONING 48
8.2. Production Environment VERIFICATION PROVISIONING 49
8.3. In-App Provisioning Test Vectors PROVISIONING 50
9. Troubleshooting VERIFICATION PROVISIONING 59
9.1. Sysdiagnose & SEID VERIFICATION PROVISIONING 59
9.2. Sysdiagnose Analysis VERIFICATION PROVISIONING 60
9.3. Cryptographic Errors VERIFICATION PROVISIONING 63
9.4. In-App Provisioning Errors PROVISIONING 65
1. Introduction VERIFICATION PROVISIONING
1.1. In-App Provisioning PROVISIONING
Apple Pay In-App Provisioning provides transit, access, and payment card issuers the ability to
initiate the card provisioning process for Apple Wallet directly from the issuer’s iOS app.
Users will find the In-App Provisioning feature an extremely convenient method to provision their
cards or passes into their iOS devices by avoiding the need to input those details manually.
Issuers will also find In-App Provisioning an effective component of a seamless iOS experience. By
driving the provisioning of cards or passes via their app, issuers can create a unified interface for
card provisioning and their other services.
Finally, for certain card products issued globally, account details may not be embossed on the
actual plastic carried by cardmembers. In-App Provisioning would serve as the sole channel for
initiating a card provisioning request for those portfolios as the account details would be provided
directly by the issuer to the iOS device.
The flow below shows the In-App Provisioning experience from a sample payment card issuer’s
app where the user taps the ‘Add to Apple Wallet’ button and the process starts. Note that the
process starts and finishes within the app: for the user, it provides a seamless flow.
Cancel Done You are all set!

DNC
Banca
Add Card to Card Added You card has been added to Apple Wallet.
Apple Pay
Bank Your card can be added to iPhone or Apple Pay is an easier way to pay in
Apple Watch shops, in apps, and online with your
iPhone, Apple Watch, iPad, and Mac.
iPhone Name JOHN APPLESEED
Use Apple Pay wherever you see
these symbols.
Apple Watch Card Number 5412
Balance 350,00 €
Add to Apple Wallet
Learn more about Apple Pay
Freeze my card: OFF

You card is frozen but you can continue
using Apple Pay Card-related information, location, device settings and device Card-related information, location, device settings and device
use patterns will be sent to Apple and may be shared togheter use patterns will be sent to Apple and may be shared togheter
with account information with your card issuer or bank to set up with account information with your card issuer or bank to set up
Card settings Apple Pay. Info su Apple Pay e privacy… Apple Pay. Info su Apple Pay e privacy…
App Apple Wallet App

Entry point Provisioning Flow Confirmation Page
Figure 1. In-App Provisioning User Flow.
Important
During the Apple Wallet provisioning flow, the user will have the option to select to which device the
card will be added to, in case there is a paired Apple Watch and the card is not on any device.
This option is automatically presented by iOS and cannot be controlled from within the app.
The app has the responsibility to correctly initialize iOS APIs so that the device selection is only
presented when the card has not been added to any device.
1.2. In-App Verification VERIFICATION
Apple Pay In-App Verification provides a credit or debit card issuer the means to utilize its iOS
mobile app for the verification of users and activation of a payment pass previously provisioned via
Apple Wallet.
Users will find the In-App Verification feature a convenient method to activate their recently
provisioned payment passes in addition to existing SMS/E-mail OTP and call center ID&V methods.
Issuers will also find In-App Verification an effective component of a seamless mobile experience.
By driving the activation of cards via their iOS mobile app, an issuer can create a unified interface
for card activation and other banking services alongside integration with Apple Wallet.
2. Checklist VERIFICATION PROVISIONING
Documentation received
ECC_V2 is the mandatory Encryption scheme [If ECC cannot be enabled in the issuer’s region,
contact Apple for alternatives]
App Security Reviewed with Apple
App User Experience Reviewed with Apple
In-App Provisioning entitlement and app whitelisting - Requested
In-App Provisioning entitlement and app whitelisting - Received
Metadata configuration on PNOs portals to let the app access cards in Apple Wallet (i.e.
associatedApplicationIdentifiers, associatedStoreIdentifiers, appLaunchUrl)
Optional: In-App Provisioning Cryptography tested in Sandbox*
In-App Provisioning Cryptography tested in Production via TestFlight.
Important
The issuer must set the minimum SDK build version to 10.3+ for testing in production with TestFlight.
Optional: In-App Verification tested in Sandbox*

In-App Verification tested in Production via TestFlight distribution, if applicable
Apple Pay functionality available via server flag and to whitelisted users only
App submitted to App Store for review (full review or Test Flight external group)
Important
Issuers MUST provide demo accounts and a video showing In-App Provisioning experience during sub
mission to App Store for reviewers to validate before approval. Failure to provide a test account and a
video might delay approval.
App approved by App Store (either full approval or Test Flight external group)
Issuer ready to start End to End Certification and to supply a promo-code or external TestFlight
account to the testing lab
E2E Certification completed and final version of the app submitted for review to the App Store
Final version of the app approved by App Store for publication (i.e. app 'ready for sale’ in App
Store Connect) - this is required to receive the green light to go live
*Sandbox testing is currently limited to selected PNOs and service providers only.
3. In-App User Experience PROVISIONING
3.1. Promoting Apple Pay Availability PROVISIONING
Splash Screens, Banners & Links

The issuer can tell their customers how easy it is to add a card to Apple Pay directly from the
issuer’s app by featuring splash screens and banners on the home screen of the app, with links to
the landing page.
Figure 2. Promoting availability.
Buttons & Marks

The issuer must ensure they include the 'Add to Apple Wallet’ button within their app, wherever
card or account management features are presented. This will serve to integrate Apple Pay as a
central feature of the issuer’s product offering.
Once the pass is provisioned, the issuer can replace the button with text such as “Added to Apple
Wallet” or “Available in Apple Wallet.”
Guidelines
Use of Apple Pay and Apple Wallet assets shall follow the following guidelines:
• The Apple Pay mark design documentation

• Apple Pay Identity guidelines
• Add to Apple Wallet button guidelines
Refer to the additional design resources for more information.
3.2. Splash Screens, Banners & Links PROVISIONING
The app shall present a splash screen/interstitial or message on home page when first opening the
app with Call To Action (CTA) that links direct to In-App provisioning or In-App Verification. Refer to
the flows below for a high level overview of when to present a splash screen.
Scenario 1 - app installation / re-installation

If customer
clicks on “add
card now” from
the splash
screen
Registration Cards view
flow (new with Add to
customer) wallet option
iPhone  Pay Pay post Card view

 Pay in-
home splash provisioning with Pay
app flow
screen screen message mark
Please include
Reinstall all screens from
flow Splash screen App home
(existing includes a short screen
the home
customer) description of screen to the
Pay card view
Please include all

screens seen by
the customers to If customer
install / reinstall the clicks on “later”
app from the splash
screen
Scenario 2 - existing customer login into the app
If customer
clicks on “add
card now” from
the splash
screen
Cards view
TouchID /
with Add to
FaceID login
wallet option
iPhone Password /  Pay Pay post Card view

 Pay in-
home passcode splash provisioning with Pay
app flow
screen login screen message mark
Please include
Splash screen all screens from
App home
Other login
includes a short screen
the home
Please clarify the screen to the
description of
format of the card view
Pay
password: length,
type of characters
If customer
clicks on “later”
from the splash
screen
Figure 3. Splash Screen User Flows.
3.3. Buttons & Marks PROVISIONING
‘Add to Apple Wallet’ Button

To indicate to the user the ability to provision a card into Apple Wallet, an app shall use either the
‘Add to Apple Wallet’ button (PKAddPassButton) or the Apple Pay mark followed by text within a
row selector.
Figure 4. ‘Add to Apple Wallet’.
Although the ‘Add to Apple Wallet’ button is the recommend option, the issuer can leverage the
Apple Pay acceptance mark within a row selector. See Figure 4 for an example. Note that the font
and color for the text, “Add to Apple Wallet”, can be selected to match the issuer’s iOS app.
Important
The issuer must NOT create their own buttons as the app may be rejected during App Store review.
No interstitial screens are allowed between the ‘Add to Apple Wallet’ button and the first screen of the
Apple Wallet provisioning flow. If a screen is present (e.g. to request customer authentication) the
issuer should use the Apple Pay mark with the row selector instead.
If the user has an iPhone, there are two scenarios (A, C) where the ‘Add to Apple Wallet’ button
needs to be considered; if the user has both an iPhone and a connected Apple Watch, there are
three scenarios (A, B, C):
A. No devices provisioned: The app must display the ‘Add to Apple Wallet’ button or Apple Pay
mark within a row selector as detailed above.
B. Some devices provisioned: The app must still display the ‘Add to Apple Wallet’ button or
Apple Pay mark within a row selector as detailed above, but may also indicate to the user
where the card is going to be provisioned next. This can be done by either changing the text in
the row selector (e.g. ‘Add to Apple Watch’) or to show a small text / graphic indication next to
the ‘Add to Apple Wallet’ button.
C. All devices provisioned: The app no longer displays the ‘Add to Apple Wallet’ button and
instead displays text such as “Added to Apple Wallet”.
Best Practice
Display the ‘Add to Apple Wallet’ button for a particular card until it has been added to all associated
devices. Once the card is provisioned on all available devices, the issuer can replace the button with
text such as “Added to Apple Wallet” or “Available in Apple Wallet”.
‘Set up Apple Pay’ Button
If the issuer has a waiver from Apple for not supporting In-App Provisioning at launch for one or
more of their apps, they should create a link to the Apple Wallet provisioning process from the pp.
To initiate the Apple Wallet setup, the issuer’s app can use one of the following approaches:
• iOS API: openPaymentSetup()

• URL Scheme: wallet://payment_setup
• Use the PKPaymentButton with type PKPaymentButtonType.setUp
The button is shown in Figure 5 can only be used when the In-App Provisioning experience is not
available and to redirect the user to the manual setup via Apple Wallet.
Figure 5. Set up Apple Pay Button.
‘Pay with Apple Pay’ Button

The app can present a pass in Apple Wallet for In-Store (NFC) payment using iOS APIs. This allows
the app to open the Apple Wallet and automatically present a specific card for payment. The
functionality can be invoked by more than one mobile app as long as the invoking app is included
in the list of ‘associatedApplicationIdentifiers' of that card.
For example, an issuer offering prepaid products may show within the app the balance of the
prepaid card and on the same screen it can offer the ability to the user to initiate the payment
directly from the app.
If the app implements the present pass functionality it shall use the PKPaymentButton with type
PKPaymentButtonType.inStore to indicate the ability to present a specific card.
For additional information refer to present(_:) from PKPassLibrary.
Figure 6. Pay with Apple Pay Button.
4. Security VERIFICATION PROVISIONING
4.1. Requirements & Recommendations VERIFICATION PROVISIONING
Requirements
In order to utilize In-App Provisioning and/or Verification, an app shall:
Meet Security Controls Requirements

Meet Multi-Factor Authentication Requirements
Implement additional security measures outlined for an Orange Path
Refer to Section 4.2 for additional information.
Best Practice
Authenticate the user via One Time Password (OTP) when the user first installs the issuer’s app onto
their device.
By having the user authenticate when they first install the app, the issuer satisfies the Apple Pay Multi
Factor Authentication (MFA) requirements and avoids the need to introduce additional authentication
steps within the In-App Provisioning flow before or after the user selects “Add to Apple Wallet.” This
will save the issuer’s cardholders time and effort and will result in a more positive user experience.
Provisioning Path Recommendations

Just as with the regular provisioning process, Apple will provide a path recommendation along with
any applicable reason codes to issuers. Through In-App Provisioning, an issuer has the option to
promote a yellow path recommendation from Apple to the green path with the exception of Reason
Code 0G - Orange Path.
In case Apple recommends Orange Path for a provisioning request, an issuer can utilize the
existing process for Orange Path validation including OTP to a tenured channel with one notable
exception: In-App Verification can not be presented as an authentication option for provisioning
requests initiated within the issuer iOS app.
For more information, refer to Section 4.2.
Note
If the provisioning data contains deviceScore=1, provisioning attempts shall be declined as further
explained in the 'Apple Pay Fraud Readiness Guidelines’.
4.2. Security Guidelines VERIFICATION PROVISIONING
Target Audience
This section will provide Apple Pay issuers with guidelines to ensure appropriate security
precautions are in place to facilitate In-App Provisioning for Apple Pay payment instruments.
Important
Every app requesting the Apple Pay In-App Provisioning entitlement must implement controls
designed to provide for secure card provisioning from inside the issuer’s app. These controls are
intended to further protect users from phishing and account takeover attempts.
Qualification
Qualification is verification during app review that the issuer app meets the minimum requirements
to ensure the controls are in place to enable In-App provisioning. In-App provisioning can only be
enabled through entitled Apps that are available through App Store. In-App provisioning
functionality will not be available for any apps that have not received the entitlement.
Minimally Acceptable Criteria for Utilizing In-App Provisioning

In order to utilize in-app provisioning, an app must meet the following two requirements:
A. Security Controls Requirements

B. Multi-Factor Authentication Requirements
An issuer must also be able to apply the additional security measures outlined for an Orange Path /
Code 0G as set forth below. Exceptions to full compliance with the requirements below require
written approval from Apple.
A. Security Controls Requirements
Qualification requires that an app meet all the Security Controls Requirements below:
Security Control Definition
Strong Password Policy Requiring a combination of at least two of the following:

• uppercase letters (e.g. A, B, C)
• lowercase letters (e.g. a, b, c)
• numeric characters (e.g. 1, 2, 3)
• special characters (e.g. $, ?, &)
Minimum Password Length Requiring a minimum length for passwords greater than six
characters
Maximum Attempts Policy Locking the user account after a specified maximum number of
attempts
Updated Credentials Controls Requiring use of different tenured channels or call center
verification if the application user credentials (i.e., username
and/or password) have been changed within a defined window
(e.g., 60 days) prior to the provisioning attempt
B. Multi-factor Authentication Requirements

All provisioning from in-app requires that multi-factor authentication of the user has been applied
at least once prior to the activation of the provisioning attempt. There are two approved
approaches to implement Multi-factor Authentication:
1. Unrecognized Device Multi-factor Authentication
Multi-factor authentication utilizing a one-time password (“OTP”) communicated to a tenured

channel (“MFA”) should be applied for new and unrecognized devices to ensure that the user is
verified during the first attempt to access a newly installed app. If the same app on the same
device is subsequently used to provision a card into Apple Pay, the original MFA satisfies the
MFA requirement for in-app provisioning.
2. In-App Provisioning with a One Time Passcode
If an issuer does not do an MFA at the time of app installation, an MFA must be done at the time
of provisioning to validate the user identity of the person seeking to provision the card. This can
be done utilizing the standard Yellow Flow capabilities of the platform (one-time password
through a tenured channel, or if none is available, via a call to the call center; note, in-app
verification may not be used in lieu of SMS, email or call center when the result would be to use
in-app verification to verify the app (as no additional security would be provided)).
Use of Apple Provisioning Data: In-App Provisioning and Orange Flow (Code 0G)
In addition to the Security Controls Requirements and the Multi-Factor Authentication
Requirements, an issuer should be able to meet the minimum requirements for Orange Path/Code
0G set forth below.
As context, Apple has implemented a Reason Code 0G (also known as “Orange Path”) as part of
the data shared by Apple with issuers for use during the provisioning process. Where Apple
indicates Orange Path / Code 0G in connection with a specific provisioning attempt, Apple is
indicating to the issuer the existence of factors suggesting that the issuer should exercise a high
degree of diligence before approving the specific provisioning request.
• In-App Provisioning: Apple requires that any In-App Provisioning attempt for which Apple
responds with Orange path / Code 0G be subject to additional authentication rigor. Specifically,
for any such attempt, the issuer is expected to do an updated OTP step to a tenured channel (in
the case of a dated OTP) or require a call into a call center if no additional tenured channel is
available. We also recommend steps like adding a requirement of entry of the CVV from the
card as part of the issuer’s user interface within their app. Note: issuers may choose to deploy
multiple of these practices with an Orange Path provisioning effort (and issuers are permitted to
use any of these practices or other security practices within their UI as they deem appropriate,
including in the absence of Orange Path/Code 0G indicators from Apple). In this context, best
practice will be to design for flexibility in enabling a range of additional verification measures
when either the issuer’s systems indicate an “orange / red flow” or where Apple’s data indicates
elevated risk.
• In-App Verification: Apple will provide a path recommendation along with any applicable reason
codes to issuers during the provisioning process. In the case of a Yellow or Orange Path (0G)
recommendation from Apple, In-App Verification can be used to identify and verify the
cardholder and activate the inactive payment pass.
Note
It is highly recommended that issuers have additional verification steps ready and available for
inclusion in their In-App Provisioning flow within their banking app.
For example, many banks deploy a one-time SMS to a verified channel for every meaningful change to
an account setup (e.g. adding a new payee into online bill payment, changing contact information) as
well as sending email notifications of such changes concurrently to the tenured email address.
The ability to gather CVV or ask additional “out-of-wallet” security questions may also be a useful
verification step; the addition of these capabilities, even if only used selectively, gives issuers
significant risk mitigation capabilities.
Provisioning Notifications
Notifications of successful provisioning (i.e. activation) are required to ensure the user is aware
that their card was successfully added to Apple Pay. This can be accomplished by sending an
electronic communication (e.g. email) or paper letter to a tenured address of record.
Revocation of Privileges
In order to ensure that users are protected from fraudulent provisioning, Apple reserves the right to
disable In-App Provisioning through all of the following methods, including, but not limited to:
• Sending provisions through Yellow flow requiring One Time Passcode for all In-App Provisioning
requests
• Blocking In-App Provisioning for specific versions of the app
• Blocking In-App Provisioning at the issuer level
• Disabling the app altogether
Issuer Certification
As part of the app submission and review process for apps that seek to incorporate In-App
Provisioning, Apple will request a bank certification as to compliance with the elements of this
guidelines document. Apple reserves the right to request demo accounts (login / password) in
order to validate elements of the functionality described herein.
4.3. Additional Security VERIFICATION PROVISIONING
The ‘Apple Pay Card Issuer Functional Requirements’ specifies additional security information that
the card issuers can obtain by analyzing the status of the app:
• Identify a device that had been previously associated with a user or where the mobile app had
been installed.
• Calculate the tenure (age) of each instance of the mobile app
• Use ‘mobile app + device’ tenure to assist in decisioning on In-App provisioning and In-App
verification
• Use ‘mobile app + device' tenure to create token risk indicator(s) for use in transaction
monitoring
• Use the mobile app’s credential reset activities to inform provision decisioning and token risk
indicators
• Determine the login method employed by the user (i.e. username/password, biometric
authentication) for each session and link that with any resulting token activation or provisioning
The data mentioned above can be used to dynamically associate a risk score to each provisioning
attempt coming from the app. The card issuer can combine information from Apple Pay
provisioning data with information from the app to strengthen the decision process and feed
additional information into the issuer’s real-time transaction fraud system.
For example, a low risk can be associated with a provisioning attempt coming from an app that has
been installed on the device for a long period of time and that has been regularly accessed and
used by the user.
On the contrary, a high risk indicator can be associated with a provisioning attempt coming from an
app that has been recently installed on a new device or where the user has recently changed login
credentials, or where the user has logged in with username / password where they regularly login
with biometrics.
5. Requirements & Configurations VERIFICATION PROVISIONING
5.1. Prerequisites VERIFICATION PROVISIONING
To implement In-App Provisioning and/or In-App Verification in the issuer’s app, the following
prerequisites must be met:
The issuer has a signed agreement with Apple

The issuer supports Apple Pay for their card portfolio
The issuer’s Team ID entitlement is granted by Apple according to Section 5.2
The issuer's Adam ID is whitelisted by Apple according to Section 5.2
The issuer defines short, concise names for the “issuer” and “issuer iOS mobile app” within
the APIs passed from the issuer’s Payment Network Operator (PNO) or service provider to
Apple according to Section 5.4
The issuer ensures their PNO or service provider populates the
‘associatedApplicationIdentifiers’, ‘associatedStoreIdentifiers’ and ‘appLaunchURL’ keys within
the DPANCardDescriptor array of the LinkAndProvisionResponse API according to Section 5.4
The issuer contacts their PNO or service provider to obtain technical specifications and kick off
the work stream to enable In-App Provisioning and In-App Verification functionality
The issuer authenticates the user at login to their mobile banking app - Apple strongly
recommends that issuers leverage a multi-factor authentication scheme within their security
protocols (for the best customer experience, issuers may consider authentication via Face ID or
Touch ID)
5.2. Entitlement & Whitelisting Request VERIFICATION PROVISIONING
Team ID
The Team ID is assigned by the Apple and is unique ID of a specific development team. The
issuer’s Team ID value is alphanumeric, and it is available from App Store Connect.
Adam ID
The Adam ID is assigned by the Apple and is the unique ID of the issuer’s app. The issuer’s Adam
ID value is numeric, and it is available from App Store Connect.
Important
Only production Team IDs and Adam IDs can receive the entitlement and can be whitelisted.
This must be the Team ID of the developer publishing the app on the App Store.
We do not provide entitlement to test Team IDs.
Requesting Entitlement & Whitelisting

To request the entitlement and whitelist for the issuer’s app(s), send the following information to
apple-pay-provisioning@apple.com:
Subject • Apple Pay Entitlement & Whitelisting Request - Issuer Name - [Country Code]
e.g. Apple Pay Entitlement & Whitelisting Request - MyBank - [DE]
Body • Issuer Name: e.g. MyBank

• Country [Country Code]: e.g. Germany [DE]
• Team ID: e.g. 1234ABCD
• Adam ID: e.g. 1234567890
• App Name: e.g. MyBanking
Important
Once the Team ID entitlement and Adam ID whitelisting have been granted, the issuer must complete
the steps in the next section - Section 5.3 - to correctly configure the entitlement.
5.3. Entitlement Configuration VERIFICATION PROVISIONING
Complete the following three steps to correctly configure the entitlement.
• Step 1: Use the Apple Developer Website to select the entitlement profile.
• Step 2: Use Xcode to ensure the same profile from Step 1 is selected to sign the app.
• Step 3: Use Xcode to manually add the entitlement to the .entitlement plist file.
Step 1: Use the Apple Developer website to select the entitlement profile
1. Go to the Apple Developer Website and login.
2. Select Certificates, Identifiers & Profiles.
3. Select “Distribution” underneath the “Provisioning Profiles” heading on the sidebar.
4. On the right, select the development (or distribution) iOS provisioning profile that the issuer will
use to develop (or deploy) their app to the App Store.
5. Click “edit" and, from the ensuing entitlements drop down, select “ApplePay In-App
Provisioning Development” to add the entitlement to the profile (see Figure 7).
REDACTED
REDACTED
REDACTED
REDACTED
Entitlements Drop Down
Figure 7. Provisioning Profiles Configuration on developer.apple.com.
Step 2: Use Xcode to ensure the same profile from Step 1 is selected to sign the app
1. Once the issuer has generated a profile which has been assigned the entitlement for In-App
Provisioning, open Xcode and head to the Preferences > Accounts > (Issuer Account) > View
Details pane where the issuer can then find and download the profile they generated.
2. In 'Build Settings’, the issuer can then adjust the Provisioning Profile to the newly generated
profile, as shown in Figure 8.
REDACTED
REDACTED
REDACTED
Provisioning Profile
Figure 8. Provisioning Profiles Configuration in Xcode Project.
Step 3: Use Xcode to manually add the entitlement to the .entitlement plist file
1. Add the entitlement manually to the .entitlement plist file of the issuer’s Xcode project, by
setting to TRUE the following key: com.apple.developer.payment-pass-provisioning. The
example below is a .entitlement plist containing the In-App Provisioning entitlement key.
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/
PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.developer.payment-pass-provisioning</key>
<true/>
<key>com.apple.developer.pass-type-identifiers</key>
<array>
<string>$(TeamIdentifierPrefix)*</string>
</array>
</dict>
</plist>
5.4. PNO Pass Metadata Configuration VERIFICATION PROVISIONING
The issuer is responsible for configuring on the PNO system five key/value pairs that are required
for the correct implementation of In-App Provisioning and In-App Verification:
"contactName"
"bank_app"
"associatedApplicationIdentifiers"
"associatedStoreIdentifiers"
"appLaunchUrl"
Important
The issuer must ensure their PNO or service provider populates the ‘contactName’,
‘associatedApplicationIdentifiers’, ’associatedStoreIdentifiers’, ’appLaunchUrl’ key/value pairs within
the ‘DPANCardDescriptor’ array of the ‘LinkAndProvisionResponse’ API.
Figure 9. In-App Verification.
"contactName"
The issuer name is defined within the ‘contactName’ key (see Figure 9) within the
'DPANCardDescriptor’ array of the ‘LinkAndProvisionResponse’ API.
"bank_app"
The name of the iOS mobile app (shown in Figure 9) to be used for In-App Verification is defined
within the value of the ‘bank_app’ section of the ‘getOTPResolutionMethodsResponse’ API.
"associatedApplicationIdentifiers"
This key allows the respective app to see, access and activate the issuer’s payment passes.
The value for this key should contain:
• The issuer’s App ID, available from App Store Connect.
An App ID is a two-part string used to identify one or more apps from a single development team.
The string consists of a Team ID (supplied by Apple and unique to a specific development team)
and a Bundle ID search string (supplied by developer), with a period (.) separating the two parts.
Note
If the issuer uses an explicit ‘App ID’, it may not match their developer account Team ID.
Review the Developer Account Help for more information.
The issuer’s App ID string should contain:
• The issuer's Team ID, as provided for entitlement in Section 5.2.

• The issuer's Bundle ID, available from App Store Connect.
// Example of Team ID:

1234ABCD
// Example of Bundle ID:

com.issuer.issuerApp
// Example of App ID:

1234ABCD.com.issuer.issuerApp
// Example of Key/Value Pair:

“associatedApplicationIdentifiers”:[”1234ABCD.com.issuer.issuerApp”]
"associatedStoreIdentifiers"
This key is used to link to the issei’s app or to redirect users to download their app from the app
Store (if it is not installed on the user’s device).

• The issuer's Adam ID, as provided for whitelisting in Section 5.2.
// Example of Adam ID:

1234567890

“associatedStoreIdentifiers”:[”1234567890”]
"appLaunchUrl"
This key is passed to the issuer’s app when opened from Apple Wallet. This happens either when
the user clicks on the issuer’s app icon from the back of the pass in Apple Wallet or when the
issuer’s app is opened during In-App Verification.
• A launch url of the issuer’s choice, in the format of scheme://path.

“appLaunchURL”:[”scheme://path”]
5.5. PNO Payment Data Configurations PROVISIONING
In-App Provisioning supports three Configurations for the payment data payload generated by the
issuer host (see ‘Configurations' below).
Important
As the supported Configuration(s) vary by PNO or service provider, the issuer should reach out to their
PNO or service provider relationship manager to confirm which of the following Configurations the
issuer host should support.
Configurations
For each Configuration and Version, all keys are required unless specified as optional, and keys in
italics are unique to each configuration:
// Version 1
// Configuration 1 (FPAN) // Configuration 2 (FPANID) // Configuration 3 (eFPAN)

version version version
nonce nonce nonce
nonceSignature nonceSignature nonceSignature
productType productType productType
name name name
auxiliaryCards (optional) auxiliaryCards (optional) auxiliaryCards (optional)
primaryAccountNumber primaryAccountIdentifier encryptedPrimaryAccountNumber
expiration primaryAccountNumberPrefix
networkName
// Version 0 Deprecated
// Configuration 1 (FPAN) // Configuration 2 (FPANID) // Configuration 3 (eFPAN)

version version version
nonce nonce nonce
nonceSignature nonceSignature nonceSignature
productType (optional) productType (optional) productType (optional)
name (optional) name (optional) name *
primaryAccountNumber primaryAccountIdentifier encryptedPrimaryAccountNumber
expiration primaryAccountNumberPrefix
networkName
// * The field ‘name’ is

required in Configuration 3
unless otherwise specified by
Apple, the issuer’s PNO, or
the issuer's service provider.
For more information on payment data format, refer to the ‘PKAddPaymentPassRequest’ section of
the 'Issuer Application-Based Provisioning’ documentation.
Keys
• ‘version’
Version 0 is deprecated - Version 1 is strongly recommended and will be enforced on future
updates.
• ‘name’
The ‘name’ key/value is required in Version 1 for all PNOs and service providers as specified in
the encryptedPassData specification.
• ‘productType’
The values for the key ‘productType’ are shown in the table below for each PNO.
For Visa Electron, the ‘productType’ depends on whether cards have a printed CVV or not. This
is to make sure Apple Wallet will never ask for CVV or Expiry if they are not printed on the card.
// MasterCard (Debit, Prepaid & Credit) & Maestro:

"productType":"DEFAULT_MASTERCARD"
// Visa (Debit, Prepaid & Credit):

"productType":"DEFAULT_VISA"
// Visa Electron & V Pay:

"productType":"01:NN:A0000000032010" // (No CVV, No Expiry)
"productType":"01:NY:A0000000032010" // (No CVV, Yes Expiry)
"productType":"01:YY:A0000000032010" // (Yes CVV, Yes Expiry)
For informational purposes, the next section - Section 5.6 - provides examples of the JSON
dictionary configurations for each PNO, with the keys provided in the ‘Configurations' above.
Note
Only the keys applicable for the particular Configuration the issuer is using should be present in the
specific payload the issuer will generate.
5.6. PNO Payment Data Examples PROVISIONING
This section provides examples of the JSON dictionary configurations for MasterCard (Debit,
Prepaid & Credit), Maestro, Visa (Debit, Prepaid & Credit), Visa Electron and V Pay brands.
Note
Prior to encryption the ‘nonce’ and ‘nonceSignature’ within the JSON dictionary must be HEX
encoded. If the issuer is provisioning Visa cards via VTS, the ‘encryptedPrimaryAccountNumber’ must
be Base64 encoded within the JSON dictionary.
JSON Dictionary for MasterCard (Debit, Prepaid & Credit) and Maestro
Use Configuration 1 and Version 1 for MasterCard (Credit, Debit, and Prepaid) and Maestro.
// Example of Version 1
{
"expiration":"01\/22",
"name":"John Appleseed",
"nonce":"c5846fb5",
"nonceSignature":"4061d9d63ed34825f285d953274a6c5e06ebe011bf91d79660e1f7c6f6d21427abb3a62
e6352e430abff987f6ec37e5dff9f3dbe40275156d03eeb594ab191d2792f37ef13ac528a65f56165c1d75346
3f",
"primaryAccountNumber":"5204245250001488",
"productType":"DEFAULT_MASTERCARD",
"version":"1"
}
// Example of Version 0 Deprecated

{
"expiration":"01\/22",
"name":"John Appleseed”,
"nonce":"c5846fb5",
"nonceSignature":"4061d9d63ed34825f285d953274a6c5e06ebe011bf91d79660e1f7c6f6d21427abb3a62
e6352e430abff987f6ec37e5dff9f3dbe40275156d03eeb594ab191d2792f37ef13ac528a65f56165c1d75346
3f",
"primaryAccountNumber":"5204245250001488",
"version":"0"
}
JSON Dictionary for Visa (Debit, Prepaid & Credit)
Use Configuration 3 and Version 1 for Visa (Debit, Prepaid & Credit) cards.
{
"primaryAccountNumberPrefix":"XXXXXX",
"encryptedPrimaryAccountNumber":"TUJQQUQtMS1GSy00MjYwNjQuMS0tVERFQS1BOEZFOEV
GRTdFNzlFNUI4RjI2MjdFOTdBMUM5MzNBMjQ2MTY2ODA3RjlFNjk3NTdCMUQ1RTU0M0JERjY1ODcxOTNEQ0JEOTUw
RTk0M0JGMEVBODg2MzYzM0QwMjBFNDZENTAwMDhCNUYwQ0U0MEQ2",
"nonceSignature":"408089C255A06E59FEF1702BA74715D96BC1C5CBD7CD6C90A6F06B94ED67D231765DA07
EEE3C16565DFD4AEF3DB71D2F652D659C233D6C279B22184ACBBDD0E13C8B237BF7FC3D9C827DAA76790B1937
98",
"networkName":"Visa",
"nonce":"08643998",
"productType":"DEFAULT_VISA",
"version":"1"
}
// Example of Version 0 Deprecated

{
“primaryAccountNumberPrefix":"XXXXXX",
"encryptedPrimaryAccountNumber":"TUJQQUQtMS1GSy00MjYwNjQuMS0tVERFQS1BOEZFOEV
GRTdFNzlFNUI4RjI2MjdFOTdBMUM5MzNBMjQ2MTY2ODA3RjlFNjk3NTdCMUQ1RTU0M0JERjY1ODcxOTNEQ0JEOTUw
RTk0M0JGMEVBODg2MzYzM0QwMjBFNDZENTAwMDhCNUYwQ0U0MEQ2",
"nonceSignature":"408089C255A06E59FEF1702BA74715D96BC1C5CBD7CD6C90A6F06B94ED67D231765DA07
EEE3C16565DFD4AEF3DB71D2F652D659C233D6C279B22184ACBBDD0E13C8B237BF7FC3D9C827DAA76790B1937
98",
"nonce":"08643998",
"version":"0"
}
JSON Dictionary for Visa Electron and V Pay

Use Configuration 3 with Version 1 for certain Visa Electron and V Pay cards.
{
"encryptedPrimaryAccountNumber":"TUJQQUQtMS1GSy00ODI0OTguMS0tVERFQS1BNTgzQjFDQ0MwNDE3NEU1
RUY1RjNFRUE5NTVEQTUxREY2NjhEMzRDRjhFNkE4RTgyMDc2NDFEN0UxRjQ5RTQ1Nzk4RjRBOEZGNzFFODFEQTYzN
EUzQUJERUQxNzcxODUwNDIxNjE4RkYwQjUwMzZCNTk1RkEyMDM4QzhEM0FDQg==",
"nonce":"49a990f4",
"nonceSignature":"40a63308d8b1659043b4e983f78564aa5a5e9a5c82fe05889a76cd9e9b81d4ae3f289cb
741f1e169dbac9d19329a90f34393ce00b854b04005c2ebea83d5c8be98e6876bb4cd9cb9a5bfe94879a4e727
98",
"productType":"01:YY:A0000000032010",
"version":"1"
}
5.7. Issuer Server Enablement Flag VERIFICATION PROVISIONING
The app shall support remote enablement / disablement of Apple Pay functionality via server
based flag. Such functionality allows card issuers to decouple the Apple Pay launch date with the
date when the app with Apple Pay functionality has to be released to App Store.
For example, the card issuer may release an updated version of the app with Apple Pay
functionality hidden a few days/weeks before the launch date.
On the day of launch, this would allow card issuers to have an already consistent user base that
could use Apple Pay functionality without the need of downloading the latest app version from App
Store.
6. Backend Implementation VERIFICATION PROVISIONING
6.1. In-App Provisioning Backend Overview PROVISIONING
This section provides a diagram and top-level step-by-step guide of the In-App Provisioning
process using ECC cryptography. For a more detailed technical overview, refer to Section 7.9.
Issuer Host Issuer App Apple Wallet Apple Servers PNO
START 1 2
5 4 3
6 7 8 9 END
Figure 10. In-App Provisioning Flow.
1. Issuer App to Apple Wallet: The user initiates the In-App Provisioning process by selecting the
'Add to Apple Wallet’ button in the app.
2. Apple Wallet to Apple Servers: Apple Wallet requests the Apple Public Certificates under
which the issuer host should encrypt the payment data payload.
3. Apple Servers to Apple Wallet: The Apple Public Certificates and nonce are provided to Apple
Wallet.
3.1. Apple Wallet to SE: Apple Wallet passes the nonce to the secure element for signing.
3.2. SE to Apple Wallet: nonceSignature is returned to Apple Wallet.
4. Apple Wallet to Issuer App: Apple Wallet then passes the Apple Public Certificates, nonce, and
the nonceSignature to the app.
5. Issuer App to Issuer Host: The issuer app passes the Apple Public Certificates, nonce, and the
nonceSignature to the issuer host.
6. Issuer Host to Issuer App: The issuer host then prepares the user’s payment data payload:
6.1. ephemeralPublicKey: The issuer host generates an ephemeral key pair (ephemeral private
key and Ephemeral Public Key) to be used only for a provisioning attempt.
6.2. encryptedPassData: The issuer host encrypts the payload with a shared key derived from
the Apple Public Certificates and the generated ephemeral private key.
6.3. The ephemeralPublicKey and the encryptedPassData are passed to the app.
6.4. activationData: The issuer host will also generate a cryptographic OTP according to the
PNO or service provider specifications.
6.5. The activationData is also passed to the app.
7. Issuer App to Apple Wallet: The issuer app passes the encryptedPassData, the
ephemeralPublicKey (assigned to the ephemeral private key used to encrypt the payment data
payload), and the activationData (cryptographic OTP) to Apple Wallet.
8. Apple Wallet to Apple Servers: Apple Wallet passes the details to the Apple Servers where
validation checks are performed.
9. Apple Servers to PNO: Payment data is passed to the PNO or service provider and the regular
provisioning flow commences.
6.2. In-App Verification Backend Overview VERIFICATION
This section provides diagrams and top-level step-by-step guides of the In-App Verification
process, which can be implemented by issuers using one of two methods:
A. Cryptographic OTP: This method leverages a cryptographic value that is generated by the
issuer host and validated by the PNO or service provider. Apple recommends issuers to support
this method as issuers can leverage the process of generating the cryptographic OTP value for
In-App Provisioning.
B. Server Initiated Activation: This method involves the issuer host initiating a pass activation
request to the device via the PNO or service provider.
There are a few steps common to both methods:
1. The user opens the issuer’s iOS mobile app either manually or by selecting the ‘Open
“bank_app”’ button from within Apple Wallet (see Figure 11).
2. The issuer iOS mobile app authenticates the user.
3. The issuer iOS mobile app determines whether any payment passes exist on the device or
paired Apple Watch that are pending activation.
4. After cross referencing the list of passes pending activation on the device with the list of
payment passes linked to the authenticated user on the issuer host, the In-App Verification
option can be presented to the user.
5. The cardholder navigates to and selects the link to activate the applicable inactive payment
pass provisioned on that device.
Figure 11. Open Bank App Button.
Method A: Cryptographic OTP
In order for the PNO or service provider to validate that the request to activate the pass originated
from an authorized issuer by an authenticated user, this method requires the use of a
cryptographic OTP value.
In the diagram and step-by-step guide below, the flow commences after the user has completed
the provisioning process via Apple Wallet. It is assumed that the bank has provided to Apple
servers, via the PNO, the “bank_app” OTP method within the
‘getOTPResolutionMethodsResponse’ API. Refer to Section 5.4 for more information.
Because the generation of the cryptographic OTP value is identical for both In-App Provisioning
and In-App Verification, Steps 2-5 in the diagram below share a similar path to Steps 6-9 in the
diagram for the In-App Provisioning Flow Overview.
1 START
2 3 4 5
END 7 6
Figure 12. In-App Verification Cryptographic OTP Flow.
1. Issuer App to Issuer Host: The issuer iOS mobile app reaches out to the issuer host to receive
the cryptographic OTP.
2. Issuer Host to Issuer App: The issuer prepares the cryptographic OTP:
2.1. activationData: The issuer host generates a cryptographic OTP according to the PNO or
service provider specifications.
2.2. The activationData is passed to the app.
3. Issuer App to Apple Wallet: The issuer’s app provides to Apple Wallet the activationData
(cryptographic OTP) as a parameter of the activate(_:activationData:completion:) method.
4. Apple Wallet to Apple Servers: Apple Wallet initiates a request to Apple servers to activate the
payment pass in question including the activationData.
5. Apple Servers to PNO: Apple servers initiate a ‘manageCardsRequest’ API to the PNO or
service provider which will then be responsible for validating the activationData generated by
the issuer host.
6. PNO to Apple Servers: Once the activationData is validated, the PNO or service provider will
initiate and transmit to the Apple servers a ‘manageCardResponse’ API to activate the pass in
question.
7. Apple Servers to Apple Wallet: Apple servers will pass the pass the activation request to Apple
Wallet which will then enable the pass for payment.
Important
The cryptographic OTP value must be provided by the issuer host to Apple Wallet via the issuer’s app,
which will initiate an activation request to Apple servers and, in turn, the PNO or service provider. The
issuer will need to contact their respective PNO or service provider to determine the appropriate
specifications needed to generate this value. Refer to Section 6.5 for more details.
Method B: Server Initiated Activation
In the diagram and step-by-step guide below, the flow commences after the user has completed
the provisioning process via Apple Wallet. It is assumed that the bank has provided to Apple
Servers, via the PNO, the “bank_app” OTP method within the
‘getOTPResolutionMethodsResponse’ API. Refer to Section 5.4 for more information.
1 START
END 4 3
Figure 13. In-App Verification Server Initiated Activation Flow.
1. Issuer App to Issuer Host: The issuer app calls out to the issuer host to request for the pass to
be activated.
2. Issuer Host to PNO: The issuer host forwards the activation request to the PNO or service
provider.
3. PNO to Apple Servers: The PNO or service provider sends a request to Apple for the pass to be
activated via a ‘submitCommandRequest' API with an ‘operationType’ of ‘Resume’.
4. Apple Servers to Apple Wallet: Apple servers notify the device to activate the payment pass,
which will then enable the pass for use with Apple Pay.
6.3. Certificates PROVISIONING
Validating Certificates
Via PKAddPaymentPassViewController, ECC public certificates will be provided to the app which
should then be passed to the issuer host.
1. The issuer host must first verify that the certificate chain is rooted in the Apple Certificate
Authority. This is an extremely critical step of the process as failing to validate the certificates
may potentially result in the issuer host encrypting the card details for a party other than Apple.
2. The issuer host must validate the chain of trust with the provided leaf certificate, sub CA
certificate, and finally the Apple Root CA - G3 Certificate from Apple Certificate Authority.
3. Additionally, the issuer host should also check to ensure the OID 1.2.840.113635.100.6.39 is
present and marked critical in the leaf certificate.
Generating Keys
Subsequently, the issuer host can extract the static public key and generate an ECC ephemeral
key pair.
1. The issuer host will then utilize the static public key from Apple and the generated ephemeral
private key to derive a shared secret.
2. The shared secret will be inputted into a KDF to calculate the shared key. Details for generating
the shared key can be found in Appendix B of the ‘Issuer Application-Based Provisioning’
specification.
3. The issuer host uses the derived shared key to encrypt the payment details
(encryptedPassData), and provide it to the iOS app along with the ephemeralPublicKey and
activationData.
Test Vectors and step-by-step instructions are available in Section 8.3.
Important
No cryptographic operations to support the transmission of payment data to Apple Wallet should be
performed on the iOS device - the cryptographic functions shall be performed by the issuer host.
6.4. Communication VERIFICATION PROVISIONING
Base64
The communication between the issuer host and app must be secured at the transport layer. In
addition to encrypting the communication, Apple recommends using Base64 (RFC 1421) when
transferring the Encrypted Payment Data configuration, the Ephemeral Public Key, and the
cryptographic OTP from the issuer host to the app.
iOS 7.0+
macOS 10.9+
Mac Catalyst 13.0+
watchOS 2.0+
• init(base64Encoded:options:)
The issuer’s app can use the iOS method init(base64Encoded:options:) to correctly initialize
the encryptedPassData, ephemeralPublicKey and the activationData properties of the
PKAddPaymentPassRequest class.
Important
Initialization of iOS APIs is often a source of errors - an incorrect initialization of iOS APIs can lead to a
cryptography error on Apple Server. Section 9 provides troubleshooting information.
6.5. PNO Activation Data VERIFICATION PROVISIONING
In addition to the Encrypted Payment Data payload, the issuer host must also provide a
cryptographic OTP value within the activationData property of the PKAddPaymentPassRequest for
In-App Provisioning. This value is defined by the PNO or service provider to facilitate the
verification of the provisioning request, and the process for generating the cryptographic OTP is
the same for both In-App Provisioning and In-App Verification.
For more information on the format of the activationData field, refer to the
PKAddPaymentPassRequest section of the ‘Issuer Application-Based Provisioning’
documentation. For any questions relating to the generation or validation of cryptographic OTP,
refer to the specifications from the issuer’s respective PNO or service provider.
Note
Apple will Base64 encode the cryptographic OTP prior to passing it to the PNO or service provider for
validation. The issuer must take this into consideration during development as well as when testing
this feature with the PNO or service provider.
The data used to define the activationData object, which is later passed to iOS via the APIs, should
appear as follows:
Visa
This must start with ‘MBPA’ (convert the Base64 cryptographic OTP to UTF-8 string).
MBPAC-1-FK-746098.1--TDEA-90DFCD26D2511AF8A601F9295B10658F1AE123D38CD6D8C12F1E8
MasterCard
This must be a valid JSON dictionary. Note that MasterCard currently supports two versions - the
issuer should contact their MasterCard representative for additional information.
{
"tokenUniqueReferenceIncluded":"XXXXX",
"signatureAlgorithm":"XXXXXXXX",
"signature":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"expirationDateIncluded":"XXXX",
"version":"X"
}
Note
For MasterCard, the cryptographic OTP is also know as the Tokenization Authentication Value (TAV).
7. Frontend Implementation VERIFICATION PROVISIONING
7.1. In-App Provisioning Frontend Overview PROVISIONING
When the user taps the ‘Add to Apple Wallet’ button for a specified card, the provisioning interface
will prompt the user to add the card to their iPhone, Apple Watch, or both devices (see Figure 14).
As mentioned in the Introduction, this is outside the control of the issuer’s app. In order for the
provisioning interface to determine which devices have not yet been provisioned with the specified
card, the issuer's app must correctly initialize the iOS APIs detailed in this section.
Figure 14. Add Card to Apple Pay & Select Device to Add Card.
Within the issuer's app, display the ‘Add to Apple Wallet’ Button only if a pass does not exist in
Apple Wallet on either the iPhone or Apple Watch:
• For iOS 13.4+ and watchOS 6.2+, the issuer can make use of the passes() and
remoteSecureElementPasses methods to determine whether any passes exist that fit this
criterion. These methods will return the FPANID, DPANID, FPAN suffix and DPAN suffix, and
the .PassActivationState of any applicable passes (for which deactivated is the state of a pass
which was previously provisioned but no longer exists in Apple Wallet).
• If a pass already exists in Apple Wallet (for which the .PassActivationState is either activated,
activating, requiresActivation or suspended), the issuer can replace the ‘Add to Apple Wallet’
button with text such as “Added to Apple Wallet” or “Available in Apple Wallet”.
• For iOS 9.0-13.4 and watchOS 2.0-6.2, refer to the equivalent APIs detailed in this section.
Important
The issuer is responsible for implementing all relevant APIs for current and future versions of their app.
The APIs in this section only return passes the issuer is entitled to access - the issuer’s app will only be
able to see a pass in Apple Wallet if the ‘associatedApplicationIdentifiers’ value is configured correctly.
If the issuer has not already configured the ‘associatedApplicationIdentifiers’ with their PNOs, refer to
Section 5.4 for more information.
7.2. In-App Verification Frontend Overview VERIFICATION
Within the issuer's app, display the option to activate a pass only if a pass exists that is pending
activation on either the iPhone or Apple Watch:
• For iOS 13.4+ and watchOS 6.2+, the issuer can make use of the passes() and
remoteSecureElementPasses methods to determine whether any passes exist that fit this
criterion. These methods will return the FPANID, DPANID, FPAN suffix and DPAN suffix, and
the .PassActivationState of any applicable passes (for which requiresActivation is the state of a
pass in Apple Wallet which is pending activation).
• Before presenting payment passes for activation, ensure the authenticated user owns the
respective payment passes. Cross reference the passes on the device with the passes linked to
the user’s card account on the issuer host system to ensure that only authenticated users who
own that particular payment pass have the authority to activate it on a particular device.
• Prompt the user immediately after initial login to activate a pass that is awaiting activation.
Alternatively, the app can trigger a different experience if the user is deep linked from Apple
Wallet for activation via the ‘appLaunchURL’ (refer to Section 5.4 for more information). In case
the user declines that option, provide an easy means within the iOS mobile app for the user to
initiate the process to activate the pass.
• For iOS 9.0-13.4 and watchOS 2.0-6.2, refer to the equivalent APIs detailed in this section.
Important
The issuer is responsible for implementing all relevant APIs for current and future versions of their app.
The APIs in this section only return passes the issuer is entitled to access - the issuer’s app will only be
able to see a pass in Apple Wallet if the ‘associatedApplicationIdentifiers’ value is configured correctly.
If the issuer has not already configured the ‘associatedApplicationIdentifiers’ with their PNOs, refer to
Section 5.4 for more information.
7.3. Get Passes VERIFICATION PROVISIONING
iOS 13.4+ iOS 9.0-13.4

watchOS 6.2+ watchOS 2.0–6.2
Mac Catalyst 13.4+ Mac Catalyst 13.0–13.4
• passes() • passes(of:)
For an iPhone, this method returns an array • PKPassType.payment
of type PKPass, for all available passes the
Deprecated
issuer is entitled to access.
For an iPhone, this method returns an array
of type PKPass when using parameter
PKPassType.payment, for all available
passes the issuer is entitled to access.
• remoteSecureElementPasses • remotePaymentPasses()
New Deprecated
For a paired Apple Watch, this method For a paired Apple Watch, this method
returns an array of type returns an array of type PKPaymentPass,
PKSecureElementPass for all available for all available passes the issuer is entitled
passes the issuer is entitled to access (the to access (the array will return empty if
array will return empty if there are no there are no passes available or there is no
passes available or there is no paired Apple paired Apple Watch).
Watch).
• canAddSecureElementPass(withPrimaryAc • canAddPaymentPass(withPrimaryAccountI
countIdentifier:) dentifier:)
New Deprecated
• primaryAccountIdentifier • primaryAccountIdentifier
New Deprecated
For an iPhone and paired Apple Watch, this For an iPhone and paired Apple Watch, this
method will return true or false using method will return true or false using
parameter primaryAccountIdentifier (this parameter primaryAccountIdentifier (this
parameter is provided by the PNO and is parameter is provided by the PNO and is
only available after the first provision of a only available after the first provision of a
card). card).
If using this method, the issuer must If using this method, the issuer must
correctly initialize the correctly initialize the
PKAddPaymentPassRequestConfiguration PKAddPaymentPassRequestConfiguration
with the primaryAccountIdentifier for each with the primaryAccountIdentifier for each
card after provisioning for the first time in card after provisioning for the first time in
the app. the app.
7.4. Pass Properties VERIFICATION PROVISIONING
iOS 13.4+ iOS 9.0-13.4

• PKSecureElementPass • PKPaymentPass
New An object of this type identifies payment
passes in Apple Wallet. The issuer can use
An object of this type identifies payment the methods of that class to get relevant
passes in Apple Wallet. The issuer can use information about their cards.
the methods of that class to get relevant
information about their cards.
• deviceAccountIdentifier • deviceAccountIdentifier
New Deprecated
The DPANID (an opaque identifier of the The DPANID (an opaque identifier of the
DPAN). The format and value is specified by DPAN). The format and value is specified by
the issuer’s PNO the issuer’s PNO.
• deviceAccountNumberSuffix • deviceAccountNumberSuffix
New Deprecated
The last four digits of the DPAN. The last four digits of the DPAN.
New Deprecated
The FPANID (an opaque identifier of the The FPANID (an opaque identifier of the
FPAN). The format and value is specified by FPAN). The format and value is specified by
the issuer’s PNO and is only available after the issuer’s PNO and is only available after
the first provision of a card. the first provision of a card.
• primaryAccountNumberSuffix • primaryAccountNumberSuffix
New Deprecated
The last four digits of the FPAN. The last four digits of the FPAN.
• .PassActivationState • PKPaymentPassActivationState
New Deprecated
The status of a card in Apple Wallet (e.g. The status of a card in Apple Wallet (e.g.
activated for an added card which has been activated for an added card which has been
verified, requiresActivation for an added verified, requiresActivation for an added
card which has not been verified). card which has not been verified).
7.5. Present ‘Add to Apple Wallet’ Button PROVISIONING
iOS 13.4+ iOS 9.0-13.4

• passes() • passes(of:)
• remoteSecureElementPasses • remotePaymentPasses()
New Deprecated
• deviceAccountIdentifier • deviceAccountIdentifier
• deviceAccountNumberSuffix • deviceAccountNumberSuffix
• primaryAccountNumberSuffix • primaryAccountNumberSuffix
New Deprecated
Using these methods and properties, obtain Using these methods and properties, obtain
the DPANID/FPANID and DPAN/FPAN suffix the DPANID/FPANID and DPAN/FPAN suffix
to determine whether to present the ‘Add to to determine whether to present the ‘Add to
Apple Wallet’ button. Apple Wallet’ button.
• canAddSecureElementPass(withPrimaryAc • canAddPaymentPass(withPrimaryAccountI
countIdentifier:) dentifier:)
New Deprecated
New Deprecated
Using this method and property, obtain the Using this method and property, obtain the
FPANID to determine whether to present FPANID to determine whether to present
the ‘Add to Apple Wallet’ button. the ‘Add to Apple Wallet’ button.
7.6. Initialize ViewController PROVISIONING
Provide key elements within PKAddPaymentPassRequestConfiguration which drive a positive user

experience for the In-App Provisioning view controller.
iOS 9.0+
Mac Catalyst 13.0+
• encryptionScheme
The encryption scheme to be used in the request.
• localizedDescription (optional)
The card product description to be displayed is defined within the ‘localizedDescription' key
(Figure 14).
• cardholderName (optional)
The cardholder name to be displayed is defined within the ‘cardholderName' key (Figure 14).
• primaryAccountSuffix (optional)
The Funding PAN suffix to be displayed is defined within the ‘primaryAccountSuffix’ key
(Figure 14). This value should be 4 digits and will have dots prepended to indicate that it is a
suffix.
• primaryAccountIdentifier (optional)
If the FPANID is passed to Apple Wallet within the ‘primaryAccountIdentifier’ key, Apple Wallet
will present only the devices on which the payment pass can still be provisioned (Figure 14).
This screen appears only on an iPhone with a paired Apple Watch.
• cardDetails
A list of optional fields in the form of “Label”, “Value” that will be displayed to the user before
initiating the provisioning process.
• paymentNetwork (optional)
If a value is provided within ‘paymentNetwork’ key, Apple Wallet will show only the artwork for
this specific payment network on the introductory page of the In-App Provisioning Flow. This
screen only appears if no card has previously been provisioned within Apple Wallet.
Important
ECC_V2 is the mandatory Encryption scheme. If ECC cannot be used in the issuer’s region, the issuer
should contact their Apple representative for an alternative.
7.7. Deep Link from Apple Wallet VERIFICATION PROVISIONING
If the ‘associatedStoreIdentifiers' value is configured correctly, the issuer’s app will be shown in the
back of the pass, and the issuer’s app will be launched when a user taps on the app link.
If the ‘appLaunchUrl’ value is configured correctly, the URL value will be passed to the issuer’s app
whenever the app is launched by Apple Wallet (e.g. during In-App Verification or when the user
taps on the issuer’s app icon from the back of the pass).
Important
The issuer must ensure the ‘associatedStoreIdentifiers' and ‘appLaunchUrl’ are correctly configured in
order to implement deep linking from Apple Wallet. Refer to Section 5.4 for more information.
Receive the ‘appLaunchURL'

The app receives this URL in the following methods of its app delegate:
iOS 9.0+ iOS 2.0-9.0
• application(_:open:options:) • application(_:handleOpen:)
Deprecated
• application(_:didFinishLaunchingWithOptions:)
No other parameter will be passed to the issuer’s app by Apple Wallet - the app will have to fetch
itself the list of cards already provisioned in Apple Wallet on iPhone and/or Apple Watch and their
status. Refer to Section 7.1 for In-App Provisioning and Section 7.2 for In-App Verification.
Important
If the issuer is implementing deep linking from Apple Wallet, the issuer must also make sure to
implement support for the URL without // (e.g. myapp:parameters). This is to address a bug in iOS 12
where the launch URL might not contain //.
The issuer can test deep linking from Apple Wallet using the Xcode simulator and command line:
xcrun simctl openurl booted myapp://parameters

xcrun simctl openurl booted myapp:parameters
7.8. Additional Implementation VERIFICATION PROVISIONING
Check the Eligibility of the App
iOS 9.0+
Mac Catalyst 13.0+
• canAddPaymentPass()
This method returns a Boolean value that indicates whether the app can add cards to Apple
Pay, and returns true if the app can add cards to Apple Pay.
Open the Payment Pass from the App
iOS 10.0+
Mac Catalyst 13.0+
• open(_:options:completionHandler:)
• passUrl
The app can open the pass in Apple Wallet by using open(_:options:completionHandler:) and
pass as argument the passUrl.
Activate Pass
iOS 13.4+ iOS 8.0-13.4

watchOS 2.0-6.2
• activate(_:activationData:completion:) • activate(_:withActivationData:completion:)
New Deprecated
Activates a payment pass using the Activates a payment pass using the
provided activation code. provided activation code.
Password Autofill
Starting with iOS 12 Apple keyboard can suggest the security code into the app. The following link
provide a detailed overview of how to use the Password Autofill workflow.
7.9. In-App Provisioning Flow Technical Overview PROVISIONING
This section provides a diagram and technical step-by-step guide of the In-App Provisioning
process using ECC cryptography. For a top-level overview featuring steps 1-9, refer to Section 6.1.
START
1 2
5 4 3
6 7 8 9
END G F
Figure 15. In-App Provisioning Flow.
A. Issuer App to Apple Wallet: The issuer app checks the eligibility of the device using
canAddPaymentPass().
B. Issuer App to Apple Wallet: For iOS 13.4+ and watchOS 6.2+, the issuer app checks existing
passes with passes() and remoteSecureElementPasses or
canAddSecureElementPass(withPrimaryIdentifier:). For iOS 9.0-13.4 & watchOS 2.0-6.2, the
issuer app checks existing passes with passes(of:) and remotePaymentPasses() or
canAddPaymentPass(withPrimaryIdentifier:).
1. Issuer App to Apple Wallet: The user initiates the In-App Provisioning process by selecting the
‘Add to Apple Wallet’ button in the app. Present the ‘Add to Apple Wallet’ button using
PKAddPassButton, then initiate the In-App Provisioning View Controller using
PKAddPaymentPassRequestConfiguration and PKAddPaymentPassViewController.
2. Apple Wallet to Apple Server (Provisioning Certificates): Apple Wallet requests the Apple
Public Certificates under which the issuer host should encrypt the payment data payload. This
is part of the delegate call PKAddPaymentPassViewControllerDelegate.
3. Apple Server to Apple Wallet: The Apple Public Certificates and nonce are provided to Apple
Wallet.
3.1. Apple Wallet to SE: Apple Wallet passes the nonce to the secure element for signing.
3.2. SE to Apple Wallet: nonceSignature is returned to Apple Wallet.
4. Apple Wallet to Issuer App: Apple Wallet sends the Apple Public Certificates, nonce &
nonceSignature to the issuer app.
5. Issuer App to Issuer Host: The issuer app passes the Apple Public Certificates, nonce, and the
nonceSignature to the issuer host.
6. Issuer Host to Issuer App: The issuer host generates the encryptedPassData,
ephemeralPublicKey & activationData and sends these to the app.
7. Issuer App to Apple Wallet: The issuer app passes the encryptedPassData,
ephemeralPublicKey and activationData to Wallet through the PKAddPaymentPassRequest
class.
8. Apple Wallet to Apple Servers: Apple Wallet passes the encryptedPassData and
ephemeralPublicKey to the Apple Servers where validation checks are performed.
9. Apple Servers to PNO (Network Check Card): Apple Servers pass the encryptedPassData
and ephemeralPublicKey to the PNO or service provider.
C. PNO to Apple Wallet: The PNO or service provider sends the T&Cs to Apple Wallet.
D. Apple Wallet to PNO (Link & Provision): The user agrees to the T&Cs and Apple Wallet sends
the activationData to the PNO or service provider.
E. PNO to Issuer Host: The PNO validates the activationData and completes final approval checks
with the issuer host.
F. PNO to Apple Wallet: The PNO sends the successful activation status to Apple Wallet.
G. Apple Wallet to Issuer App: The user sees that the card has been successfully activated, and
Apple Wallet dismisses the In-App Provisioning View Controller.
8. Testing VERIFICATION PROVISIONING
8.1. Sandbox Environment VERIFICATION PROVISIONING
Apple offers the possibility to test In-App Provisioning cryptography using the Apple Pay Sandbox
environment. Refer to the Apple Pay Sandbox website for more information.
Important
Sandbox is available for issuers’ testing worldwide irrespective of the list of countries that is specified
in the website, which only applies to merchant testing.
Sandbox for In-App Provisioning is currently limited to selected PNOs and Service Providers.
Developers could use the MasterCard Sandbox cards listed in the Apple Pay Sandbox website to
initially prototype In-App Provisioning implementation. This method provides a way to test In-App
Provisioning cryptography in a pre-production environment irrespectively of the issuer’s PNOs.
Sandbox Configuration
To develop In-App Provisioning or In-App Verification using Apple Pay Sandbox the issuer should
follow these steps:
1. Create a Sandbox iCloud account using App Store Connect (refer to ‘Create a Sandbox Tester
Account’ section at the link above) - note that a new email address never associated with an
iCloud account before must be used.
2. Login into iCloud on the test device using the account from the previous step.
3. Open Apple Wallet and add one card from the list of cards available on Apple Pay Sandbox
page.
4. If the issuer is able to successfully add a Sandbox card to their device they are ready to develop
using Sandbox.
The issuer has now successfully configured the Apple Pay Sandbox. The issuer should see the
word ‘Sandbox’ when they open Apple Wallet.
Sandbox Recommendations
• The issuer must ensure they have received the Apple Pay Provisioning Entitlement
• The issuer should build and test their app using the Sandbox environment above, and can side
load their app to a device via Xcode
• The issuer can use the test vectors and the server sample code (available upon request) to
build their server component
• The issuer can start testing their implementation using one of the Mastercard sandbox cards.
Use JSON version 0 configuration 1 (FPAN)
Note
The purpose of Sandbox is to test the issuer’s cryptography - it is not a tool or environment intended
for testing the different color provisioning flows.
8.2. Production Environment VERIFICATION PROVISIONING
Testing shall be performed in the production environments using production devices via Ad-hoc
Provisioning Profiles, TestFlight or the production App Store by means of Promo Codes, after the
necessary approvals.
For TestFlight and App Store, be sure to budget additional time for the App Review process as
approval time may vary.
Important
It is the responsibility of the issuer to ensure the In-App Provisioning functionality is thoroughly tested
in the app across all supported iOS versions and devices prior to release to the general public.
Ad-hoc Provisioning Profiles

For preliminary testing, make use of ad-hoc provisioning profiles to install the app on devices
available to the issuer. Note that the issuer must have the UDIDs for the devices in order to test the
issuer app with this method. Refer to Xcode Help for more information.
TestFlight
The app will need to be approved by App Review, but can be distributed more easily than via ad-
hoc provisioning profiles by leveraging TestFlight. To obtain the app via TestFlight, the user must
be part of the issuer’s App Store Connect team with an assigned role of Admin, Technical, App
Manager, Developer, or Marketer. Refer to the Developer website for additional information.
Important
For all testing with TestFlight, the issuer must set the minimum supported build to iOS 10.3 or later.
When the issuer does eventually build the app for the production App Store, the issuer may move the
minimum supported iOS version back to iOS 9.0 or later.
App Store Promo Codes

For complete end to end testing, distribute the app via the production App Store after submission
to App Review. The distribution of the app for testing purposes via the production App Store must
be through the use of Promo Codes. Refer to the Developer website for more information on the
use of Promo Codes for limiting the distribution of an app via the App Store.
The issuer must select “Manual Release” when submitting their app for App Review, otherwise the
issuer may inadvertently release the test app to the general public. Once testing is complete, the
app can be made available for public download by selecting “Release This Version” within App
Store Connect. In case changes have been made to the app after inclusion on the App Store for
testing, the issuer will need to “Cancel This Release” within App Store Connect. The issuer can
then re-submit their corrected app to the App Store for approval. Refer to the Developer website
for additional information.
Note
For Ad-hoc Provisioning Profiles and TestFlight, the issuer app is not available from Apple Wallet.
8.3. In-App Provisioning Test Vectors PROVISIONING
This step-by-step guide details the process for using test vectors. To help the issuer test their
issuer host encryption as well as their app interface with Apple Wallet, Apple has provided test
vectors (including a sample set of public certificates, plaintext, ephemeral key pair, shared secret,
shared key, and cipher text), and a detailed step-by-step guide on how to use them.
The following section contains an example with ‘production-like’ data that can be used to validate
the issuer’s backend implementation of In-App Provisioning cryptography.
Steps 1-6 cover the issuer server side cryptography, whereas steps 7-8 refer to how data can be
passed to the issuer App with an example of how to correctly initialize iOS APIs.
Once the issuer has validated their ability to generate each data point, the issuer has successfully
validated their cryptography with the test vectors (Steps 1 to 6).
Important
All data is HEX encoded unless otherwise stated.
Step 1: Extract Public Key from Leaf Certificate
After the issuer has verified the validity of the certificate chain, the first step consists of extracting
the Apple public key from the leaf certificate.
Input
// Apple Leaf Certificate (Sample, PEM Format, Base64 encoded):
-----BEGIN CERTIFICATE-----
MIIEEjCCA7igAwIBAgIIEccnFAKsD+UwCgYIKoZIzj0EAwIwgYExOzA5BgNVBAMMMlRlc3QgQXBwb
GUgV29ybGR3aWRlIERldmVsb3BlcnMgUmVsYXRpb25zIENBIC0gRUNDMSAwHgYDVQQLDBdDZXJ0aW
ZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTk
wODA3MjA1NzA5WhcNMjEwNzEzMDI1ODAwWjBtMTYwNAYDVQQDDC1lY2MtY3J5cHRvLXNlcnZpY2Vz
LWVuY2lwaGVybWVudF9VQzYtSW5NZW1vcnkxETAPBgNVBAsMCEFwcGxlUGF5MRMwEQYDVQQKDApBc
HBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABC4+XM9rmrBL56
IvP6zP3nPIfocVU5SjSBVAiolsoYo3TaxmmvO/
YiD8hjdn9K9HUHxbwiH8ShmHTa85tAdOPrijggIrMIICJzAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYM
BaAFNbW1Vrl//3CfDTDQ969aHZcNqm+ME8GCCsGAQUFBwEBBEMwQTA/
BggrBgEFBQcwAYYzaHR0cDovL29jc3AtdWF0LmNvcnAuYXBwbGUuY29tL29jc3AwNC10ZXN0d3dkc
mNhZWNjMIIBHQYDVR0gBIIBFDCCARAwggEMBgkqhkiG92NkBQEwgf4wgcMGCCsGAQUFBwICMIG2DI
GzUmVsaWFuY2Ugb24gdGhpcyBjZXJ0aWZpY2F0ZSBieSBhbnkgcGFydHkgYXNzdW1lcyBhY2NlcHR
hbmNlIG9mIHRoZSB0aGVuIGFwcGxpY2FibGUgc3RhbmRhcmQgdGVybXMgYW5kIGNvbmRpdGlvbnMg
b2YgdXNlLCBjZXJ0aWZpY2F0ZSBwb2xpY3kgYW5kIGNlcnRpZmljYXRpb24gcHJhY3RpY2Ugc3Rhd
GVtZW50cy4wNgYIKwYBBQUHAgEWKmh0dHA6Ly93d3cuYXBwbGUuY29tL2NlcnRpZmljYXRlYXV0aG
9yaXR5LzBBBgNVHR8EOjA4MDagNKAyhjBodHRwOi8vY3JsLXVhdC5jb3JwLmFwcGxlLmNvbS9hcHB
sZXd3ZHJjYWVjYy5jcmwwHQYDVR0OBBYEFK0uo8t+NMLt7kNoTicRH8xJMznQMA4GA1UdDwEB/
wQEAwIDKDASBgkqhkiG92NkBicBAf8EAgUAMAoGCCqGSM49BAMCA0gAMEUCIQCKEXnIsY2PZqMF2x
HKehKgp/ZywZ/9/TZ+AnpOA6mI/AIgTI94NSaIn7DLd47QTK760WILDOr0EdOHiExJMZwYp7c=
-----END CERTIFICATE-----
Operation Parse the leaf certificate and extract the Apple Public Key.
Output
// Apple Public Key in uncompressed format (65 bytes):
042E3E5CCF6B9AB04BE7A22F3FACCFDE73C87E87155394A34815408A896CA18A374DAC669AF3B
F6220FC863767F4AF47507C5BC221FC4A19874DAF39B4074E3EB8
Step 2: Ephemeral Key Pairs
On the issuer server, generate the Ephemeral Key Pairs.
Output
// Ephemeral Public Key in uncompressed format (65 bytes):
0499A6F42E83EA4F150A78780FFB562C9CDB9B7507BC5D28CBFBF8CC3EF0AF68B36E60CB10DB6
9127830F7F899492017089E3B73C83FCF0EBDF2C06B613C3F88B7
// Ephemeral Private Key (32 bytes):

7EEE47DEE108A08EDD2BCD2BB762A543CA23EA96C9AF09AD54BEB9FA3CE1A026
The Ephemeral Private Key is expressed as HEX encoded integer value. The associated curve is
the “NIST P-256”.
Step 3: Elliptic-curve Diffie–Hellman
The Elliptic-curve Diffie–Hellman algorithm is used to generate the Shared Secret. As input keys
use the Apple Public Key from the leaf certificate and the Ephemeral Private Key generated on the
issuer server.
Input
// Apple Public Key in uncompressed format (From Step 1):
042E3E5CCF6B9AB04BE7A22F3FACCFDE73C87E87155394A34815408A896CA18A374DAC669AF3B
F6220FC863767F4AF47507C5BC221FC4A19874DAF39B4074E3EB8
// Ephemeral Private Key (From Step 2):

7EEE47DEE108A08EDD2BCD2BB762A543CA23EA96C9AF09AD54BEB9FA3CE1A026
Operation Use Apple Public Key and Ephemeral Private Key as parameters in the Shared
Secret function.
Output
// Shared Secret (32 bytes):
A88B995FECBDF756515ED42BA53A6CCCA4F5936F69CF4D15352C94C592B347B1
Important
The issuer’s implementation shall now discard the Ephemeral Private Key.
Step 4: NIST Single-step KDF
The NIST Single-step KDF parameterized with the SHA-256 hash function is used to derive a 256
bit key. The following are the inputs to the KDF.
Input
// Counter (4 bytes):
00000001
// Shared Secret (From Step 3, 32 bytes):

A88B995FECBDF756515ED42BA53A6CCCA4F5936F69CF4D15352C94C592B347B1
// Other Info (84 bytes):
// Algorithm ID Length (1 byte):

0D
// Algorithm ID ("id-aes256-GCM", 13 bytes):

69642D6165733235362D47434D
// Party U Info ("Apple", 5 bytes):

4170706C65
// Ephemeral Public Key (From Step 2, 65 bytes):

0499A6F42E83EA4F150A78780FFB562C9CDB9B7507BC5D28CBFBF8CC3EF0AF68B36E60CB10
DB69127830F7F899492017089E3B73C83FCF0EBDF2C06B613C3F88B7
Operation Generate the other info as specified in NIST SP 800-56A, Section 5.8.1 as well as
Appendix B of the ‘Issuer Application-Based Provisioning’ Specification.
Concatenate values in order shown above.
Output
// KDF Input (120 bytes):
00000001A88B995FECBDF756515ED42BA53A6CCCA4F5936F69CF4D15352C94C592B347B10D696
42D6165733235362D47434D4170706C650499A6F42E83EA4F150A78780FFB562C9CDB9B7507BC
5D28CBFBF8CC3EF0AF68B36E60CB10DB69127830F7F899492017089E3B73C83FCF0EBDF2C06B6
13C3F88B7
Note
Counter, Algorithm ID Length, Algorithm ID, Party U Info are all static whereas Shared Secret and
Ephemeral Public Key are dynamic and different for each attempt.
Step 5: Symmetric AES Key
From the KDF input, the issuer can generate the AES key which is used for encryption in Step 6.
Input
// KDF Input (From Step 4):
00000001A88B995FECBDF756515ED42BA53A6CCCA4F5936F69CF4D15352C94C592B347B10D696
42D6165733235362D47434D4170706C650499A6F42E83EA4F150A78780FFB562C9CDB9B7507BC
5D28CBFBF8CC3EF0AF68B36E60CB10DB69127830F7F899492017089E3B73C83FCF0EBDF2C06B6
13C3F88B7
Operation As specified in NIST SP 800-56A, Section 5.8.1 apply SHA-256 hash function to
the KDF Input to generate the shared AES key.
Output
// AES symmetric key (32 bytes):
083080D3D0C521C02CD3AE2134363D09EA50DFF914677FAB9E22F18F9C28A3B9
Important
The hash function must be applied to the binary data of the KDF Input and not its HEX representation.
Step 6: AES GCM Encryption
The AES symmetric key is used to encrypt the JSON payload with the AES cypher in GCM mode
with null byte IV. The resulting output shall include the AES GCM Message Authentication Code
(MAC) after the encrypted data.
Input
// AES Key (From Step 5):
083080D3D0C521C02CD3AE2134363D09EA50DFF914677FAB9E22F18F9C28A3B9
// JSON Payload (67 bytes), UTF-8 encoded:

{"Parameter1":"Value1","Parameter2":"Value2","Parameter3":"Value3"}
Operation AES-256 Encryption in GCM mode with 12 null byte IV. The AES MAC GCM is
appended at the end of the encrypted data.
Output
// Encrypted Data + AES GCM MAC (67 + 16 = 83 bytes):
E3EF6BA2FFA05B6985FE129E3CB6845C4EA1E94AE98D31A538A4E24906FB720D764D640894CD9
DE7CEC00114396651A1CCAEDCF480C57A959E925C04492B9CF85FC711FAB3CBED10DC2BA99A2B
B063CEFF8DE1
Important
The length of the output data must match the length of the input data + the length of the AES GCM
MAC. The issuer must ensure the crypto routine outputs the MAC AES GCM after the encrypted data.
Step 7: Transferring Data to the Issuer App
Once the encrypted data is generated in Step 6 the issuer host then generates the Activation Data
(the cryptographic OTP required to activate the card by the network).
After the Activation Data has been generated, the ‘Activation Data’, ‘Ephemeral Public Key’ and
‘Encrypted Data’ need to be encoded as Base64 strings and sent as a JSON back to the app.
For more information on the input refer to the PKAddPaymentPassRequest documentation.
Input
// Activation Data:
// network specific
// Ephemeral Public Key (From Step 2, 65 bytes):

0499A6F42E83EA4F150A78780FFB562C9CDB9B7507BC5D28CBFBF8CC3EF0AF68B36E60CB10DB6
9127830F7F899492017089E3B73C83FCF0EBDF2C06B613C3F88B7
// Encrypted Data + AES GCM MAC (From Step 6) (67 + 16 = 83 bytes):

E3EF6BA2FFA05B6985FE129E3CB6845C4EA1E94AE98D31A538A4E24906FB720D764D640894CD9
DE7CEC00114396651A1CCAEDCF480C57A959E925C04492B9CF85FC711FAB3CBED10DC2BA99A2B
B063CEFF8DE1
Operation Encode ‘Activation Data’, ‘Ephemeral Public Key’, and ‘Encrypted Data with GCM
MAC’ as Base 64 string and create a JSON using the resultant strings.
Output
// JSON Payload sent back to client iOS app (Base 64 encoded):
{
"activationData":"bmV0d29yayBzcGVjaWZpYw==",
"ephemeralPublicKey":"BJmm9C6D6k8VCnh4D/tWLJzbm3UHvF0oy/
v4zD7wr2izbmDLENtpEngw9/iZSSAXCJ47c8g/zw698sBrYTw/iLc=",
“encryptedData”:”4+9rov+gW2mF/
hKePLaEXE6h6UrpjTGlOKTiSQb7cg12TWQIlM2d587AARQ5ZlGhzK7c9IDFepWeklwESSuc+F/
HEfqzy+0Q3CupmiuwY87/jeE="
}
Step 8: PKAddPaymentPassRequest API
Once the app receives the JSON described in Step 7 the issuer can use
init(base64Encoded:options:) to initialize the relevant field of that class in a binary format. The API
accepts the most common Base64 formats.
The example below details how to use the API to initialize the field in binary by starting from its
Base64 representation:
Example
// Base64 Representation
ephemeralPublicKeyBase64 = “BJmm9C6D6k8VCnh4D/tWLJzbm3UHvF0oy/
v4zD7wr2izbmDLENtpEngw9/iZSSAXCJ47c8g/zw698sBrYTw/iLc="
ephemeralPublicKey = Data(base64Encoded: ephemeralPublicKeyBase64, options:

[])
Once the data has been initialized, PKAddPaymentPassRequest holds the card data needed to add
a card to Apple Pay.
Refer to Section 9 for additional information on how to debug iOS API initialization.
9. Troubleshooting VERIFICATION PROVISIONING
9.1. Sysdiagnose & SEID VERIFICATION PROVISIONING
During In-App Provisioning development phase, it is essential that the issuer is able to collect logs
on their device and check those logs for potential error messages. This is also essential when
reporting issues to Apple.
Sysdiagnose
In order to collect Apple Pay logs on device, one of the following three profiles must be installed
using these instructions:
• iPhone / iPad Profile

• MacBook Profile
• Apple Watch Profile
Once collected, the logs will be available in a file named ‘Sysdiagnose’.
SEID
The SEID (Secure Element Identifier) identifies the secure element of the device where the pass
data is signed and stored. It is a HEX encoded string.
For all communications with Apple, the issuer must provide:
• the SEID of the test device

• the timestamp (including timezone) of the attempt
• the FPAN suffix of the card
Hint
The device SEID can be found in: Settings > General > About > SEID.
The issuer can also use the device SEID to search within logs.
9.2. Sysdiagnose Analysis VERIFICATION PROVISIONING
This step-by-step guide details how to analyze a Sysdiagnose. The issuer must follow the
instructions in Section 9.1 before proceeding with the steps below.
Step 1: Open ‘systems_logs.logarchive’

When the issuer un-tar a sysdiagnose on their machine, they will see a ‘system_logs.logarchive’,
file. On macOS, double click and open the file, and it will open the file in console. This will provide a
useful GUI or searching and filtering data. Once the Log console is open, the issuer will be able to
use the search bar, located at the top right hand corner, to find specific errors. Figure 16 shows an
example of the Console Log.
Enter search terms here.

Process and Message information See Step 2 for more information.
Detailed log
Figure 16. Typical view of a ‘log archive’.
Step 2: Enter Search Terms

In the search bar enter either the:
• SEID* of the device - this helps to isolate the Apple Pay client/server communication
• Process : Passbook (filter passbook logs)
• Error status
Searching the above will display result in the output to be updated. If the issuer provides the SEID,
they are likely to see the messages with a process: PassbookUIService. The logs presented on
screen provide a clear indication of the errors that are visible to Apple.
Step 3: Analyze Request
The SEID is particularly useful to quickly filter the Apple Pay activity. When performing an SEID
search, the log archive will display Apple Pay logs including the In-App Provisioning client-server
communication between Apple Wallet and Apple Server.
For example, the issuer could see which data is sent by Apple Wallet to Apple Server during In-App
Provisioning requests.
REDACTED
Detailed log
Figure 17. Log archive filtered on SEID.
The example in Figure 17 shows the log for the POST request where Apple Wallet sends the In-App
Provisioning cryptography data to Apple Server. By looking at that request the issuer can evaluate
whether the class PKAddPaymentPassRequest and its fields ephemeralPublicKey,
encryptedPassData, and PKEncryptionScheme* were correctly initialized.
Note
*EV_ECC_v2 is currently the encryption scheme and version to be used unless instructed differently by
Apple.
Below an extract of the log shown in the POST request message:
Performing request:
POST https://pr-pod2-smp-device.apple.com:443/broker/v4/devices/[Redacted]/cards
{
"Accept-Language" = de;
…[Other data not logged here]
}
{
encryptedPassData =
"0OZHGdjwpP0ZxePlHagTp6uttS7l4CTlCNzAPGYgOIFXS4cbE07KxmHjzc7m1vfRH77i1zW0hhltYZYGHAjpGlXg
yGgHZqOru8eqTgQgJJdvfEeILemfaxh+L05kHeccjCIOBP2XbwOxTzNjAK2a75lAfSrSwDCh3DZntB+W2YyESQNSb
u/xqmSIo3o0N2nUqDeCCQiNEBJEgL//Fr/
44ThgMABZ6qBTjmKbT7hGR90aFSpGp20Dep0603vkl8L4Rfc2g1WFRQevyqtj4Jc5dIfB4h4JndRk5qJVj6K2IHe4
fGGlJa0q5IXhidhtlSseOyIpD+uNbkYVnTr83QH42/iB6q+dmTJ9eU59HXI9q/
CRvZnSGkbZX35ZILzD+E9fMPpuBB4xG4G32KqcU4Zw/
PMuHULXdqCUgKZDJx+OM0PywRIV1GKVdGulNYzpIubHuXmrmKRE44tnHwaiE4RRhgg9ykxKMzQDC2Qscu8xBIIkTW
vcdC8gCEFUKA+qWY2Gs+85/OWG/
TGbngWPy0UYH70mhLWlCJ8gcaAnQw9xv01qEp0BLwCk0GkXKtBaZKFwWhQAc+dwgEAJIyt0j8Z3npm2jiWU6ZD0Wt
p6SkjB6DbrFTxz/FsB7PeE2hlm3pxwwMFsj4xYfIBTOMNJs0YAtExcEriOd0QaLcX5KA==";
encryptionVersion = “EV_ECC_v2";
ephemeralPublicKey =
“BJDEmk593wJyfxQ07ed9KckQbzO9nG6jIsA0FCL+GyuxAF9TGcqHmLpsa6Is5Jp7SWRzwPNZYCvGa8d888cF6KY=
";
...[Other data not logged here]

}
After reviewing the highlighted information above, the issuer can evaluate the data sent from the
issuer to the PNO. The information above should correspond to the data they have obtained in
their logs and should not differ.
9.3. Cryptographic Errors VERIFICATION PROVISIONING
This step-by-step guide details the process for debugging cryptography errors. The error 500
indicates a generic failure, which could be an error in the implementation of the cryptographic
routines (key derivation, encryption, etc), an error in the way data is transferred across systems
(issuer host, issuer app, and iOS APIs) or an error in the JSON dictionary.
Step 1: Data Format and iOS API Initialization

When initializing the PKAddPaymentPassRequest make sure that data is in the correct format.
Step 2: Base64 Encoding to Initialize iOS APIs

If the issuer passes data from their backend to the app, using a Base64 encoding (recommended),
they can use the init(base64Encoded:options:) API to initialize the relevant field of that class in a
binary format. The API accepts the most common Base64 formats. The example below details how
to use the API to initialize the field in binary by starting from its Base64 representation.
ephemeralPublicKeyBase64 = “BJmm9C6D6k8VCnh4D/tWLJzbm3UHvF0oy/v4zD7wr2izbmDLENtpEngw9/
iZSSAXCJ47c8g/zw698sBrYTw/iLc=="
ephemeralPublicKey = Data(base64Encoded: ephemeralPublicKeyBasee64, options: [])
Important
The ephemeralPublicKey must be in uncompressed format (65 bytes long).

When outputted in HEX it must starts with '04'.
If the key is not in uncompressed format the process will fail.
Step 3: Double Encoding

A common error is when the data has been ‘double-encoded’ (once as outputted from the crypto
module on the server-side, and once before sending it to the client still on the server-side). In that
case even a correct initialization of iOS API’s as in 'Step 2' will result into an error as Apple Server
will receive the double encoded version of the data.
Step 4: Detailed Analysis
Based on the issuer’s ability to log data or to side load certificates choose one of these two options
for further analysis:
1. The issuer should request an ‘In-Memory’ Certificate from Apple to be used for encryption
instead of the certificate received from iOS API’s. Send then the output data
(ephemeralPublicKey and encryptedPassData) to Apple for analysis.
2. If the steps above do not solve the issue, provide Apple with the full set of logs. The issuer
should log each step of their backend encryption including key generation and intermediate
parameters and Apple should be able to debug their implementation. Output each field in
Base64 or HEX format:
• Apple Environment Certificate: Production, Sandbox, Test Vector.

• Extracted Public Key from Apple Certificate (Base64 or HEX).
• JSON dictionary to be encrypted (UTF-8 encoded String).
• Ephemeral Public Key (Base64 or HEX).
• Ephemeral Private Key (Base64 or HEX).
• Input to the KDF function (Base64 or HEX).
• Derived AES Key (Base64 or HEX).
• Encrypted Data (Base64 or HEX).
9.4. In-App Provisioning Errors PROVISIONING
There could be several reasons that may cause an unsuccessful provision of a card. This section
consists of a sample subset of use cases that the issuer can use as a reference to compare their
log output. Each scenario is accompanied by example outputs from Apple Wallet.
Note
Scenarios 1-2 cover errors that happen before the user is presented with T&Cs.
Errors that happen after the user has accepted T&Cs are reported in Scenarios 3-5.
REDACTED
REDACTED
REDACTED
Figure 18. Log Archive - Generic Error.
Figure 19. Log Archive - Invalid ‘appLaunchURL’.
Figure 20. Card Not Added.
Scenario 1
Scenario Card Not Added’ Before T&Cs
Details Enter the SEID of the device in the Search bar located in the top right hand corner.
This will output a set of logs with requests and responses, looking through the log
output, the issuer can select the ‘request’ message, as shown in Figure 18, where
the highlighted field displays an output specific to the chosen message.
For this use case, the information that can be validated in the ‘request’ is the
encryptedPassData and the ephemeralPublicKey, as this is the data that is sent
from the device to the server.
In Figure 18, the issuer can view the the log archive request / response. Below the
log archive, the response from the server is displayed in a more readable format,
with the error code highlighted. The response yields an ‘error 500’ which is a
generic error, and reasons to resolve are listed in the resolution section.
Response
Response: ...[Other data not logged here]
{
}
{
statusCode = 500;
statusMessage = "Broker Service Response exception”;
}
Cause There are multiple reasons why the issuer may receive this error:
A. Cryptography error, wrong data encoding, or invalid JSON dictionary

B. Whitelisting (Incorrect Adam ID is whitelisted)
C. Issue with the resources such as T&Cs and Card Art being loaded
Resolution A. Cryptography Error, wrong data encoding, or invalid JSON dictionary:

Use the cryptography implementation and validation pages to resolve any
issues with the issuer’s cryptography or data format.
B. Whitelisting (Incorrect Adam ID is whitelisted):

This applies only for tests done in production.
• Has the issuer requested the whitelisting of their app’s Adam ID? Refer to
Section 5.2 for additional details.
• If yes, is the issuer distributing their app via TestFlight? Refer to Section 8.2
for additional details.
C. Issue with the resources such as T&Cs and Card Art being loaded:
This is highly unlikely to be error. It may typically happen in pre-production
environments where the configuration on the payment network portal may be
subject to frequent changes. To exclude this error try to add the card manually
via Apple Wallet. If the issuer sees the T&Cs while adding the card manually
they can rule out this problem. If the manual provisioning fails, the issuer should
contact their respective PNO, and attempt to re-upload their T&Cs to the PNO.
Figure 21. Unsupported Card.
Scenario 2
Scenario In-eligible Card
Details As opposed to Scenario 1, in this case the server responds with a status code
‘200’, which means the request completed successfully. However, by looking at the
response the issuer can see that the server returned the card as non eligible (i.e.
’eligibilityStatus= 0’).
Response
{
"Content-Length" = 57;
"Content-Type" = "application/json";
Date = "Tue, 21 May 2019 04:40:57 GMT”;
"x-conversation-id" = 086063f209b34b84bee028a75c6af0f2;
}
{
errorCode = 40403;
}
Cause Card details provided are not eligible for Apple Pay (e.g. card not whitelisted by
PNO / Issuer).
Resolution The issuer should check with their PNO that the card has been correctly
configured.
Scenario 3
Scenario Issuer Declines Provisioning: ‘Red Flow’ Response
Response
{
"Content-Length" = 57;
"Content-Type" = "application/json";
Date = "Tue, 21 May 2019 04:40:57 GMT”;
"x-conversation-id" = 086063f209b34b84bee028a75c6af0f2;
}
{
errorCode = 40403;
}
Cause A failure after the user has accepted T&Cs is often related to a decline on the
issuer side. The declined is represented by a ‘Red Response’. This could be caused
by several factors. For example, it may be the issuer declining the attempt or it may
be the PNO responding on behalf of the issuer is the response takes too long to be
processed.
By looking at the logs for this type of error the issuer can see that they have an
error code which has returned ‘40403’, where the device would display: “Could not
add Card, Try again later or contact your card issuer for more information”.
Resolution Red flow is the response provided from the issuer’s respective PNO, in this event,
they should contact their PNO, with the ‘conversationID’. Using this the PNO
should be able to identify the underlying reason for the response.
Figure 23. Successful Provision.
Scenario 4
Scenario PNO Declines due to Invalid Activation Data
Response
Performing request:
POST ...[Other data not logged here]
{
}
{
activationData =
"eyJ2ZXJzaW9uIjoiMiIsImV4cGlyYXRpb25EYXRlSW5jbHVkZWQiOnRydWUsInRva2VuVW5pc
XVlUmVmZXJlbmNlSW5jbHVkZWQiOmZhbHNlLCJzaWduYXR1cmVBbGdvcml0aG0iOiJSU0EtU0h
BMjU2Iiwic2lnbmF0dXJlIjoiQzhSSmJFL0svUDM5Nmc2d2thdkR1bUtVc015MTdlT1JPWUlXM
2lnY0lXYU1iOHEweXlrM1R6S0lzQWNjT2NTSXJmeHdQM3NwdTAySlNuakJQQWhxOUg0bzRuMjg
xNTgrSlJFTzYxK2tIRHZmcy8vYWxhR2N0Rm1jUW9tNWJDd3ZyR0N5djNUaFZmRnFKblJsN3Jie
TRXR3Y3MHFFY2xGZVdEa0svLzdWdHdIRG01T2Q4WG1OSkQ1VE5LTGZsczQ5SWdjQ1ZDZ1lHNFV
vdTh0RmJtWTFaMjF5Q1BQcUJJSk80a0d0WGFTTVB1OWZtdjdpeDltOUNhbDl2UE1CS3FDeTBYL
y9GLzBtM2NuYmlEMDhFUER1RjB5TVluYWhFbE5ydXZNd2lqelRwZXhEMG9ZSGZEUzlBOHk2cmZ
6VVZjOE5rQmx0QlJQdGdsKzVBTlhybmI5QTJBPT0ifQ==";
deviceName = "iPhone (2)";
}
Cause To evaluate the ‘activationData’ that is needed to activate the card by the PNO.
Searching the SEID, produces an output that contains a ‘POST’ request. An
example of the request is detailed below.
Resolution Reviewing the ‘activationData’ field the issuer can evaluate the data and compare
this with their logs, to verify that the ‘activationData’ sent in the request is
accurate.
Scenario 5
Scenario Other Reasons for Failure after T&Cs
Details For a result on a device that displays: “Could not set up Apple Pay” or “Card Not
Added”, using the wallet profile, generate a sysdiagnose. Selecting the ‘Errors and
Faults’ tab, in the top left-hand corner, will display all the errors and faults for the
sysdiagnose. Searching for “PassbookUIService” under the ‘Process’ tab, the
issuer will be able to review the specific errors relating to either the Invalid Launch
URL, Card Art, Card Metadata, and Invalid notification server address.
Cause Metadata errors like the ones outlined above, require resolution via contacting the
issuer’s respective PNO (Payment network operator). The issuer should partner
with their PNO to resolve the issues involving metadata.
For Figure 19, Invalid ‘appLaunchURL’ produces a result where the issuer can see
in the response message they have the following error: ‘Invalid data error reading
the pass paymentpass.com.apple…’
This is reiterated in the response message output, for this use case specifically, the
issuer will see an issue with the metadata regarding an invalid ‘appLaunchURL’.
Other similar cases may involve card art not being properly sized or the card art
resources not available.
Resolution In general, amend the card metadata accordingly. In the example in Figure 19, the
‘appLaunchURL’ was updated as specified in Section 5.4.

Getting Started With Apple Pay In-App Provisioning, Verification & Security (3.0)

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Getting Started With Apple Pay In-App Provisioning, Verification & Security (3.0)

Uploaded by

Copyright:

Available Formats



Getting Started with Apple Pay

08/31/2015 Draft Initial

01/06/2016 1.1 Added language regarding Adam ID submission.

Added FPAN/DPAN suffix, passesOfType, remotePaymentPasses as methods to determine

Minor wording changes.

Consolidated separate documentation: ’In-App Provisioning Security Guidelines’ (now

AES Advanced Encryption Standard

API Application Programming Interface

CTA Call to Action

DPAN Device PAN

E2E End to End

ECC Elliptic Curve Cryptography

FPAN Funding PAN

GCM Galois/Counter Mode

HEX Hexadecimal Format (e.g. 0x0102AABF)

IDE Integrated Development Environment

JSON JavaScript Object Notation

MAC Message Authentication Code

MFA Multi Factor Authentication

NIST National Institute of Standards and Technology

OID ISO Object Identifier

OTP One Time Password

PAN Primary Account Number

POST HTTP POST request

PNO Payment Network Operator

RSA Rivest–Shamir–Adleman algorithm

SEID Secure Element ID

T&Cs Terms and Conditions

URL Universal Resource Link

UTF-8 8-bit Unicode Transformation Format

1.1. In-App Provisioning PROVISIONING

Cancel Done You are all set!

Apple Watch Card Number 5412

Add to Apple Wallet

Learn more about Apple Pay

Freeze my card: OFF

App Apple Wallet App

Figure 1. In-App Provisioning User Flow.

Optional: In-App Verification tested in Sandbox*

3.1. Promoting Apple Pay Availability PROVISIONING

Splash Screens, Banners & Links

Figure 2. Promoting availability.

Buttons & Marks

• The Apple Pay mark design documentation

Refer to the additional design resources for more information.

Scenario 1 - app installation / re-installation

iPhone  Pay Pay post Card view

Please include all

Scenario 2 - existing customer login into the app

iPhone Password /  Pay Pay post Card view

Figure 3. Splash Screen User Flows.

‘Add to Apple Wallet’ Button

Figure 4. ‘Add to Apple Wallet’.

• iOS API: openPaymentSetup()

Figure 5. Set up Apple Pay Button.

‘Pay with Apple Pay’ Button

For additional information refer to present(_:) from PKPassLibrary.

Figure 6. Pay with Apple Pay Button.

4.1. Requirements & Recommendations VERIFICATION PROVISIONING

Meet Security Controls Requirements

Refer to Section 4.2 for additional information.

Provisioning Path Recommendations