Quickstart: Creating and distributing Wallet item packages (.mswallet files)
This topic describes how to create Wallet item packages that can be distributed to users.
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, deal, payment instrument or a general card. 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.
Prerequisites
How a Wallet item package is imported into Wallet.
There are multiple ways a package can be imported into Wallet. The following table describes each scenario.
| Scenario | Description |
|---|---|
| User selects a .mswallet item from a website | The user will be prompted to add the item to Wallet. |
| User selects a .mswallet item from an email | The user will be prompted to add the item to Wallet |
| The phone fetches an updated .mswallet item from a 3rd party service | The item will be downloaded from the 3rd party service without prompting the user. This happens when the user opens Wallet or when they tap refresh. The system will try to download an update for each package that has a WebServiceUrl and AuthenticationToken defined. |
| An app adds Wallet item package using the Wallet APIs. | The app uses the ImportItemAsync method to process a Wallet item package. The package must be associated with the app. The API will prompt the user whether they want to add & review if it’s a new item as appropriate. This scenario is demonstrated in the Wallet Quickstart sample. For more information about the Wallet APIs, see Quickstart: Using the Windows Phone 8.1 Wallet APIs. |
Files in a Wallet item package
Wallet item packages are stored as a zipped package with the .mswallet file extension (ex. "BlueYonder.mswallet") and have the mime type application/vnd.ms.wallet. The following files must be placed at the root level of the package.
Note The files must be named as they are shown in the table.
| File Name | Required | Description |
|---|---|---|
| WalletItem.xml | Required | An XML file that describes the item. |
| Logo99x99.png | Required | Small logo of the Wallet item. |
| Logo159x159.png | Required | Medium logo of the Wallet item. |
| Logo336x336.png | Required | Large logo of the Wallet item. |
| Logo.png | Optional | The logo of the issuer of this item. |
| HeaderBackground.png | Optional | The image to display behind the header of the item. |
| BodyBackground.png | Optional | The image to display behind the body of the item. |
| PromotionalImage.png | Optional | The image to display on the back of the item. |
| Locale folders | Optional | Each folder can contain localized string and image assets. For more information, see Multi-language support |
When creating a Wallet item package, create the files described in the preceding table and add them to a Zip file and make sure the file is given the extension .mswallet. To test your package, send it to yourself as an email and when the email arrives on your phone, click on the attachment to import the package into Wallet.
WalletItem.xml
The definition of the Wallet item is contained in a file called WalletItem.xml in your package. This is an XML file that describes the type of item, the colors you want to use and various other properties. This XML file must adhere to the WalletItem.xsd schema. The schema can be downloaded from here. The following table describes the elements that can be defined in a WalletItem.xml file.
| Element Name | Required | Description |
|---|---|---|
| Version | Required | Version number of the Wallet item package. Only a value of 1 is supported. |
| Id | Required | Identifier of the Wallet item. This value is only required if you are enabling updates of the item through a web service and you have therefore supplied a value for WebServiceUrl and AuthenticationToken. |
| WebServiceUrl | Required for updates. | URL of the 3rd party service from which updates will be pulled by the phone. Must be https:// unless the device is developer unlocked. |
| AuthenticationToken | Required for updates. | Used for authenticating the item with the 3rd party service. |
| ProductId | Optional | Id of the application associated with the item. |
| Kind | Required | Identifies the type of the item. The following list defines all valid values for this element. Deal General PaymentInstrument Ticket BoardingPass MembershipCard |
| DisplayName | Required | |
| IssuerDisplayName | Required | |
| HeaderColor | Required | Specify color in #rrggbb format. |
| BodyColor | Required | Specify color in #rrggbb format. |
| HeaderFontColor | Optional | Specify color in #rrggbb format. |
| BodyFontColor | Optional | Specify color in #rrggbb format. |
| LogoText | Optional | This is displayed at the top of the item's details view beside the logo image, if one was provided. |
| ExpirationDate | Optional | W3C date as a string. |
| Barcode\Symbology | Optional | Specifies the format of the bar code image to generate. The following list defines all valid values for this element. UPCA UPCE EAN13 EAN8 ITF CODE39 CODE128 QR PDF417 AZTEC |
| Barcode\Value | Optional | The data to encode using the specified Barcode\Symbology. |
| DisplayMessage | Optional | The message that will be shown in the item's details view. |
| IsDisplayMessageLaunchable | Optional | Determines whether tapping on the DisplayMessage will launch the app associated with this item. This is only applicable if the ProductId element has been set. |
| DisplayProperties\Header\* | Optional | Possible parent elements of one or more Property elements. Each element can only appear once. The number of child Property elements that are allowed for Header, Primary, Secondary, Center and Footer is determines by the WalletItem schema. |
| DisplayProperties\Primary\* | Optional | Possible parent elements of one or more Property elements. Each element can only appear once. The number of child Property elements that are allowed for Header, Primary, Secondary, Center and Footer is determines by the WalletItem schema. |
| DisplayProperties\Secondary\* | Optional | Possible parent elements of one or more Property elements. Each element can only appear once. The number of child Property elements that are allowed for Header, Primary, Secondary, Center and Footer is determines by the WalletItem schema. |
| DisplayProperties\Center\* | Optional | Possible parent elements of one or more Property elements. Each element can only appear once. The number of child Property elements that are allowed for Header, Primary, Secondary, Center and Footer is determines by the WalletItem schema. |
| DisplayProperties\Footer\* | Optional | Possible parent elements of one or more Property elements. Each element can only appear once. The number of child Property elements that are allowed for Header, Primary, Secondary, Center and Footer is determines by the WalletItem schema. |
| DisplayProperties\Property\Key | Optional | The property key. |
| DisplayProperties\Property\Name | Optional | The display name, or label, of the property. |
| DisplayProperties\Property\Value | Optional | The value of the property. |
| DisplayProperties\Property\NumberFormat | Optional | If the value of the property is a number, you can define the number format to use. The following list defines all valid values for this element. Decimal Percent Exponential Currency |
| DisplayProperties\Property\CurrencyCode | Optional | ISO 4217 currency code. Element cannot be used with NumberFormat or DateTimeFormat. |
| DisplayProperties\Property\DateTimeFormat | Optional | Format of the property value as a DateTime. The following list defines all valid values for this element. FullDateTime LongDate LongTime MonthDay ShortDateTime ShortDate ShortTime YearMonth . |
| DisplayProperties\Property\AutoDetectLinks | Optional | Makes any property value that looks like a phone number, address or URL clickable. |
| DisplayProperties\Property\SummaryViewPosition | Optional | If this element exists, it indicates the property to display in the list view and the order that property appears in the list view. The value is an integer and can be either 0 or 1 which determines whether the property is displayed in the first or second position. If set, the value of the property is displayed in the list view without the label. If two properties have this element set, then the values are displayed in “{0}, {1}” format. |
| IsMoreTransactionHistoryLaunchable | Optional | Determines whether an option to see more transactions is available in the item transactions view. Clicking this option launches the app with an applicable activation event. |
| TransactionHistory\TransactionItem\Description | Optional | A description of the transaction. |
| TransactionHistory\TransactionItem\DisplayAmount | Optional | A string representing the amount of the transaction, for example, "$123.45" |
| TransactionHistory\TransactionItem\Id | Optional | A string identifier of the transaction item. A linked app can refer to this transaction using this ID. |
| TransactionHistory\TransactionItem\DisplayLocation | Optional | A string representation of where the transaction took place, for example, "Contoso on 3rd Ave." |
| TransactionHistory\TransactionItem\TransactionDate | Optional | The XML datetime of the transaction. |
| TransactionHistory\TransactionItem\IgnoreTimeOfDay | Optional | Whether to display the time of the transaction, or just the date. |
| TransactionHistory\TransactionItem\IsLaunchable | Optional | Whether the user can tap on the transaction item to launch a linked app and get more information. When the linked app is launched in this manner, the will contain the value of the ActionKind property on the WalletActionActivatedEventArgs will be set to Transaction. |
RelevantLocations\Location\Latitude RelevantLocations\Location\Longitude RelevantLocations\Location\Altitude RelevantLocations\Location\DisplayMessage |
Optional* | If a Location element is specified, then Latitude & Longitude elements must exist. Other elements are optional. Zero or more locations where the item is relevant, for example, stores where a loyalty card can be used or the location of a concert where a ticket can be used. All values are doubles, except for Description which is a string. |
RelevantDate\Date RelevantDate\Description |
Optional* | If the RelevantDate element exists then Date must be provided. Description is optional. Specifies a single date when then item is relevant, for example the date of the concert. |
Example WalletItem.xml file
The following XML file shows an example WalletItem.xml file that defines a boarding pass for a fictitious airline called BlueYonder.
<?xml version="1.0" encoding="utf-8"?>
<WalletItem>
<Version>1</Version>
<Id>5609</Id>
<WebServiceUrl/>
<AuthenticationToken/>
<ProductId />
<Kind>BoardingPass</Kind>
<DisplayName>Blue Yonder Airlines</DisplayName>
<IssuerDisplayName>Blue Yonder Airlines</IssuerDisplayName>
<Barcode>
<Symbology>QR</Symbology>
<Value>e.g. 012345678</Value>
</Barcode>
<DisplayMessage />
<HeaderColor>#d4edff</HeaderColor>
<BodyColor>#006fbf</BodyColor>
<HeaderFontColor>#00094d</HeaderFontColor>
<BodyFontColor>#fbfcfe</BodyFontColor>
<LogoText />
<DisplayProperties>
<Header>
<Property>
<Key>Hd1</Key>
<Name>Gate</Name>
<Value>A2</Value>
</Property>
</Header>
<Primary>
<Property>
<Key>Pr1</Key>
<Name>New York City</Name>
<Value>NYC</Value>
</Property>
<Property>
<Key>Pr2</Key>
<Name>Seattle</Name>
<Value>SEA</Value>
</Property>
</Primary>
<Secondary>
<Property>
<Key>Bp1</Key>
<Name>BOARDS</Name>
<Value>7:50A</Value>
</Property>
<Property>
<Key>Bp2</Key>
<Name>DEPARTS</Name>
<Value>10:20A</Value>
</Property>
<Property>
<Key>Bp3</Key>
<Name>Flight</Name>
<Value>1503</Value>
</Property>
<Property>
<Key>Bp4</Key>
<Name>ZONE</Name>
<Value>4</Value>
</Property>
</Secondary>
<Footer>
<Property>
<Key>Ft1</Key>
<Name>Passenger</Name>
<Value>Darrin DeYoung</Value>
</Property>
<Property>
<Key>Ft2</Key>
<Name>Seat</Name>
<Value>20C</Value>
</Property>
</Footer>
</DisplayProperties>
</WalletItem>
Tip To set the Name or Value fields of a property to blank, use a non-breaking space. This is illustrated in the following XML examples.
Setting the Name field of a property to be blank
<!-- Setting the Name to blank -->
<Property>
<Key>17</Key>
<Name> </Name>
<Value>MyValue</Value>
</Property>
Setting the Value field of a property to be blank
<!-- Setting the Value to blank -->
<Property>
<Key>17</Key>
<Name>My name or label</Name>
<Value> </Value>
</Property>
Multi-language support
Wallet item packages support multiple languages so that the user will be a able to view your card in the language they've chosen for their phone. Localized content is located within locale-specific subdirectories of the package. Each locale folder can contain a single strings.txt file, which follows the text resource format. For more information, see Resources in Text File Format. Let's consider the following property element from BlueYonder boarding pass that was described in the preceding section, Example WalletItem.xml file.
<Property>
<Key>Bp3</Key>
<Name>Flight</Name>
<Value>1503</Value>
</Property>
When a user has their phone set to German and views this card, it would be a better experience if the labels and values for all properties on the card were displayed in German. For example, we'd like to display the Flight label as Flug in this example. To enable this scenario in the Wallet item package, perform the following steps.
Create a folder in the package with the name de-DE. This is the BCP-47 directory name for German.
In the folder you just created, add a text file called strings.txt. This is the text file that will contain the translations for this language.
Open strings.txt in your favorite text editor and add the following lines.
; Label for the flight property Flight=FlugThe first line in the preceding example is an optional comment that you can add to clearly identify the intent of the translation.
Save strings.txt.
Note If you want to save and use German characters, save your text file using Unicode encoding rather than using a specific ANSI code page.
Repeat steps 1 to 4 for every language you want to support.
Locale folders can also contain locale-specific versions of any of the images for the item. The images must have the same name as the images in the root folder, for example \de-DE\Logo99x99.png. If a locale-specific image asset is not found for the current locale, the image in the root folder will be used instead.
Localized content is contained under separate subdirectories of the root of the Wallet item package, in BCP-47 directory names. The closest match to the user's current language settings are used. For example, if only es-ES is supplied in the package and the current locale is es-MX then es-ES will be used.
Associating a Wallet item package with your app
In the BlueYonder boarding pass that was described in the preceding section, Example WalletItem.xml file, the ProductId element was empty. This means that when the card is imported into Wallet it will not be associated with an app. This is advantageous, on one hand, because it means you don't have to have an app on the user's phone in order to promote your brand in Wallet. On the other hand, if the user has your app installed, the app will not be able to manage this boarding pass because it is not associated with your app. To link the card to your app, the ProductId element has to be set with the Id of your app. You can find that value in the Package.appxmanifest file of your app project. The following shows what this line looks like in a Package.appxmanifest file.
<mp:PhoneIdentity PhoneProductId="7cc7ccfd-973c-49b4-b7ca-1b05cd725705" PhonePublisherId="00000000-0000-0000-0000-000000000000" />
Updating a Wallet item package
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. This is done by making a GET request to the RESTful web service service identified by the WebServiceUrl of the Wallet item. The following is an example of a request the phone makes to get an update for an item.
https://WebServiceUrl/1/walletitems/id
WebServiceUrl is the value of the WebServiceUrl property on the Wallet item and Id is the Id of the item to be updated. The AuthenticationToken that was provided in the WalletItem.xml file for this item will be automatically added as a header in the GET request. The web service should verify that this header value is valid when handling each request from Wallet.
If the above request is successful, the updated Wallet item package will be downloaded by the phone and the Wallet item will be updated. The following table lists the HTTP responses that the web service should provide.
| HTTP response code | Description |
| 200 | Success. The response payload contains the updated data for the specified item. |
| 401 | Request was not authorized. For example, an invalid AuthenticationToken was supplied in the header of the GET request or the Id of the item is invalid. |
| 304 | If the specified item has been updated previously by Wallet, the GET request will contain an If-Modified-Since header. If the web service determines that the item has not been modified since the value specified in this header, it should send a 304 response code. |
Important Wallet stops making any further requests for updates from the web service if it receives 100 service failure responses, HTTP codes of 300 or greater, and if it has received service failures for 30 consecutive days from this web service At that point, you will not be able to deliver new updates for Wallet items that were affected and must instead supply new Wallet item packages with new Ids.
Error codes when manually importing a package
If an error occurs when a user tries to import a .mswallet package manually, the UI will display an error message. The following table lists the possible HRESULT error codes that will be displayed to the user.
| HRESULT error code | Description |
| 0x803A0050 | The Version element in WalletItem.xml is missing or its value is not 1. |
| 0x803A0051 | The ProductId element in WalletItem.xml has an invalid value. Specify a GUID enclosed in curly braces {}. |
| 0x803A0052 | The Id element is missing. It must be supplied when a value for WebServiceUrl has been specified. If no value for WebServiceUrl exists, you can omit a value for Id because one will be auto-generated internally. The app can find all items using GetItemsAsync. |
| 0x803A0053 | The Kind element in WalletItem.xml has an invalid value. |
| 0x803A0054 | A Location element in WalletItem.xml has missing or invalid child elements. Verify that the Latitude and Longitude child elements exist and are valid. |
| 0x803A0055 | Verify that the values for all Color elements such as HeaderColor, BodyColor, HeaderFontColor, BodyFontColor. The values should be specified in #rrggbb format. |
| 0x803A0056 | The ExpirationDate element in WalletItem.xml contains an invalid value. |
| 0x803A0057 | The value of the WebServiceUrl element in WalletItem.xml is invalid. It must start with https:// unless the device is developer-unlocked, in which case it can alternatively begin with http://. |
| 0x803A0058 | WalletItem.xml must contain a value for AuthenticationToken, if it contains a value for the WebServiceUrl element. |
| 0x803A0060 | The DisplayName element is missing from WalletItem.xml. |
| 0x803A0061 | The IssuerDisplayName element is missing from WalletItem.xml. |
| 0x803A0062 | The Date or Description child elements are missing from a TransationItem element in WalletItem.xml or the value of a child element of TransactionItem is invalid. |
| 0x803A0063 | A child element of the Property element in WalletItem.xml contains an invalid value. |
| 0x803A0064 | The Symbology element in WalletItem.xml contains an invalid value. |
| 0x803A0065 | The Wallet item package is missing one or more required images - Logo99x99.png, Logo159x159.png or Logo336x336.png. |
| 0x803A0066 | A strings.txt file from a locale folder in the Wallet item package could not be parsed. |
| 0x803A0067 | A Relevant date element is missing a Date child element or a child element contains an invalid value. |
Summary and next steps
To see Wallet item packages in action, you download the following packages and email them to the account associated with your phone. You an then tap on the attachment in the email and import that package into Wallet.
- Blue Yonder example Wallet item package.
- Adventure Works example Wallet item package.
- Tailspin Toys example Wallet item package.
- Northwind Traders example Wallet item package.
- Coho Winery example Wallet item package.