1. Oliver Scheer
Senior Technical Evangelist
Microsoft Deutschland
http://the-oliver.com
Wallet Support and
In App Purchasing in
Windows Phone 8

2. Topics
• Wallet Overview
• Applications and wallet storage
• Wallet capabilities
• Creating and using a membership card
• Creating the card
• The Wallet Background Agent
• Creating and using a payment instrument card
• In App Purchases
• Adding products to your application
• Durable and Consumable items
• The purchase lifecycle
• The Application Programmer Interface
• Finding products
• Purchasing products
• Using product receipts

3. Wallet Overview
3

4. Windows Phone Wallet
• The Wallet is implemented as part of the Windows Phone
operating system
• The Wallet acts as a container for applications that can
store membership information and transaction data for
paid services
• The wallet provides an additional launching point for an
application
• The launch can be via a deep link to a page describing a
particular offer or service
3/19/2014‹#›

5. Wallet Storage
• Wallet information is held on a per-application basis
• An application can only interact with its own wallet
storage
• Each application will store information relating to the
services provided via that application
• Special offers
• Transactions
• Membership information
• Custom fields for that particular application
3/19/2014‹#›

6. Opening the Wallet
• The Wallet is supplied as part of the Windows Phone
• Users can store details of membership cards in the wallet
• These are linked to “wallet aware” applications on the phone
• The membership cards can be credit or debit cards, or any form
of membership tracking that you wish to add to your
application
• This includes transaction support and also allows you to alert
the user to any special offers or promotions associated with a
card

7. Storing data in the Wallet
• Users can store details of their cards inside the wallet
• They can add as many sets of card details as they like and the
wallet will store the details securely
• Each card is associated with an application that manages
transactions on that card
• They can PIN protect access to the wallet
• The wallet PIN can also be used to control access to Windows
Phone Store purchases

8. Navigating the Phone Wallet
• When the user opens the wallet they are shown a list of
all the cards that have been placed in there
• Each of the cards is bound to the application behind it
• When the card is opened the user has the option to start
the application behind that card
• This provides another way in which your application can
get started
• Uses can open their wallet, find your membership card
and run your application from there
3/19/2014‹#›

9. Using a Card
• When a user opens a card they can view the data for the card and
see their account information
• This is displayed by the Wallet
• They can also open the application from the Wallet entry
• A player could enter your multiplayer game from their wallet,
which would be the place you would store their user credentials
• The wallet also displays app supplied fields, for example balance
information
• This is text provided by the application behind the wallet
• It can also display transaction information for cards which are
payment instruments
3/19/20149

10. Adding a New Card
• The user can add a new card by tapping the + in the
application bar
• They can also search for existing cards in the wallet
• Each card is identified by the first six digits of the card
number
• Once you have created a card you can then search for
applications that can perform transactions on that card
• If an application is found the card is then bound to that
application
3/19/201410

11. Adding a New Card via an Application
• Cards are only useful once they have been bound to
applications
• Card providers can create applications that are bound to
cards in the wallet
• The Wallet program provides a menu of applications from
“well known” card providers
• A user can create a card from one of these applications
• Your applications can also create cards for storage in the
wallet
3/19/201411

12. Adding Cards from within Applications
• Cards are linked with the applications that use them
• The app code must create and populate a
WalletTransactionItem instance and pass that to the
AddWalletItemTask which handles the storage in the
Wallet
• A WalletTransactionItem object contains a number
of standard fields
• Applications can add their own custom fields for their
own use
• Only the application that is bound to a card can access
the information in the card
3/19/201412

13. Adding Cards from within Applications
• It is not possible for a card to be added to a wallet
without the user approving the action
• This prevents applications from “spamming” the wallet
with large numbers of cards
• The wallet also provides a means by which a user can
delete a card that they no longer use
3/19/201413

14. Wallet Enabled Applications
• A wallet application does not have to just manipulate money
• It could be any kind of club membership
• The wallet could contain membership details and any custom data about the club
• Each wallet entry can also store customised data for that application
• Achievements in a game, permission levels, responsibilities, etc
• Once an application is registered with the wallet it will appear alongside all the other
applications in the wallet
3/19/201414

15. Creating and using
a membership card
15

16. Wallet Applications and Capabilities
• If an application just wishes to use the Wallet to
store membership details and transaction logs it
just needs to enable the ID_CAP_WALLET
capability
• Any application can do this
• To use the payment instruments and store secure
elements in published applications you will have to
have those permissions added to your account
• Contact the Dev Center Support team to do this
3/19/201416

17. Creating a Wallet entry for an application
3/19/201417
WalletTransactionItem membershipItem;
membershipItem = new WalletTransactionItem("Membership");
membershipItem.IssuerName = issuer.IssuerName;
membershipItem.DisplayName = issuer.IssuerName + " Membership Card";
membershipItem.IssuerPhone.Business = issuer.IssuerPhone;
membershipItem.CustomerName = details.CustomerName;
membershipItem.AccountNumber = details.MembershipNumber;
membershipItem.BillingPhone = details.PhoneNumber;
membershipItem.IssuerWebsite = new Uri(issuer.IssuerWebSite);
membershipItem.DisplayAvailableBalance = "1000 points";
membershipItem.Logo336x336 = new BitmapImage(new Uri("/images/BrSml.png", …));
membershipItem.Logo159x159 = new BitmapImage(new Uri("/images/BrMed.png", …));
membershipItem.Logo336x336 = new BitmapImage(new Uri("/images/BrLge.png", …));
AddWalletItemTask addWalletItemTask = new AddWalletItemTask();
addWalletItemTask.Item = membershipItem;
addWalletItemTask.Show();

18. Demo
Demo 1: Creating a Club

19. Simple Wallet Use
• If you just want to store and manage membership information for your application the
wallet is a good way to do this
• Users can find and run your application from the Wallet
• The application can update the wallet membership properties to display information about
the status of the user
• This can be done simply by updating the text properties of the wallet information
• This will then be reflected in the wallet display
3/19/201419

20. The Wallet
Background Agent
20

21. The Wallet Background Agent
• Applications that use the wallet can also create a
Background Agent that can update the wallet on the phone
when the application is not being used
• The agent will also run when the user refreshes the card
from the Wallet
• Your application can use this in lots of different ways
• Update a list of transactions
• Inform the user of special offers
• Manage membership expiry
3/19/201421

22. Special Offer Display
• Special offers are displayed right next to the card details
• If the user activates the offer it will perform a deep link
activation of the application that can take the user directly
to the page for that offer
• The deep link is set by the background agent, so that the
application can identify the offer that has been made
3/19/201422

23. Creating a Wallet Agent
• A Wallet Agent works in a very similar way to other background tasks
• There is no template for the creation of the agent project
• Instead you have to create the agent as a class library and add it to the application
solution
3/19/201423

24. The Wallet Agent Project
• This is added to the solution just as with other agents
• The project output also needs to be added to the references of the application
3/19/201424

25. Adding the Wallet Background Task
• To link the agent to the application you need to modify the WMAppManifest.xml file for
the application
• The ExtendedTask item needs to be added, which sets the type of the agent and
identifies the assemblies to be used when it runs
3/19/201425
<Tasks>
<DefaultTask Name="_default" NavigationPage="MainPage.xaml" />
<ExtendedTask Name="BackgroundTask">
<BackgroundServiceAgent Specifier="WalletAgent" Name="WalletAgent"
Source="JumpstartWalletAgent" Type="JumpstartMembersClub.MyWalletAgent" />
</ExtendedTask>
</Tasks>

26. The Wallet Background Class
• This is the code that implements the agent
• The OnRefreshData method is called by the Windows Phone operating system to refresh
the wallet content
• It could use a web service to contact the host and do this
3/19/201426
public class MyWalletAgent : WalletAgent
{
protected override async void OnRefreshData(RefreshDataEventArgs args)
{
// Update the wallet items supplied in the args parameter
NotifyComplete();
}
}

27. Adding a Special Offer on refresh
3/19/201427
protected override async void OnRefreshData(RefreshDataEventArgs args)
{
foreach (WalletItem item in args.Items) {
WalletTransactionItem card = item as WalletTransactionItem;
if (card != null) {
if (card.Id == "Membership") {
card.Message =
"Cheese sale with special deals on Edam. Tap here for more details";
card.MessageNavigationUri = new Uri("/CheeseDealsPage.xaml",
UriKind.Relative);
await card.SaveAsync();
}
}
}
NotifyComplete();
}

28. Using the Special Offer
• The special offer text is displayed next to the card in the
wallet
• If the user taps the offer the application will be launched at
the page specified
• This works in the same way as a launch from any other deep
link
3/19/201428

29. Page Destination
• The background agent can define different entry pages
depending on the offer being made
• It can also include Query data in the URL which can be picked up
by the page and used to select particular behaviours
3/19/201429

30. Refreshing the Card
• The card will be refreshed before it is used for the first
time
• It can also be refreshed manually by the user
• When the refresh action is performed the
OnRefreshData method is called in the card agent
• The user can also delete the card and unlink it from the
application
3/19/201430

31. Deleting the Card
• The user can also delete the card and unlink it from the
application
• Unlinking is only a useful thing to do if other
applications can make use of that card
• The user can edit the card information, this will be
picked up by the application when it next uses those
card properties
• If the card has custom properties added by the
application they can be changed only by the card
application
3/19/201431

32. Demo
Demo 2: Using a Wallet Agent

33. Simple Wallet Use in Applications
• You can use these methods to make any user of your application a “card carrying member”
• The card can hold custom information for users and also provide alerts about new services
• The card will appear in the wallet on the Windows Phone, which provides another point of
access to your application
• While you can perform “transactions” on a membership card these only affect the balance
displayed on the card
• There is no transaction storage in this form of card
• You can however manage a balance display for the card user
3/19/201433

34. Creating and using
a payment
instrument card

35. Payment Instrument Cards
• If you want to create a card that tracks transactions you need to create a
PaymentInstrument to hold the card information
• This manages a list of transactions that your application can add to and search through
• It is created and used in exactly the same way as the membership card
• To create a PaymentInstrument the ID_CAP_WALLET_PAYMENTINSTRUMENTS capability
must be set for the application
• The card serves only as a container for the application data
• The application must provide all the business logic to update and manage the card data
3/19/201435

36. Creating a PaymentInstrument
3/19/201436
PaymentInstrument accountItem;
accountItem = new PaymentInstrument("Credit");
accountItem.PaymentInstrumentKinds = PaymentInstrumentKinds.Credit;
accountItem.IssuerName = issuer.IssuerName;
accountItem.DisplayName = issuer.IssuerName + " Bank Card";
accountItem.IssuerPhone.Business = issuer.IssuerPhone;
accountItem.CustomerName = details.CustomerName;
accountItem.AccountNumber = details.AccountNumber;
accountItem.BillingPhone = details.PhoneNumber;
accountItem.IssuerWebsite = new Uri(issuer.IssuerWebSite);
accountItem.ExpirationDate = details.Expires;
accountItem.DisplayAvailableBalance = "1000";
accountItem.DisplayCreditLimit = details.CreditLimit.ToString("C");
accountItem.DisplayAvailableCredit = details.AvailableCredit.ToString("C");

37. Creating a PaymentInstrument
• There are more properties to be set when a PaymentInstrument is created
• These must include the type of the card being made
• When working with payment information you need to be mindful of currency formatting in
the locale and culture where the phone is used
• An application can add this information to the payment instrument so that it can
customise the information display appropriately
• The example application on Windows Store shows how this is done
3/19/201437

38. Creating a transaction: Finding the Wallet
• The first stage in performing a transaction is finding the wallet to use
• The FindItem method will return null if the card is not found
3/19/201438
// Find the payment instrument to use
PaymentInstrument walletPay;
walletPay = Wallet.FindItem("Credit") as PaymentInstrument;
if (walletPay == null)
{
MessageBox.Show("Wallet not found");
return;
}

39. Creating a transaction: Setting the transaction details
• These transaction properties are required – shown here as hard-coded examples
• For your application they will reflect the actual action performed
• Note that the amounts are specified as strings
• They are textual descriptions of the actions performed
3/19/201439
// Create the transaction
WalletTransaction transaction = new WalletTransaction();
transaction.DisplayAmount = "10";
transaction.Description = "Cheese Purchase";
transaction.TransactionDate = DateTime.Now;

40. Creating a transaction: Storing the transaction
• The TransactionHistory property of a PaymentInstrument is implemented as a
dictionary that is indexed on a transaction identifier string
• Each identifier string must be unique or the Add action will fail
• The SaveAsync method commits the action to the actual wallet
• It is an asynchronous operation and so the method performing this action must be made
async
3/19/201440
// Add the transaction to the wallet
walletPay.TransactionHistory.Add("Cheese Purchase " + DateTime.Now, transaction);
await walletPay.SaveAsync();
MessageBox.Show("Transaction stored");

41. Viewing Transactions
• Transactions are stored in the wallet and can be
viewed in along with the card data
• The transaction list is only displayed once some
transactions have been added
3/19/201441

42. Demo
Demo 3: Using a Payment Instrument

43. Payment Instruments
• A payment instrument can be used as a store for credit and debit card details and
transactions that have been performed on them
• However, the card does not implement any of the banking behaviours as such
• The application must perform the management of the account information
• The Wallet infrastructure will provide a display mechanism and bring all the account
management activity into one place
3/19/201443

44. In-App Purchases

45. In-App Purchases
• In Windows Phone 7.x it was only possible to sell an application at a fixed price through
the Windows Phone Marketplace (now the Windows Phone Store)
• This was the only way you could get paid for the application
• The Windows Phone 8 application environment allows the developer to create an
application that contains paid content
• The Microsoft Store will issue licences for items that have been purchased by the users of
your application
• You can use this to activate application features or provide in-application resources, such
as items in games
3/19/201445

46. Build apps with higher and recurring revenue
opportunity
Customize
Add and modify different paid
options for different user
segments
Extend reach
Attract a larger user base with
free baseline experience
Upsell
Upsell users to purchase paid
digital goods and services that
enhance or extend the app
experience in the app itself
In-App Purchase

47. In-App Purchase used for digital content
Offer digital assets
Durables: buy once & own
forever, e.g. new game
levels, maps, game items
Consumables: game
currency, movie rentals,
access to digital magazines
for 6 months, etc.

48. Integrate In-App to app experience
Manage, monitor and respond
In-App Purchase: sell items in your app

49. Putting Products into the Microsoft Store
• As well as submitting applications to the store it is also possible to submit products for
purchase by users
• These will be purchased in just the same way as games, using the same payment
mechanism
• Products can then be assigned to a particular application
• This is performed using the Windows Phone Store Dashboard for that application
• The application can initiate purchases of the products
• The Microsoft Store retains licence information for the products that a user can purchase
• The application can determine which products have been purchased
3/19/201449

50. Creating an Application that uses products
• The developer creates the application and submits it to the Windows Store
3/19/201450
Developer
Application
Windows
Store
Submit app

51. Creating an Application that uses products
• The developer creates the list of products that can be sold alongside applications
3/19/201451
Developer
Application
Windows
Store
Submit app
Submit products

52. Creating an Application that uses products
• When the application runs it can request a list of products that are associated with that
application
• This list can be used to drive in-app purchasing options
3/19/201452
Developer
Application
Windows
Store
Submit app
Submit products
Get product list

53. Creating an Application that uses products
• The user can initiate the purchase operation
• This is managed in just the same way as Windows Store purchases
3/19/201453
Developer
Application
Windows
Store
Submit app
Submit products
Get product list
Purchase Products

54. Creating an Application that uses products
• When the application starts, and after a purchase operation, it can activate the purchased
feature or load the purchased content
3/19/201454
Developer
Application
Windows
Store
Submit app
Submit products
Get product list
Purchase Products
Get licences

55. Creating an Application that uses products
• The store will also supply a digitally signed receipt that can be used to manage access to
external resources provided to the user via the application
3/19/201455
Developer
Application
Windows
Store
Submit app
Submit products
Get product list
Purchase Products
Get receipt

56. Product Provision
• If the purchase relates to an in-application durable or consumable it is the responsibility of
the application writer to ensure that access to this is managed correctly and securely
• If the user buys the “Save” option for the program this should be enabled after the
purchase and each time they run the application
• If the player buys 1,000 health points it is up to the application to ensure that the health
is adjusted accordingly
• If the player buys a digital item (image, music) the application should ensure that this is
delivered to the application
• This may mean that the application must use the purchase receipts in conjunction with
their own systems
3/19/201456

57. Enumerating Listings for in game products
• The creator of this game has added two products, “Special Cheese” and “Ultra Cheese”
which can be used in the game
• These products have been assigned to this game
• The game can then request listing information for these items that will be used to manage
the purchase of the items
• The ids for these products are given in an array to the load method
• Once the items have been purchased the application can then validate this against the
store
3/19/201457
ListingInformation listings =
await CurrentApp.LoadListingInformationByProductIdsAsync(
new string[] { "Special Cheese", "Ultra Cheese" });

58. Making an in-application purchase
• This statement purchases the “Special Cheese” product
• The second parameter (in this case false) determines if a receipt is
to be provided for the purchase
• This is an asynchronous operation
3/19/201458
await CurrentApp.RequestProductPurchaseAsync("Special Cheese", false);

59. Using a Digital Receipt
• An application can request a digital receipt for a particular purchase
• The receipt is provided as a string of XML containing the transaction details
• This can be used to authenticate resources access on another service operated by the
application
3/19/201459
string receiptXml = await CurrentApp.GetProductReceiptAsync("Cheese Music");

60. Checking if a licence has been purchased
• This is the code used to determine if the product has been purchased
• The application reports that the purchased item has been delivered to the user by calling
the ReportProductFulfillment method and identifying the purchased item
• If the product is a consumable it can be purchased again
• The application must securely store the new status setting
3/19/201460
var productLicenses = CurrentApp.LicenseInformation.ProductLicenses;
var licence = productLicenses["Special Cheese"];
if (licence.IsActive)
{
// enable Special Cheese Power
CurrentApp.ReportProductFulfillment("Special Cheese");
}

61. Managing the state of a consumable
• A consumable item can be purchased multiple times
• Each time it is purchased the application must make the appropriate changes to the status
and report that it has been delivered
3/19/201461
var productLicenses = CurrentApp.LicenseInformation.ProductLicenses;
var licence = productLicenses["Cheese Power Points"];
if (licence.IsConsumable && licence.IsActive)
{
// add the extra points
cheesePower = cheesePower + 200;
CurrentApp.ReportProductFulfillment("Cheese Power Points ");
}

62. In-App Purchases
• In-App purchases provide a very powerful way of monetising an application
• It is now possible to move from “Trial Mode” to “Full Version” without needing the user
to download a new application
• Remember however that the responsibility for managing the in-application products
purchased is yours
• It is important that the application protects the purchases that have been made by users
of the program
3/19/201462

63. Review
• Applications in Windows 8 can use the Wallet to manage membership information for users
• The Wallet Agent allows an application to update special offers and other information
automatically
• The Payment Instrument mechanism provides a way that transactions can be stored and
viewed on Windows Phone
• Applications can now provide a menu of products which can be purchased from within the
program
• These can be consumable (can be bought multiple times) or durable (are bought once)
• The Windows Store will track licences that have been purchased for an item and provide
receipts that can be used to authenticate resource access
63

64. The information herein is for informational
purposes only an represents the current view of
Microsoft Corporation as of the date of this
presentation. Because Microsoft must respond
to changing market conditions, it should not be
interpreted to be a commitment on the part of
Microsoft, and Microsoft cannot guarantee the
accuracy of any information provided after the
date of this presentation.
© 2012 Microsoft Corporation.
All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.
MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION
IN THIS PRESENTATION.