Wallet for Windows Phone Store apps

  • Article

Wallet on Windows Phone allows users to store their reward cards, tickets, deals and payment cards in a central location. This ensures that users have their cards when and where they need them. Wallet ships on every Windows Phone. From an app developer perspective, you can think of Wallet as a lightweight platform that you can use to create and maintain a connection with your users and as a surface area on Windows Phone that is always available for your content. Using the functionality provided by the Windows Runtime APIs for Wallet, your can increase your app's reach by adding items with your unique branding to Wallet. You can also import Wallet items into Wallet.

The Wallet experience

When the user launches Wallet, they are shown a summary list of all items in their wallet. The following screen shot shows a typical summary list view. This is where users find summary info of their Wallet items. All items are organized into a single, flat list. A larger card is displayed at the top of the list. This card has been promoted to the top of the list because the user is near a location where the item can be used, or is viewing the Wallet at a time when this item is most relevant, or both. You can provide geolocation or time data with your item to help bubble it to the top of this summary view at the relevant time or location.

When creating Wallet items, you can define what information you want to display for the card in the summary view. Tapping on any card in the summary view takes you to the details view of the Wallet item.

The anatomy of a Wallet item

When the user selects your item from the summary list, the details of the item will be shown to them. Each Wallet item has two sides. These are the front side, or front-of-card view and the back side, or back-of-card view.

The front-of-card view

The front-of-card view of a Wallet item is highly customizable, allowing you to style and brand this view as you see fit. The following screen shot shows a typical Wallet item front-of-card view.

The user can navigate to the back-of-card view of an item by tapping on the "more information" icon displayed at the bottom of the preceding screen shot.

The back-of-card view

The back-of-card view is used to give the user more details about the particular item. You can also display calls to action which, when tapped, can perform actions such as opening your app. The following screen shot shows a typical back-of-card view for a Wallet item.

Integrating with Wallet

Windows Phone 8.1 introduces two ways in which you can integrate with Wallet. You can programmatically create and manage Wallet items from your app using the Windows Phone 8.1Wallet APIs or you can define items declaratively, package them in a special package and distribute them to users to install directly into Wallet.

Using the Wallet extensibility API

The Wallet extensibility API is found in the Windows.ApplicationModel.Wallet namespace. This is a new Windows Runtime API introduced in Windows Phone 8.1 to enable your app to interact with Wallet in the following ways.

  • Create and insert items. You can create Wallet items that represent a boarding pass, membership card, ticket, deal, payment instrument or a general card.
  • Update the items associated with your app.
  • Delete items associated with your app.
  • Add transactions to the items associated with your app.
  • Define relevant date and location information for a Wallet. Adding this information promotes the item in the main summary view in Wallet on the particular date, or at the particular location. A toast notification pop-up message will also be displayed. For example, a relevant date for a boarding pass is the date of the flight. Another example is the location of a cinema for a movie ticket. This enables items to show up in the summary list when they are most relevant.
  • Add verbs to an item that enable a user to perform actions when tapped.
  • Launch Wallet from your app to display one of your Wallet items.
  • Open your app by tapping on one of your items in Wallet.
  • Import an item using Wallet item package.

For more information on how to use this API in your app, see Quickstart: Using the Windows Phone 8.1 Wallet APIs.

Making and distributing a Wallet item using a Wallet item package.

A Wallet item package is a zip container, with the .mswallet file extension, containing images and metadata (XML) that fully describes a personalized Wallet item that can be added to Wallet, such as a boarding pass, membership card, ticket or deal. Instead of adding items using the Wallet APIs, you can define these packages and your users can import them into Wallet. The added benefit of this approach is that the user doesn't have to have a particular app installed in order to add Wallet items from you into their Wallet.

A Wallet item package can be ingested into Wallet in any of the following ways.

  • The user selects a .mswallet item from a website
  • The user selects a .mswallet item from an email
  • Whenever Wallet is opened by the user or the user taps refresh, the phone will attempt to update the contents of each card that has a WebServiceUrl and AuthenticationToken defined.
  • An app adds a Wallet item by importing a Wallet item package using the ImportItemAsync API.

For more information, see Quickstart: Creating and distributing wallet item packages (.mswallet files).

Quickstart: Using the Windows Phone 8.1 Wallet APIs

Quickstart: Creating and distributing wallet item packages (.mswallet files)

Windows.ApplicationModel.Wallet