Onboard push provisioning for Wallets

Apple Pay entitlement

To support tokenization for Apple Pay (in-app provisioning and in-app verification), request the special entitlement com.apple.developer.payment-pass-provisioning from Apple.

Requesting entitlement and whitelist

To request the entitlement and whitelist for your issuer application, send the following information to [email protected]:

Subject

Apple Pay Entitlement & Whitelisting Request - Issuer Name - [Country Code]. For example, Apple Pay Entitlement & Whitelisting Request - MyBank - [DE]

Body

Issuer Name. For example, MyBank.
Country [Country Code]. For example, Germany [DE].
Team ID. Your team ID is available from Apple Developer Membership. For example, 1234ABCD.
Adam ID. Your Adam ID is the Apple ID listed in your App Store Connect - App Store Information. For example, 1234567890.
App Name. For example, MyBanking.

Configuring the entitlement in Apple Developer website

Go to Apple Developer Membership and log in to your account.

Select Certificates, IDs & Profiles and select Identifiers.

Select your application bundle ID from the list.

After approval has been granted, the Additional Capabilities tab will be visible. Go to the tab and select In-App Provisioning.

Configuring the entitlement in Xcode

Go to step 2 if you already configured the entitlement in the issuer application. Otherwise, add a new Property List file to your project with the file extension .entitlements. For example, App.entitlements.

To add a new Property List file, go to your target, then to Build Settings as shown in the following figure. Set Code Signing Entitlements to the path of the newly created file, for example, App/App.entitlements. Alternatively, you can set CODE_SIGN_ENTITLEMENTS in xcconfig.

Setting code signing entitlements in xcconfig

// path to your entitlements file
CODE_SIGN_ENTITLEMENTS = App/App.entitlements

Go to your entitlement files. Add a new key, com.apple.developer.payment-pass-provisioning, with type Boolean and value 1 either by editing the file directly or through Xcode.

This entitlement is not visible in the Signing & Capabilities tab.

Adding entitlement in the file

<?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/>
</dict>
</plist>

TSP configuration

The issuer must configure the following key/value pairs in the TSP system for In-App Provisioning and In-App Verification:

contactName
bank_app
associatedApplicationIdentifiers
associatedStoreIdentifiers
appLaunchUrl

For more details, see section 5.4. PNO Pass Metadata Configuration in the document Getting Started with Apple Pay In-App Provisioning, Verification & Security (shared by Apple).

A common problem is misconfiguring associatedApplicationIdentifiers in the TSP system.

This issue typically prevents the issuer from reading the card digitization state from Apple Pay.

Google Pay

If you plan to integrate push provisioning with Google Pay, perform the following steps.

Request access to Google’s documentation

Google's Android Push Provisioning API documentation is not public. If you cannot access it, sign in or request the access.

Key requirements from Google

The content is intended for issuers that have a signed contract to integrate with Google Pay.
Partners must use a Google Account associated with their corporate email address rather. Personal email accounts (such as Gmail, Yahoo Mail, and MSN) cannot be associated with an NDA and therefore will not be granted access.

Request issuer application access to Push Provisioning API

Your development team must request access before the application can use Google's Push Provisioning API and the Thales Push Provisioning service.

Google provides the access based on the app package name and its fingerprint. These fields have to be registered by app developers by means of submitting an Push Provisioning API Access Request form.

This step is especially important for internal and test builds of the application.

Problem with gaining access to Push Provisioning API leads typically to an error reported by D1 SDK saying Google Pay Unavailable at the configuration step.

If that is the case for your app, then please review the app's package name and fingerprint vs. the values submitted in the form above.

Best practices and branding guidelines

Check the best practices guide for integration recommendations on provisioning cards into Google Pay.

Follow Google's branding guidelines which define the style of "Add to Google Pay" button.

TSP configuration

The issuer must configure the following settings in the TSP system to comply with Google Pay's requirements:

Terms of Service
Card metadata including card art

For more details, see Google's guide on TSP configuration.

A common issue is misconfiguring the application package name in the TSP system as described in the Common issues with metadata section of the Google's guide.

This issue prevents the application from reading the card digitization state from Google Pay.

Google Pay launch process

Before the application can be published on Google Play Store, the development team has to pass several review and testing steps with Google. See Google's launch process page.

Samsung Pay

For Samsung Pay, it is required to have the following configurations set before integrating D1 SDK to your issuer application:

Register your mobile app

Go to Samsung Pay Developers and create an account to sign up.
Follow the steps in Getting Started section on how to onboard as a Samsung Pay developer.

Upload the release version of your app

Follow the steps mentioned in "App to app card enrollment integration guide" document located in Samsung Pay guides to upload your app to SAMSUNG PAY developer console.

Service ID

Create the Service ID in the Samsung Pay Developers portal. The Service ID combines the Application and a certificate signing request (CSR), or other parameters used to identify the partner application.

For more information, refer to Samsung Pay Developers portal on Service Creation.

The Service ID is passed to the Config class during the configuration of D1 SDK. An example of the Service ID is shown as follows:

Service 1 = <com.issuer.walletapp, CSR1_US>

For issuers using Visa and Mastercard Tokenization (that is, VTS or MDES), a CSR is not required.

Issuer name

Configure ISSUER NAME in the Samsung Pay Developers portal to match the issuer name configured in the TSP.

If ISSUER NAME does not match the issuer name configured in the TSP, the issuer application will not be able to read the card digitization state from Samsung Pay.

See Samsung Pay FAQ & Troubleshooting for more details and steps how to verify that the card is provisioned with a proper issuer name.

Samsung Pay configurations

Debug API key

This data is used to verify the application that uses Samsung Pay scheme to interact with the Samsung Pay application. Debug API key can be retrieved by registering a new service on Samsung Pay Developers portal. There are some points that the application has to be aware of on the Debug API key:

It is valid for only three months and may change at the discretion of Samsung.
The value may be revoked by Samsung for unresolved issues caused by the application.
The application is able to request an additional Debug API key after 90 days.
The total number of devices that can use the key is unlimited. However, a partner is limited to 10 Samsung accounts for testing leading to Samsung certification.
The application should not display this value in the debug log.
It is to be removed in the release configuration.

The following code snippet shows an example on how to add the Debug API key to the AndroidManifest.xml file.

<application>
    <meta-data android:name="spay_debug_api_key"
               android:value="qwertyuiop1234567"/>
</application>

Debug mode

The following setting is only used for debug or testing purposes. If the integrator uses the release version of the SDK in a debug or release version of the app, the debug_mode must be set to 'Y' in the AndroidManifest.xml file and add the following code snippet:

<application>
    <meta-data android:name="debug_mode"
               tools:replace="android:value"
               android:value="Y"/>
</application>

This is only for debug or testing purposes. During the final release process, the integrator must remove the above from manifest file and follow the Samsung documentation for release mode.

Package visibility queries (Android 11+)

From Android R OS (if target SDK version is 30) onwards, you must declare <queries> in the Android manifest file.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:tools="http://schemas.android.com/tools"
  package="xxx.xxx.xxx.xxx">
  <queries>
    <package android:name="com.samsung.android.spay" />
    <package android:name="com.samsung.android.samsungpay.gear" />
  </queries>
</manifest>

Obfuscation

If you use ProGuard with Samsung Pay, the following rules are commonly required:

# Samsung Pay
-keep class com.samsung.android.sdk.** { *; }
-keep interface com.samsung.android.sdk.** { *; }

If you use DexGuard, the following rules are commonly required:

-keepresourcexmlelements manifest/application/meta-data@name=debug_mode 
-keepresourcexmlelements manifest/application/meta-data@name=spay_debug_api_key 
-keepresourcexmlelements manifest/application/meta-data@name=spay_sdk_api_level

PreviousInitial Setup Next3. Initialization

Last updated 4 months ago

Was this helpful?