Class WalletExtension

java.lang.Object
com.codename1.payment.WalletExtension
public final class WalletExtension extends Object

Publishes card data to the Apple Wallet issuer-provisioning extension so users can add the issuer's cards to Apple Wallet from inside the Wallet app ("From apps on your iPhone"). iOS only; on other platforms isSupported() returns false and all methods are no-ops.

How it works

The Wallet extension runs in a separate process, launched by the Wallet app, usually while your app is not running. It cannot call into your Java code. Instead your app pre-publishes the list of available cards (and an auth token) with this class; the data is stored in the shared App Group container where the generated extension reads it. The final provisioning step - producing the encrypted pass payload - is performed by your issuer backend: the extension POSTs Apple's certificates/nonce plus the card identifier and auth token to the HTTPS endpoint configured in the ios.wallet.issuerEndpoint build hint, which must respond with JSON {"activationData", "encryptedPassData", "ephemeralPublicKey"} (base64).

Call [#setPassEntries(WalletPassEntry[])] whenever the user's card list changes (e.g. after login) and keep a fresh auth token published with setAuthToken(java.lang.String); call clear() on logout.

Enabling the extension (no native code needed)

Add these build hints to the iOS build:

  • ios.wallet.extension=true - generates the non-UI Wallet extension
  • ios.wallet.appGroup=group.com.mycompany.myapp - shared App Group id
  • ios.wallet.issuerEndpoint=https://... - issuer backend endpoint
  • ios.wallet.includeUI=true + ios.wallet.authEndpoint=https://... - optional in-Wallet login screen, only needed when you report setRequiresAuthentication(boolean) true instead of keeping a token
  • ios.wallet.*Inject hints - inject custom Objective-C at key points

Each extension needs its own App ID and provisioning profile carrying the restricted com.apple.developer.payment-pass-provisioning entitlement, which Apple grants per-app on request. For cloud builds either place the .mobileprovision files in src/main/resources and name them in the ios.wallet.nonuiProvisioningProfile / ios.wallet.uiProvisioningProfile hints, or host them at the URLs given in the ios.wallet.nonuiProvisioningURL / ios.wallet.uiProvisioningURL hints. The card network must also list the extension App IDs in the pass metadata (associatedApplicationIdentifiers) or Wallet never invokes the extension.

Bringing your own extension

If you already have Xcode extension targets (e.g. from an issuer SDK vendor or an existing native app), skip the ios.wallet.* hints and copy each extension into ios/app_extensions/<Name>/ in your project instead: its sources, Info.plist, <Name>.entitlements, an optional buildSettings.properties with Xcode build settings (set IPHONEOS_DEPLOYMENT_TARGET=14.0 for Wallet extensions) and the extension's .mobileprovision for cloud device builds.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    clear()
    Clears everything previously published: pass entries, remote pass entries, the auth token and the requires-authentication flag.
    static boolean
    isSupported()
    Returns true if the platform supports publishing Wallet extension data: iOS 14 or newer with the ios.wallet.extension build hint enabled.
    static void
    setAuthToken(String token)
    Publishes the auth token that the extension forwards to the issuer endpoint (JSON authToken field and Authorization: Bearer header) when the user adds a card.
    static void
    setPassEntries(WalletPassEntry[] entries)
    Publishes the cards that the Wallet extension offers for provisioning on the iPhone itself, replacing any previously published list.
    static void
    setRemotePassEntries(WalletPassEntry[] entries)
    Publishes the cards offered for provisioning on a paired Apple Watch, replacing any previously published list.
    static void
    setRequiresAuthentication(boolean requiresAuthentication)
    Sets whether Wallet should present the login UI extension before provisioning.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • isSupported

      public static boolean isSupported()
      Returns true if the platform supports publishing Wallet extension data: iOS 14 or newer with the ios.wallet.extension build hint enabled. Returns false on all other platforms and in the simulator.

    • setPassEntries

      public static void setPassEntries(WalletPassEntry[] entries)

      Publishes the cards that the Wallet extension offers for provisioning on the iPhone itself, replacing any previously published list. Cards already present in Wallet are filtered out automatically by the extension.

      Parameters
      • entries: the available cards; an empty array or null clears the list

    • setRemotePassEntries

      public static void setRemotePassEntries(WalletPassEntry[] entries)

      Publishes the cards offered for provisioning on a paired Apple Watch, replacing any previously published list. Typically the same list as [#setPassEntries(WalletPassEntry[])].

      Parameters
      • entries: the available cards; an empty array or null clears the list

    • setRequiresAuthentication

      public static void setRequiresAuthentication(boolean requiresAuthentication)
      Sets whether Wallet should present the login UI extension before provisioning. Keep this false and maintain a fresh token with setAuthToken(java.lang.String) to skip in-Wallet login entirely.

    • setAuthToken

      public static void setAuthToken(String token)

      Publishes the auth token that the extension forwards to the issuer endpoint (JSON authToken field and Authorization: Bearer header) when the user adds a card.

      Parameters
      • token: the token, or null to remove it

    • clear

      public static void clear()
      Clears everything previously published: pass entries, remote pass entries, the auth token and the requires-authentication flag. Call this when the user logs out.