Apple Wallet ID

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

Apple Wallet ID is available for:

• iOS 16.0 or later. Some credentials may require a newer iOS version.
• An Incode iOS SDK version that supports Apple Wallet identity verification.

How It Works

Apple Wallet appears as one option in the ID Capture module's document chooser. The integration is chooser-based:

1. Your app initializes the iOS SDK and starts a session.

2. The ID Capture module shows any configured physical-capture and file-upload choices immediately.

   At the same time, the SDK checks with PassKit whether Apple Wallet is available on the device. If it is, the chooser adds Apple Wallet as an option. If it isn't, the existing choices stay the same.

3. The user selects Apple Wallet.

4. The SDK requests a one-time challenge from Incode. The challenge lists the fields configured in Dashboard.

5. Apple shows the system authorization sheet. The user reviews the requested information and authorizes with Face ID or Touch ID.

6. PassKit returns an encrypted response. The SDK sends this response to Incode without inspecting it.

7. Incode decrypts and validates the response on the server. ID Capture completes, and onboarding continues.

The host app doesn't receive raw Wallet identity attributes through a client callback. Results stay part of the Incode session and its configured verification flow. The back end determines requested identity fields through the one-time challenge; the SDK doesn't choose them.

Prerequisites

Before integrating Apple Wallet, confirm all of the following:

Apple Credential Availability

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

Passport-derived Digital ID and national ID support require additional PassKit descriptors and corresponding Incode back-end validation.

Set Up Apple Wallet ID

Complete the following steps in order.

Configure Incode

Apple Wallet configuration is server-driven. 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.

The Flow or Workflow response supplies enablement but intentionally does not include requested fields. The one-time back-end challenge is the authoritative source for requested fields. The public addIdScan() API doesn't expose Apple Wallet enablement or requested-field settings. This avoids a second client-side configuration that could conflict with the back-end challenge.

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. Entitlement approval is granted per 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>portrait</string>
        <string>address</string>
        <string>issuing-authority</string>
        <string>document-expiration-date</string>
        <string>document-number</string>
        <string>driving-privileges</string>
        <string>age</string>
        <string>date-of-birth</string>
        <string>document-issue-date</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. Calling the Wallet identity API without this key causes iOS to terminate the app.

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

Merchant Configuration

Set the merchant ID on the shared manager 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.

Enable Apple Wallet in ID Capture

Configure Apple Wallet in Dashboard for the specific Flow or Workflow where it should be offered.

1. Open the ID Capture module in the Flow or Workflow.
2. Keep the ID document chooser enabled.
3. Turn on Enable Digital ID upload.
4. Enable the APPLE_WALLET method.
5. Select the identity fields required by the use case.

The SDK does not expose a corresponding code-defined setting. When the chooser opens, it performs a general driver's-license availability check. Physical-capture and file-upload choices remain usable while the check runs. Apple Wallet appears only when PassKit confirms that the device has a requestable mDL. The availability check does not pre-validate every Dashboard-configured field, because those fields arrive later with the one-time challenge.

Requested Fields

Every requested field must satisfy three conditions:

1. The field is enabled in the 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.

Dashboard exposes the following choices. Challenge values are shown for troubleshooting only; integrators do not pass them through a public SDK API.

Both issuing-country and issuing-authority requests map to PassKit's .issuingAuthority element, and all four resident-address choices map to PassKit's single .address element. Unknown, unsupported, or OS-unavailable fields are logged and skipped. If no supported elements remain, the SDK shows the generic Wallet retry screen after the user selects Apple Wallet.

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. A threshold request can fall back to the age element when the issuer does not provide that threshold. Confirm the resulting data and retention behavior for your environment before relying on a threshold-only use case. The SDK marks 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.

Sequence Diagram

The Wallet challenge is fetched after the user selects Apple Wallet. The SDK drives the PassKit authorization sheet, and the returned encrypted response is validated server-side.

sequenceDiagram
    autonumber
    participant App as Client app
    participant SDK as Incode SDK
    participant BE as Incode back-end
    participant Wallet as Apple Wallet (PassKit)

    App->>SDK: Start Flow or Workflow
    Note over App,SDK: SDK initialization and onboarding start
    SDK->>Wallet: Check driver's-license availability
    Wallet-->>SDK: Available / not available
    SDK-->>App: Render document chooser
    Note over App,SDK: Apple Wallet appears only when PassKit confirms availability
    App->>SDK: User selects Apple Wallet
    SDK->>BE: Request one-time challenge
    BE-->>SDK: nonce, merchantId, requestedFields
    SDK->>Wallet: Present authorization sheet (requested elements)
    Wallet->>Wallet: User authorizes with Face ID / Touch ID
    Wallet-->>SDK: Encrypted identity response (opaque)
    SDK->>BE: Send encrypted response for validation
    BE-->>SDK: Return verification result
    SDK-->>App: Continue onboarding

On cancellation, the user returns to the chooser. On failure, the SDK shows its generic Wallet retry screen. On success, the encrypted response is validated and onboarding continues.

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.

When contacting Support, include:

• SDK version
• App bundle ID
• iOS/device version
• Incode session identifier
• Approximate timestamp
• Whether the failure occurred before or after Apple's authorization sheet

Do not include raw identity data.

External References

• Get started with Verify with Wallet
• Configure your environment for the Verify with Wallet API
• PKIdentityAuthorizationController