Windows Dev Center

Wallet for Windows Phone 8

Windows Phone 8 introduces the Wallet, which allows users to do the following:

  • Collect coupons, credit cards, memberships, loyalty cards, and more in one place.

  • Manage the payment instruments that they use in the app and music store.

  • Link items in the Wallet to apps on their phone.

  • Make contactless transactions, using Near-Field Communication (NFC), in some markets.

As a developer, you can create apps that integrate with the Wallet. Using the functionality provided through the Wallet APIs, you can create, read, write, and delete Wallet items from your app. Through the Windows Phone 8 Wallet experience, you can keep items up-to-date by using agents, and interact with the user through status messages and custom fields. In addition, Wallet items enable users to deep link in to your app so that you can provide a more meaningful in-app experience.

By adding Wallet functionality to your app, you have the opportunity to increase your app’s reach. You can add items with your branded logo, making your brand visible from within the Wallet. Deep linking from the Wallet back to your app offers users an additional entry point to your app (your app will still appear in the all apps list), and gives you context about how they opened your app so that you can provide relevant information. Apps that handle club memberships, coupons or deals, and banking are all great Wallet integration candidates, but you can be creative and come up with unique scenarios for integrating your app into the Wallet. Integrating with the Wallet also promotes your app to users, because it will show up in the Wallet’s UX for adding Wallet items (your app will still be in the Store if users look for it there).

The Wallet API offers full programmatic access to the Wallet. It allows you to create, read, update, and delete Wallet items. Item access is controlled such that your app can only ever work with items in the Wallet that it created or that were linked to your app by the user. For certain item types, the user is prompted by the phone to accept the addition of your items to the Wallet, giving the user peace of mind. Your Wallet items can also be kept up to date using a Wallet agent that asks your app to update items whenever it is necessary. Each Wallet item type has a rich schema that also allows you to add custom fields. You can choose to fill in as many or as few of those fields as you’d like.

If your Wallet extensibility solution includes barcode images, use the following image sizes. If you don’t want to provide images for each resolution, provide a single image for the highest resolution, and it will scale as needed.

Phone resolution

Barcode image size

480 × 800

434 × 174

720 × 1280

651 × 261

768 × 1280

695 × 278

If your solution includes QR codes or other square images, provide a single image that is 278 × 278, and it will scale as needed.

The following table lists the capabilities that are required to use the Wallet API in Windows Phone 8. If these are not specified in the WMAppManifest.xml your app might not work correctly or it might fail the process of submission to the Store.


API that requires this capability


Required for all Wallet API, which is anything in Microsoft.Phone.Wallet or Microsoft.Phone.SecureElement.


Required for PaymentInstrument and OnlinePaymentInstrument.


Required for SecureElementSession, SecureElementChannel and SecureElementReader.

Important noteImportant Note:

To deploy or submit an app that uses ID_CAP_WALLET_SECUREELEMENT or ID_CAP_WALLET_PAYMENTINSTRUMENTS, you must request special permissions and have that permission applied to your developer account. For more info and for assistance, contact Dev Center support.

For more info about Windows Phone 8 capabilities, see App capabilities and hardware requirements for Windows Phone 8.

To increase the discoverability of your app that integrates with the Wallet, you can define your app as a Wallet extension. This makes your app appear in the other list of apps in the Wallet when the user taps add. The user can then pick your app from that list and the app will be downloaded and installed on the phone. This is another great way to increase the discoverability of your app.

To appear in the Wallet other list, register as one of the Wallet extensions. Extensions are specified in the WMAppManifest.xml file of your app project. The following is an example of a WMAppManifest.xml file that contains the Extension element to register the app as a Wallet extension.

<?xml version="1.0" encoding="utf-8"?>
<Deployment xmlns="" AppPlatformVersion="8.0">
  <DefaultLanguage xmlns="" code="en-US" />
  <App xmlns="" ProductID="{3860f72b-b8fc-4503-b922-c25f315da9c3}" Title="SamplePhoneApp" RuntimeType="Silverlight" 
       Version="" Genre="apps.normal" Author="PhoneApp2 author" Description="Sample description" Publisher="PhoneApp2" 
    <IconPath IsRelative="true" IsResource="false">Assets\ApplicationIcon.png</IconPath>
      <Capability Name="ID_CAP_NETWORKING" />
      <Capability Name="ID_CAP_MEDIALIB_AUDIO" />
      <Capability Name="ID_CAP_MEDIALIB_PLAYBACK" />
      <Capability Name="ID_CAP_SENSORS" />
      <Capability Name="ID_CAP_WEBBROWSERCOMPONENT" />
      <Capability Name="ID_CAP_WALLET" />
      <DefaultTask Name="_default" NavigationPage="MainPage.xaml" />
      <PrimaryToken TokenID="PhoneApp2Token" TaskName="_default">
          <SmallImageURI IsRelative="true" IsResource="false">Assets\Tiles\IconicTileSmall.png</SmallImageURI>
          <IconImageURI IsRelative="true" IsResource="false">Assets\Tiles\IconicTileMediumLarge.png</IconImageURI>
          <DeviceLockImageURI IsRelative="true" IsResource="false">
    <!--Register as a Wallet extension. The ConsumerID for Wallet extensions is always set to {5B04B775-356B-4AA0-AAF8-6491FFEA5683}, which is the id of the phone's Wallet app. -->
      <Extension ExtensionName="Wallet_app_membership" ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5683}" TaskID="_default"/>
      <ScreenResolution Name="ID_RESOLUTION_WVGA" />
      <ScreenResolution Name="ID_RESOLUTION_WXGA" />
      <ScreenResolution Name="ID_RESOLUTION_HD720P" />

In the preceding code, the extension is defined by adding an Extension element to the Extensions section in the WMAppManifest.xml file. If the Extensions element is missing, you can add it after the Tokens section. The attributes for the entry are defined as follows.

  • ExtensionName: Defines the type of extension you are registering. Valid values for this attribute when registering as a Wallet extension are:

    • Wallet_app_other – for non-specific Wallet items

    • Wallet_app_loyalty – for loyalty cards

    • Wallet_app_membership – for membership cards

    • Wallet_app_transit – for transit cards

    • Wallet_app_payment – for payment cards

    You only need to register once, even if your app is used for multiple Wallet item types. You can register as an extension for multiple Wallet item types if you want by adding multiple Extension elements to the Extensions section in WMAppManifest.xml. Currently, when the user taps other to bring up the Add to Wallet dialog box and look for Wallet extensions, all extensions are returned, regardless of what Wallet item type was defined when registering as an extension.

  • ConsumerID: This is a fixed value, set to the id of the Wallet app on the phone, which is {5B04B775-356B-4AA0-AAF8-6491FFEA5683}. This is shown in the preceding code.

  • TaskID: Set this to default.

Registering as a Wallet extension is voluntary, but it is a great discoverability opportunity for your app. If you don’t register as an extension, your app won’t show up in the Add to Wallet dialog box. However, users can still search the Windows Phone Store and download your app as usual.


Your app is not visible in the other list of apps in the Wallet until you have submitted it to the Store and it has been published. Your app is not visible in this list when testing with the Windows Phone 8 Emulator or a Windows Phone 8 device.

© 2015 Microsoft