Apple wallet extension

Apple wallet extension

Use Apple Wallet extensions to let end users discover and provision cards directly from the Apple Wallet application, in addition to the issuer application.

Through application extensions, you can expose custom functionality and content outside the issuer application and make it available while the end user interacts with Apple Wallet or the system.

Provisioning cards within the Apple Wallet application improves the in-app experience by avoiding manual entry of payment card details.

Refer to the Apple extension overview for general information about iOS extensions.

User experience

The end-to-end Apple Wallet extension flow has two main phases:

1. Apple Wallet discovers that the issuer application has cards available for provisioning.
2. The end user authenticates and selects which cards to add; Apple Wallet then requests the provisioning payload from the issuer application via the D1 SDK.

Discovery and authentication

Apple Wallet shows the issuer application as an option when cards are available for provisioning.

1

Discover issuer application in Apple Wallet

Apple Wallet checks with the issuer application to determine whether cards are available. If cards are available, the issuer application appears in the list of options.

2

The end user selects the issuer application

When the end user selects the issuer application, Apple Wallet triggers the issuer application UI extension to authenticate the end user.

3

Authenticate the end user

The issuer application’s UI extension authenticates the end user using the same credentials and methods (for example, manual login and biometrics) as the main issuer application.

Selecting and provisioning cards

Apple Wallet fetches and displays the cards available from the issuer application.

1

Apple Wallet fetches available cards

Apple Wallet requests the list of available cards from the issuer application through the non-UI extension. The end user sees a list of cards to add.

2

View card details

The end user can review card details (for example, card art, product title, and last four digits) before adding the card.

3

Accept terms and conditions

The end user reviews and accepts the issuer’s and payment network’s terms and conditions.

4

Provisioning payload and tokenization

For each selected card, Apple Wallet requests a provisioning payload from the issuer application and then initiates the tokenization flow with the payment network TSP.

Extensions

The Apple Wallet integration requires two types of extensions from the issuer application:

• Non-UI extension Reports the status of the extension flow and card availability. This covers the card discovery and provisioning payload steps. It is implemented by extending the D1 SDK base class D1IssuerProvisioningExtensionHandler.
• UI extension Authenticates the end user. This is a separate screen that uses the same login credentials as the issuer application. It implements the D1IssuerProvisioningExtensionAuthorizationProviding protocol.

Apple Wallet extensions are installed at the same time as the issuer application. For Apple Wallet to detect that there are passes to add and to show the extension, the end user must launch the issuer application at least once.

D1 SDK provides a base implementation for the non-UI extension so that you do not need to implement the complete logic yourself. The issuer application calls D1Task.configure() with WalletExtensionConfig during application launch to share card details with the extension. While this configuration is required only once after installation, we recommend calling it on every application launch to keep card information up to date.

High-level flow: the issuer application configures the D1 SDK so Apple Wallet can discover cards.

After successful authentication in the UI extension, the issuer application must call D1IssuerProvisioningExtensionAuthorizationProviding.bindingHash() to retrieve the encoded hashed client binding payload (cbp). The issuer application must pass this cbp value to the issuer backend when requesting the issuer token. Then it must call D1IssuerProvisioningExtensionAuthorizationProviding.login() so the SDK can continue the non-UI extension flow.

The bindingHash() value is different in the issuer application and in the extension. Generate a separate issuer access token for the extension.

Sequence diagrams

1. Apple Wallet shows the issuer application button

Apple Wallet discovers that the issuer application has cards available for provisioning.

2. End user authentication

Apple Wallet launches the issuer application UI extension for authentication.

3. Available cards are displayed

Apple Wallet requests the list of available cards and shows them to the end user.

4. Tokenization

Apple Wallet requests provisioning payloads and tokenizes the selected cards.

Integrate Apple Wallet via the D1 SDK

SDK configuration

When you perform iOS SDK initialization, the issuer application must also call configure(ConfigParams.walletExtensionConfig(...)) and provide:

cardParamsList

Use this variant when you have a single consumerId and a single issuerId:

• cardParamsList – List of card IDs, card art, product titles, and last four digits. Card art and product title are displayed in Apple Wallet.
• appGroupID – The shared container ID so the D1 SDK can share data between the issuer application and its extensions.

let coreConfig = ConfigParams.coreConfig(consumerID: "<obtained from server>")
let cardConfig = ConfigParams.cardConfig()

let card = ConfigParams.CardParams(cardID: "<obtained from server>",
        cardArt: UIImage(named: "<image_name>")!, productTitle: "<product title>", last4: "<last4>")
let walletExtensionConfig = ConfigParams.walletExtensionConfig(cardParamsList: [card],
        appGroupID: "<App Group ID defined in app capabilities>")

d1Task.configure([coreConfig, cardConfig, walletExtensionConfig]) { errors in
    if let errors = errors {
        for error in errors {
            // Inspect errors to identify which configuration failed
            // Refer to the D1 SDK integration error management section
        }
    }
}

// Save consumerId to authenticate the same end user in the wallet extension flow
saveToKeychain(key: "D1ConsumerID", value: "<consumer_ID>")

func saveToKeychain(key: String, value: String) {
    guard let valueData = value.data(using: .utf8) else {
        return
    }
    let query: [String: Any] = [kSecClass as String: kSecClassGenericPassword,
        kSecAttrService as String: "<service associated, e.g. IssuerAppService>",
        kSecAttrAccessGroup as String: "<App Group ID defined in app capabilities>",
        kSecAttrAccount as String: key]
    var addQuery = query
    addQuery[kSecValueData as String] = valueData
    let status = SecItemAdd(addQuery as CFDictionary, nil)

    if status == errSecDuplicateItem  {
        let updatedData: [String: Any] = [kSecValueData as String: valueData]
        SecItemUpdate(query as CFDictionary, updatedData as CFDictionary)
    }
}

issuerParamsList

Use this variant when you support multiple combinations of issuerId and consumerId:

• issuerParamsList – List of cardParamsList with the corresponding issuerId and consumerId.
• appGroupID – The shared container ID so the D1 SDK can share data between the issuer application and its extensions.

let coreConfig = ConfigParams.coreConfig(consumerID: "<obtained from server>")
let cardConfig = ConfigParams.cardConfig()

var issuerParamsList: [ConfigParams.IssuerParams] = []
let card1 = ConfigParams.CardParams(cardID: "<obtained from server>",
        cardArt: UIImage(named: "<image_name>")!, productTitle: "<product title>", last4: "<last4>")
let card2 = ConfigParams.CardParams(cardID: "<obtained from server>",
        cardArt: UIImage(named: "<image_name>")!, productTitle: "<product title>", last4: "<last4>")
let card3 = ConfigParams.CardParams(cardID: "<obtained from server>",
        cardArt: UIImage(named: "<image_name>")!, productTitle: "<product title>", last4: "<last4>")
let issuerParam1 = ConfigParams.IssuerParams(cardParams: card1, issuerID: "<issuerId 1>", consumerID: "<consumerId 1>")
let issuerParam2 = ConfigParams.IssuerParams(cardParams: card2, issuerID: "<issuerId 2>", consumerID: "<consumerId 2>")
let issuerParam3 = ConfigParams.IssuerParams(cardParams: card3, issuerID: "<issuerId 2>", consumerID: "<consumerId 3>")
issuerParamsList.append(issuerParam1)
issuerParamsList.append(issuerParam2)
issuerParamsList.append(issuerParam3)

let walletExtensionConfig = ConfigParams.walletExtensionConfig(issuerParamsList: issuerParamsList,
        appGroupID: "<App Group ID defined in app capabilities>")

d1Task.configure([coreConfig, cardConfig, walletExtensionConfig]) { errors in
    if let errors = errors {
        for error in errors {
            // Inspect errors to identify which configuration failed
            // Refer to the D1 SDK integration error management section
        }
    }
}

// Save issuerId values for use during wallet extension authentication
saveToKeychain(key: "issuerID1", value: "<issuerId 1>")
saveToKeychain(key: "issuerID2", value: "<issuerId 2>")

func saveToKeychain(key: String, value: String) {
    guard let valueData = value.data(using: .utf8) else {
        return
    }
    let query: [String: Any] = [kSecClass as String: kSecClassGenericPassword,
        kSecAttrService as String: "<service associated, e.g. IssuerAppService>",
        kSecAttrAccessGroup as String: "<App Group ID defined in app capabilities>",
        kSecAttrAccount as String: key]
    var addQuery = query
    addQuery[kSecValueData as String] = valueData
    let status = SecItemAdd(addQuery as CFDictionary, nil)

    if status == errSecDuplicateItem  {
        let updatedData: [String: Any] = [kSecValueData as String: valueData]
        SecItemUpdate(query as CFDictionary, updatedData as CFDictionary)
    }
}

We strongly recommend using the last4 parameter.

Without last4, the SDK may misinterpret tokenization status in shared-device scenarios. For example, if User A tokenizes a card and then User B logs into the same issuer application on the same device, the SDK might incorrectly assume tokenization is already complete for User B.

App Group ID

By default, the issuer application and its extensions do not share storage. Use app groups to share storage between them. See the Apple extension overview for more details.

appGroupID identifies the shared container between the issuer application and its extensions. You configure it in Xcode under Capabilities.

Example of configuring an app group in Xcode for the issuer application and its extensions.

Ensure that the App Group ID is correctly added to Xcode before using it in configure(ConfigParams.walletExtensionConfig(...)). Otherwise, the D1 SDK returns the invalidAppGroupID error.

Apple Pay entitlement

Similar to in-app Apple Pay provisioning, you must add the entitlement com.apple.developer.payment-pass-provisioning to both the UI and non-UI extension targets. For onboarding details, refer to your Apple Wallet provisioning documentation or Push provisioning onboarding for wallets.

UI extension

Create a UI extension

Create an Intents UI Extension target in Xcode for the Apple Wallet UI extension.

1

Add a new target in Xcode of type Intents UI Extension.

2

In the new target, enable the same App Group ID and entitlement values as in the issuer application. If the App Group ID differs, the login API returns the walletExtensionAppGroupIDNotFound error.

3

Update the extension Info.plist:

• Set NSExtensionPointIdentifier to com.apple.PassKit.issuer-provisioning.authorization.
• Set NSExtensionPrincipalClass to a class that conforms to D1IssuerProvisioningExtensionAuthorizationProviding.

Example entitlements and extension configuration:

<?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.security.application-groups</key>
    <array>
        <string>group.com.example.IssuerApp</string>
    </array>
</dict>
</plist>

<?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>NSExtension</key>
    <dict>
        <key>NSExtensionPointIdentifier</key>
        <string>com.apple.PassKit.issuer-provisioning.authorization</string>
        <key>NSExtensionPrincipalClass</key>
        <string>$(PRODUCT_MODULE_NAME).IntentViewController</string>
    </dict>
</dict>
</plist>

Integrate the SDK for the UI extension

The D1 SDK provides the D1IssuerProvisioningExtensionAuthorizationProviding protocol, which extends Apple’s PKIssuerProvisioningExtensionAuthorizationProviding and adds bindingHash() and login() APIs.

In the UI extension, implement a view controller that conforms to D1IssuerProvisioningExtensionAuthorizationProviding, authenticates the end user, calls bindingHash() to retrieve the cbp, requests the issuer token from the issuer backend with this cbp, and then calls login. See your SDK login documentation for token generation.

Login with a single issuerId

import UIKit
import PassKit
import D1

class IntentViewController: UIViewController, D1IssuerProvisioningExtensionAuthorizationProviding {
    var completionHandler: ((PKIssuerProvisioningExtensionAuthorizationResult) -> Void)?
    private let authButton = UIButton(type: .system)

    override func viewDidLoad() {
        super.viewDidLoad()
        // Configure UI layout
        authButton.addTarget(self, action: #selector(authButtonTouched), for: .touchUpInside)
    }

    @objc func authButtonTouched() {
        // Load authentication-related data from Keychain (at minimum consumerID)
        let consumerID = loadFromKeychain(key: "D1ConsumerID")

        // Provide both manual and biometric authentication methods as required by Apple

        Task {
            do {
                let cbp = try await self.bindingHash()
                var issuerToken = getAccessToken(sub: consumerID!, cbp: cbp)
                try await self.login(&issuerToken)

                await MainActor.run {
                    self.completionHandler?(.authorized)
                }
            } catch {
                await MainActor.run {
                    self.completionHandler?(.canceled)
                }
            }
        }
    }

    func loadFromKeychain(key: String) -> String? {
        let getQuery: [String: Any] = [kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: "<service associated, e.g. IssuerAppService>",
            kSecAttrAccessGroup as String: "<App Group ID defined in app capabilities>",
            kSecAttrAccount as String: key,
            kSecReturnData as String: true]
        var item: AnyObject?
        let status = SecItemCopyMatching(getQuery as CFDictionary, &item)
        if status == errSecSuccess,
           let data = item as? Data {
            return String(data: data, encoding: .utf8)
        }
        return nil
    }

    func getAccessToken(sub: String, cbp: String) -> Data? {
        // Use cbp when requesting the issuer token from the issuer backend
        return Data()
    }
}

Login with multiple issuerIds

import UIKit
import PassKit
import D1

class IntentViewController: UIViewController, D1IssuerProvisioningExtensionAuthorizationProviding {
    var completionHandler: ((PKIssuerProvisioningExtensionAuthorizationResult) -> Void)?
    private let authButton = UIButton(type: .system)

    override func viewDidLoad() {
        super.viewDidLoad()
        // Configure UI layout
        authButton.addTarget(self, action: #selector(authMultiIssuerButtonTouched), for: .touchUpInside)
    }

    @objc func authMultiIssuerButtonTouched() {
        // Load issuer IDs from Keychain
        let issuerId1 = loadFromKeychain(key: "issuerID1")
        let issuerId2 = loadFromKeychain(key: "issuerID2")

        // Provide both manual and biometric authentication methods as required by Apple

        Task {
            do {
                let cbp = try await self.bindingHash()
                let issuerToken1 = getAccessToken(iss: issuerId1!, cbp: cbp)
                let issuerToken2 = getAccessToken(iss: issuerId2!, cbp: cbp)
                var issuerTokens = [issuerToken1, issuerToken2]

                try await self.login(&issuerTokens)

                await MainActor.run {
                    self.completionHandler?(.authorized)
                }
            } catch {
                await MainActor.run {
                    self.completionHandler?(.canceled)
                }
            }
        }
    }

    func loadFromKeychain(key: String) -> String? {
        let getQuery: [String: Any] = [kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: "<service associated, e.g. IssuerAppService>",
            kSecAttrAccessGroup as String: "<App Group ID defined in app capabilities>",
            kSecAttrAccount as String: key,
            kSecReturnData as String: true]
        var item: AnyObject?
        let status = SecItemCopyMatching(getQuery as CFDictionary, &item)
        if status == errSecSuccess,
           let data = item as? Data {
            return String(data: data, encoding: .utf8)
        }
        return nil
    }

    func getAccessToken(iss: String, cbp: String) -> Data {
        // Use cbp when requesting the issuer token from the issuer backend
        return Data()
    }
}

If cards share the same issuerId but have different consumerId values, generate a single issuerToken for that issuerId.

Non-UI extension

Create a non-UI extension

Create an Intents Extension target in Xcode for the Apple Wallet non-UI extension.

1

Add a new target in Xcode of type Intents Extension. Clear Include UI Extension because the UI extension was created previously.

2

In the new target, enable the same App Group ID and entitlement values as in the issuer application. If the App Group ID differs, D1 SDK operations return the walletExtensionAppGroupIDNotFound error.

3

Update the extension Info.plist:

• Set NSExtensionPointIdentifier to com.apple.PassKit.issuer-provisioning.
• Set NSExtensionPrincipalClass to a class that extends D1IssuerProvisioningExtensionHandler.

Example entitlements and extension configuration:

<?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.security.application-groups</key>
    <array>
        <string>group.com.example.IssuerApp</string>
    </array>
</dict>
</plist>

<?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>NSExtension</key>
    <dict>
        <key>NSExtensionPointIdentifier</key>
        <string>com.apple.PassKit.issuer-provisioning</string>
        <key>NSExtensionPrincipalClass</key>
        <string>$(PRODUCT_MODULE_NAME).IntentHandler</string>
    </dict>
</dict>
</plist>

Integrate the SDK for the non-UI extension

The D1 SDK provides the base class D1IssuerProvisioningExtensionHandler, which extends Apple’s PKIssuerProvisioningExtensionHandler and implements the required APIs. In most cases, you only need to extend this class.

import D1

class IntentHandler: D1IssuerProvisioningExtensionHandler {
}

Error handling

Optionally, override errorEncountered(_:) in the non-UI extension to log or track errors received during the extension flow.

import D1

class IntentHandler: D1IssuerProvisioningExtensionHandler {

    override func errorEncountered(_ error: D1Error) {
        print("Error = \(error.localizedDescription)")
    }
}

Typical error cases include:

• The appGroupID is invalid or not found.
• The D1 backend returns an error.

# Example: error in status API
SDK Error = Error in status API. Cause: [2](-25300) Failed storage access. 
Error: [20009]The appGroupID is not found in Apple Pay Wallet UI and Non-UI extension. 
It could be due to several reasons: In the main application, there is no wallet extension 
configuration by calling `D1Task.configure(_:completion:)` with 
`ConfigParams.walletExtensionConfig(cardParamsList:appGroupID:)` OR 
the appGroupID defined in the main application capabilities is not defined in the UI 
and non-UI extension targets capabilities.

# Example: error in passEntries API
SDK Error = Error in passEntries API. Cause: [3]Received a server error with 
HTTP error code 400 and message 'Server error'. Error: [40001]Errors encountered 
whilst executing card operations.

# Example: error in remotePassEntries API
SDK Error = Error in remotePassEntries API. Cause: [3]Received a server error 
with HTTP error code 400 and message 'Server error'. Error: [40001]Errors encountered 
whilst executing card operations.

# Example: error in generate API
SDK Error = Error in generate API. Cause: [3]Received a server error with 
HTTP error code 400 and message '911. Operation failed .1'. Error: [40001]Errors encountered 
whilst executing card operations.

Apple functional requirements

To align with Apple’s functional requirements, the D1 SDK D1IssuerProvisioningExtensionHandler and the issuer application adopt the following practices:

• Display card art and cardholder name.
• Determine whether cards are available (eligibility) within 100 ms of Apple invoking the API.
• Provide card art and app icons with squared edges.
• Support both manual and biometric login methods for authentication in the UI extension.

FAQ

How can the issuer application provide card availability to Apple Wallet before the end user logs in?

The end user must log in to the issuer application at least once so that the extension can be updated with card status. The issuer application calls configure(ConfigParams.walletExtensionConfig()) to provide the list of cards to the D1 SDK.

If a login fails, where is the error shown?

We recommend showing login errors directly in the UI extension’s login screen. The UI extension should follow the same UX guidelines as the issuer application’s login.

What are the size and resolution requirements for card images?

The digital card image should follow Apple’s functional requirements:

• Provide images as PNG (recommended) or vector PDF.

  • Wallet extensions have stricter memory limits than main apps.
  • PDF files increase memory usage because the OS converts them to PNG.
• Use a resolution of 1536 × 969.
• Ensure the image size is less than 4 MB.
• Use squared (not rounded) corners.
• Exclude physical-card-only elements (for example, PAN, embossed characters, hologram, chip contacts).
• Use landscape orientation. If the physical card is portrait, reorient it to landscape.
• Optionally add the contactless indicator when NFC payments are supported.

Do extensions require new bundle identifiers?

Yes. The new bundle identifiers must be included in the associatedApplicationIdentifier of the payment network operator (PNO). iOS supports wildcard bundle identifiers.

Issuers must also update existing passes in Apple Wallet using PNO APIs. If the bundle ID is not included, cards added through the Apple Wallet extension cannot be accessed by the issuer application (for example, for digitization state checks).

What could be wrong if the issuer application icon does not appear in Apple Wallet?

Check the following:

• The issuer application is installed and has been opened at least once.
• The issuer application calls configure(ConfigParams.walletExtensionConfig()) to update the card list.
• The issuer application and both extensions use the same appGroupID in configure(ConfigParams.walletExtensionConfig()) and in Xcode capabilities.

Is in-app provisioning required for Apple Wallet extensions to work?

Yes. The issuer application must first implement in-app push provisioning to wallets before adding Apple Wallet extensions.