Storing Payment Instruments in the Wallet

Payment Instruments include banking cards, such as credit and debit cards, and financial payment services, which are capable of performing a financial transaction.

The following example demonstrates the creation of a PaymentInstrument object that represents a credit card:

Click here to view code image

var instrument = new PaymentInstrument(card.Id.ToString())
                {
                    AccountNumber = "123456",
                    CustomerName = "Alan Turing",
                    ExpirationDate = DateTime.Now.AddMonths(3),
                    DisplayName = "Unleashed Card",
                    PaymentInstrumentKinds = PaymentInstrumentKinds.Credit
                };

Wallet items, such as the PaymentInstrument class and its super class WalletTransactionItemBase, have a multitude of optional properties for storing information such as address details, billing information, and financial transactions. You can choose to fill in as many or as few of those fields as you need. You can also create custom fields for storing other data if need be, which you look at later in the chapter.

Use the AddWalletItemTask class to add a payment instrument to the Wallet. The AddWalletItemTask follows the launchers and choosers model from Chapter 14, “Leveraging Built-In Apps via Launchers and Choosers.”

The AddWalletItemTask resides in the Microsoft.Phone.Tasks namespace. As a general rule, if you are subscribing to a task’s Completed event, the task should be instantiated as a field of your page or viewmodel, and its Completed event subscribed to in the constructor, as demonstrated in the following excerpt:

Click here to view code image

class CardViewModel : ViewModelBase
{
    readonly AddWalletItemTask addWalletItemTask = new AddWalletItemTask();
    ...

    public CardViewModel() : base("Card")
    {
        ...

        addWalletItemTask.Completed += HandleAddWalletItemTaskCompleted;
    }
...
}

With the AddWalletItemTask ready to go, the task’s Item property is set to the instrument, and the task’s Show method is called:

Click here to view code image

addWalletItemTask.Item = instrument;
addWalletItemTask.Show();

The Show method presents the user with a confirmation dialog, and the OS adds the payment instrument to the Wallet.

When the user completes or cancels out of the task, the Completed event is raised, and the event handler receives a TaskResult value indicating whether the item was successfully added to the Wallet.

The following excerpt demonstrates how to handle the Completed event:

Click here to view code image

void HandleAddWalletItemTaskCompleted(object sender, AddWalletItemResult e)
{
    if (e.TaskResult == TaskResult.OK)
    {
        MessageService.ShowMessage(
            e.Item.DisplayName + " was added to your wallet.");
    }
    else if (e.TaskResult == TaskResult.Cancel)
    {
        MessageService.ShowMessage("Cancelled");
    }

    Refresh();
}

In the following section, you see how these principles are applied to a simple banking app.