Apple Wallet mDL - Integration Guide

Apple Wallet verification lets a user share approved identity attributes from a supported identity credential in Apple Wallet instead of photographing a physical document. The SDK presents Apple's system authorization sheet, sends the encrypted Wallet response to Incode for validation, and then continues the onboarding flow.

Important: Incode must enable Apple Wallet for your account and provide an SDK build that exposes addIdScan(appleWalletRequestedFields:). Contact your Incode representative before starting the integration.

Requirements

Before integrating Apple Wallet, confirm all of the following:

The IncdOnboarding SDK generally supports iOS 13.0+, but Apple Wallet identity verification has a higher minimum. The current SDK implementation uses PassKit APIs available from iOS 16.0 and supports compatible identity credentials on iPhone.

Apple credential availability

Apple controls the minimum device and OS for each credential. These requirements can change, so verify them on Apple's Verify with Wallet page before planning a rollout.

Prepare the app

1. Ask Incode Support to enable Apple Wallet for the correct account and environment. Obtain the merchant ID and an SDK build that contains the required API.
2. Complete Apple's Verify with Wallet entitlement process for the app's bundle ID. Entitlement approval is granted per bundle ID.
3. Add the identity-presentment capabilities to the App ID, associate the approved merchant ID, and regenerate the provisioning profile.
4. Add the entitlements and NSIdentityUsageDescription shown in Configure the host app.
5. Configure the same merchant ID on IncdOnboardingManager.shared before starting onboarding.
6. Enable Apple Wallet in the ID Capture configuration and request only fields approved by Apple and enabled by Incode.
7. Install the correctly signed app on an eligible iPhone containing a compatible identity credential, start onboarding, and choose Apple Wallet from the document chooser.
8. Approve the system sheet with Face ID or Touch ID. On success, the SDK submits the encrypted response and continues the configured onboarding flow.

Integration overview

The current integration is chooser-based:

1. Your app initializes IncdOnboarding and starts a session.
2. The ID Capture module displays the document chooser.
3. The user selects Apple Wallet.
4. The SDK requests a one-time challenge from Incode.
5. The SDK builds a PKIdentityRequest with the challenge, merchant ID, and configured identity elements.
6. Apple displays the system authorization sheet. The user reviews the requested information and authorizes with Face ID or Touch ID.
7. PassKit returns an HPKE-encrypted CBOR payload. The SDK treats it as opaque data and sends it to Incode.
8. Incode decrypts and validates the response on the server. The ID Capture module completes and the onboarding flow continues.

The host app does not receive raw Wallet identity attributes through a dedicated client callback. Results remain part of the Incode session and its configured verification flow.

The SDK marks the requested elements with Apple's mayStore intent. Make sure the fields you request and the retention described in your privacy policy match your approved use case.

Configure Incode

Ask Incode Support to configure the following for each environment:

• Enable Digital IDs and the Apple Wallet method for ID Capture.
• Enable the identity fields required by the use case.
• Configure the merchant ID and server-side identity certificate used to validate the encrypted response.
• Confirm that the merchant ID belongs to the same environment used by the SDK session.

Do not copy a merchant ID from a sample or another environment. A mismatch between the app, provisioning profile, and Incode server configuration prevents the Wallet response from being validated.

For Dashboard-defined flows, Incode supplies the enabled Apple Wallet method and requested fields through the ID Capture configuration. For code-defined flows, also pass the requested fields to addIdScan(appleWalletRequestedFields:) as shown below.

Configure the host app

Apple Developer account

Follow Apple's environment configuration process:

1. Request access to Verify with Wallet for your exact bundle ID.
2. Create or select the merchant ID coordinated with Incode.
3. Create the required Identity Access Certificate in coordination with Incode's server configuration.
4. Add In App Identity Presentment to the App ID.
5. Add In App Identity Presentment Merchant IDs and select the merchant ID.
6. Generate and install a new provisioning profile.

Entitlements

The app target must contain both identity-presentment entitlements. Include only document types and elements Apple approved for the app. This example shows a typical US mDL subset; replace the merchant placeholder with the value supplied for your environment.

<key>com.apple.developer.in-app-identity-presentment</key>
<dict>
    <key>document-types</key>
    <array>
        <string>us-drivers-license</string>
    </array>
    <key>elements</key>
    <array>
        <string>given-name</string>
        <string>family-name</string>
        <string>date-of-birth</string>
        <string>portrait</string>
        <string>document-number</string>
        <string>document-expiration-date</string>
        <string>issuing-authority</string>
    </array>
</dict>
<key>com.apple.developer.in-app-identity-presentment.merchant-identifiers</key>
<array>
    <string>merchant.your-company.identity</string>
</array>

The Apple Pay entitlement com.apple.developer.in-app-payments does not replace the identity-presentment merchant entitlement.

Privacy usage description

Add a user-facing explanation to the host app's Info.plist:

<key>NSIdentityUsageDescription</key>
<string>We use information from your ID in Apple Wallet to verify your identity.</string>

Use wording that accurately describes your app's purpose and data handling. Calling the Wallet identity API without this key causes iOS to terminate the app.

Merchant configuration

Set the merchant ID before starting the onboarding session:

IncdOnboardingManager.shared.appleWalletMerchantID =
    "merchant.your-company.identity"

The value must exactly match an entry in com.apple.developer.in-app-identity-presentment.merchant-identifiers and the merchant configured by Incode for the active environment.

Add Apple Wallet to ID Capture

For a code-defined flow, pass a non-empty list of requested fields and keep the ID type chooser enabled:

let flowConfiguration = IncdOnboardingFlowConfiguration()

flowConfiguration.addIdScan(
    scanStep: .both,
    showIdTypeChooser: true,
    appleWalletRequestedFields: [
        "given_name",
        "family_name",
        "birth_date",
        "document_number",
        "expiry_date",
        "portrait"
    ]
)

appleWalletRequestedFields has the following configuration behavior:

• nil disables Apple Wallet.
• A non-empty array enables Apple Wallet in the document chooser on iOS 16.0+.
• An empty array is an invalid configuration. Debug builds assert; optimized builds treat it as disabled.
• showIdTypeChooser: false hides the chooser and therefore prevents the current Apple Wallet flow from being initiated.

Requested fields

Every requested field must satisfy three conditions:

1. The field is enabled in the Incode ID Capture configuration.
2. The SDK maps it to an Apple PKIdentityElement.
3. The host app's Apple entitlement and provisioning profile authorize the corresponding element.

The SDK maps these field names. The availability column also identifies fields whose entitlement and end-to-end backend validation are still being finalized:

The SDK ignores unknown fields, fields unavailable on the current OS, and fields excluded from the SDK build. It logs the ignored field name and continues if at least one supported element remains. If no supported elements remain, the SDK shows the generic Wallet failure screen.

Current limitation: issuing_country does not currently have a requester mapping and is ignored. The final mapping and entitlement matrix for this and other extended fields is Coming Soon. Contact Incode Support before requesting a field not listed above.

The client uses Apple's privacy-preserving threshold elements for age_over_18 and age_over_21, but their final end-to-end validation is still in progress. Once Incode confirms them for your environment, prefer a threshold over age_in_years when the exact age is unnecessary.

Cancellation and errors

The current integration does not expose a Wallet-specific public error callback. Errors remain inside the chooser experience so the user can retry or select document capture instead.

PassKit diagnostic errors may include cancelled, invalidElement, invalidNonce, notSupported, networkUnavailable, noElementsRequested, requestAlreadyInProgress, and unknown. The current SDK handles cancelled by returning to the chooser; the other categories use the generic retry experience and are not returned as a public IncdError.

When contacting Support, include the SDK version, app bundle ID, iOS/device version, Incode session identifier, approximate timestamp, and whether the failure occurred before or after Apple's authorization sheet. Do not include raw identity data.

Related documentation

• IncdOnboarding SDK Usage
• SDK Installation and Setup
• Apple: Get started with Verify with Wallet
• Apple: Configure the Verify with Wallet environment
• Apple: PKIdentityAuthorizationController

License

Copyright 2026 Incode Technologies. All rights reserved.