Tag Archives: Payment Request API

ICYMI – Your weekly TL;DR

Spring is here and so is another weekend! Check out what you might have missed this week before diving into weekend projects.

Microsoft Store Services SDK launches support for interstitial banner ads

This week we announced the launch of interstitial banner ads support in the Microsoft Store Services SDK! Read more to learn how to add them to your apps.

Simplify payments in UWP Apps with the Payment Request API from Microsoft

The Windows 10 team wants to help you take advantage of new simplified payment options for Windows 10 UWP apps. Click through right here to find out how you can add these options into your apps.

New MapControl features in Windows 10 Creators Update

We have updated the Maps platform for the Windows 10 Creators Update to give our maps a cleaner, more beautiful and realistic look so that it’s consistent between web and UWP apps.

Download Visual Studio to get started.

The Windows team would love to hear your feedback. Please keep the feedback coming using our Windows Developer UserVoice site. If you have a direct bug, please use the Windows Feedback tool built directly into Windows 10.

Simplify payments in UWP apps with the Payment Request API from Microsoft

The Windows 10 team wants to help you take advantage of new simplified payment options for Windows 10 UWP apps. A not-so-appealing part of the ecommerce shopping experience to this day is the checkout process. The average documented shopping cart abandonment rate is 68.81 percent, and 27 percent of U.S. online shoppers have abandoned an order in the past quarter due to a “too long /complicated checkout process [source].”

Over 90% of paid App Developer revenue has been coming from In-App Purhcases (IAP), now app developers can add a new business model and revenue stream by taking advantage of the new Payment Request API to sell physical goods and services or conduct other commerce not supported natively in the Windows and Xbox stores. This API provides an integrated for Universal Windows Platform (UWP) Apps to bypass the complicated process of requiring a user to input payment information and select shipping methods.

After a simple implementation, described below, the millions of customers who already have a payment option saved with Microsoft will be able to check out more seamlessly in your app. This gives customers a faster and more convenient way to pay because they do no need to enter their payment information every time they want to purchase a product in your app.

What the Payment Request API for UWP Apps Enables

The Payment Request API for UWP apps, based on the W3C Payment Request API spec, gives app developers the ability to streamline the checkout process in their UWP Apps. It does so by allowing users to speed through the checkout process, by using payment options and shipping address, already saved with their Microsoft account. You can increase conversion and reduce your risk of data breaches because the payment information is tokenized. With the Windows 10 Creators Update, users can pay with their saved payment options freely throughout experiences in Windows including in UWP apps or on the web via the Microsoft Edge browser.

We are excited to announce the availability of the Payment Request API for UWP app developers today – starting with the OS Build and SDK version 15003.

With this release, we expand on the capabilities already announced for web developers, in the Microsoft Edge Team blog post, which walks you through how to call the Payment Request API from within the Microsoft Edge browser.

Figure 1. Process flow diagram of the Payment Request API

How to use the API

1. Start by creating a set of all the payment options that you accept. You can decide to create a request and resubmit the same one each time. Or create a new request on each button click.

// Enumerate all the payment methods our store accepts.
var data = new
                supportedNetworks = new[] { "visa", "mastercard" },
                supportedTypes = new[] { "credit" },
                mode = "TEST"

var acceptedPaymentMethodsAll = new[]
                new PaymentMethodData(new[] { "https://pay.microsoft.com/microsoftpay" },                     

2. Pull together the payment details. These details will be shown to the user in the payment app. Please note that the API will not add up the items or calculate the sales tax for you. It’s up to you to provide the required information correctly.

// Aggregate all the prepared payment details.
var details = new PaymentDetails()
       DisplayItems = displayItems,
       Total = totalItem,
       ShippingOptions = new List<PaymentShippingOption>
           new PaymentShippingOption("Standard (3-5 business days)", new PaymentCurrencyAmount("0.00",            
           new PaymentShippingOption("Express (2-3 business days)", new PaymentCurrencyAmount("4.99", 
           new PaymentShippingOption("Overnight (1 business day)", new PaymentCurrencyAmount("11.99", 
        Modifiers = new[]
            new PaymentDetailsModifier(new[] { "contoso/credit" }, totalItemForContosoCard, 

3. You can put all the assembled payment details together in one payment request.

// Create a new payment request and associated internal state describing this proposed transaction.
    var state = new PaymentRequestState();
    var request = new PaymentRequest(details, acceptedPaymentMethods, merchantInfo, options);

Submitting the Payment Request (shows the UI

1. Call the SubmitPaymentRequestAsync method to submit your payment request. This will bring up the payment app showing the available payment options.

// Submit the payment request for mediation and (possibly) user review.
state.SubmissionRequestOperation = paymentMediator.SubmitPaymentRequestAsync(request, async (sender, args) =>
       args.Acknowledge(await HandlePaymentRequestChangedAsync(request, args, state));

Processing payment request updates

1. The total price to a user might change depending on the shipping address and preferred shipping option the user selects. The following code creates the available shipping options based on the shipping address provided by the user.

private static async Task<IReadOnlyList<PaymentShippingOption>> GetShippingOptionsForAddressAsync(PaymentAddress address)
   // Compose a list of available shipping methods for this address.
    var methods = (address.Country.Equals("USA"))
        ? ShippingMethodsDomestic
        : ShippingMethodsInternational;

    // Calculate the shipping cost for each available shipping method based on this address.
     return await Task.WhenAll(
         methods.Select(async (method) => new PaymentShippingOption(method, await 
                        GetShippingCostAsync(method, address))));

Processing the payment response

Process the payment token returned in the payment response as part of the submissionResult.Response.PaymentToken object.

var tokenProcessingResult = PaymentRequestCompletionStatus.Failed;
    // TODO: Process payment token from submissionResult.Response.PaymentToken
    // If processing succeeded, set tokenProcessingResult to PaymentRequestCompletionStatus.Succeeded

Completing the Payment Request

Send the payment mediator the updated tokenProcessingResult. If the returned status is “Succeeded,” the payment app will indicate success and will then return focus back to your app. If “Failed” is returned, the  payment app UI will indicate payment failure to the user.

// Notify payment app of processing result.
// Payment application will now disappear from UI. Transaction complete.

Feature detect (check universal API contract version)

1. The minimum OS version that the Payment Request API will be supported on is the Windows 10 Anniversary Update. You can use the following code to check if the Payment Request API is supported on the user’s device/build. If the API is not supported, you can then direct users to use other means to complete the purchase in your app.

var isPaymentApiSupported = ApiInformation.IsTypePresent(Windows.ApplicationModel.Payments.PaymentMediator);
if (isPaymentApiSupported)
        // Payment API is supported, continue with payment request creation.

Availability and Documentation

The Payment Request API will be available for testing as part of the SDK included with Build 15003 on phone and desktop. Developer documentation for the API is available here on MSDN.

Onboarding Requirements

For UWP applications, we support tokenized payment method(s) via integration with payment service providers. The response from a payment request will contain a microsoftpay token inside of which will be a single use token from your payment service provider. Microsoft requires authorization from you to request payment service provider tokens on your behalf. Therefore, before you can get started, we need you to follow a few steps to register for a seller account and provide the necessary authorization. To get started, visit Microsoft Seller Center to register, accept the terms and provide us access to request tokens on your behalf. Once you have done this, copy the resulting Merchant ID from the dashboard into your application when constructing a payment request. Then, when your application submits a payment request, you will receive a payment token from your processor which you will need to submit for payment.

Geos and Localization

Initially, this payment API can only be used by US based businesses to process US-region transactions. The user experience will support over 100 languages. Support for payments outside of the US will be added later at which time we will post an update to the developer community.

To Sum Up

Digital payments are on the rise and our team at Windows wants to help you take advantage of this trend. We’ve created an API that you can harness to improve in-app checkout experiences and enable increased purchase activity.

Windows users can expect a polished and trusted checkout experience that removes the need to reach for their credit card every time they want to make a purchase. We are excited to make this announcement and cannot wait for you to try out the API and provide us with your feedback.

Simpler web payments: Introducing the Payment Request API

We’re thrilled to introduce a preview implementation of the Payment Request API in Microsoft Edge, enabling simpler checkout and payments on the web on Windows 10 PCs and Phones. Support for Payment Request in stable builds will be coming to EdgeHTML 15 in the Creators Update early next year.

Payment Request works with Microsoft Wallet on Windows 10 PCs and phones to make ecommerce faster and simpler for customers and merchants alike. You can begin to develop for the Payment Request API today in Microsoft Edge on preview builds, starting with Windows Insider Preview build 14986. The Microsoft Wallet user experience allowing for end to end testing will be available in an upcoming Insider build soon.

Screen capture showing an example Microsoft Wallet checkout dialog. The dialog reads "Confirm and Pay," with dropdown menus for "Pay with," "Ship to," "Shipping options," and "Email receipt to," with the total amount and a "Pay" button.

Conversion rates in the checkout flow are a key measure for ecommerce sites. 46% of e-commerce shoppers abandon the checkout process during the payment phase, signaling frustration with the complexity and redundancy of re-entering form data or tracking down payment information. Even a small increase in the success rate of checkout make a direct impact on your site’s bottom line, while improving the shopping experience for customers.

In Microsoft Edge, the Payment Request API connects to Microsoft Wallet (with the user’s permission), allowing easy access to payment information associated with the user’s Microsoft Account. Because payment information is securely saved in a digital wallet, shoppers don’t have to navigate through traditional checkout flows and repeatedly enter the same payment and shipping address information repeatedly. The wallet can provide a faster and more consistent experience across websites, which saves shoppers time and effort by allowing them to securely share saved payment information.

How does it work?

Microsoft and the other members of the W3C Web Payments Working Group designed the API with the goal of standardizing communication across merchants, browsers, and payment methods to provide a better experience for users, and a single, consistent API for developers.

With the Payment Request API, payment information is provided by the wallet (once the user has granted consent), as opposed to being collected via a checkout form in the website. The browser mediates all the information passed between the wallet and the merchant.

Flow chart illustrating the browser mediating a payment from a user to a merchant via a wallet app on the local system.

Let’s look at how to implement the Payment Request API into a sample site.


We start with the constructor. The PaymentRequest object is constructed by passing the following parameters:

  • methodData: an array of dictionaries that contains the payment method identifiers and any pertaining data; a payment method identifier is a string that identifies a supported payment method
  • details: information about the transaction, such as the line items in an order
  • options: additional information that the Wallet may need to collect


In the snippet above, we are allowing users to pay with any debit or credit card that belongs to Visa, MasterCard, or Amex networks. The details object contains the subtotal amount, the sales tax, and the total due. These details will be shown to the user in the wallet. Please note that the API will not add up items or calculate the sales tax – it’s up to the merchant to provide the correct information. In this example, we are selling a physical good, so we’ll ask the wallet to collect the customer’s shipping address.

Showing the UI, processing the payment, and displaying the results

Once the PaymentRequest object is created, you can trigger the browser to display the wallet with request.show(). In Microsoft Edge, this will present the user with a checkout dialog from Microsoft Wallet:

Screen capture showing an example Microsoft Wallet checkout dialog. The dialog reads "Confirm and Pay," with dropdown menus for "Pay with," "Ship to," "Shipping options," and "Email receipt to," with the total amount and a "Pay" button.

Customers can then select the appropriate payment information, shipping address, and other fields, then click Pay when ready. At this point, the users will have to verify their identify. If successful, this will fulfill the request.show() promise and return  to the website all the information that the customer provided to the Wallet. For the basic card payment method, the result object will contain the card holder name, card number, expiry month and other relevant fields. The merchant can then use this information to process the transaction on the backend.

After the response comes back from the server, you can use result.complete(‘success’) to display the success screen in the Wallet and result.complete(‘fail’) to indicate a failed transaction.


Listening for events

The price might change according to the shipping address and shipping options that the customer selects. You can listen to those changes with the shippingaddresschange and shippingoptionchange events to recalculate the prices accordingly.


Feature detection

Sites can feature detect for the Payment Request API, forward the user to a legacy, form-based experience if it is not available.


Here’s an example of a minimal implementation of this code:


Testing & Availability

The Payment Request API is on by default starting with the most recent Windows Insider Preview release (14986 or higher) on phone and desktop. The Microsoft Wallet user experience allowing for end to end testing will be available in an upcoming Insider build soon. During this preview period, Microsoft Wallet’s response for the basic card payment method will be a fake payment card response, to help developers perform early-integration testing without having to deal with the constraints of PCI.

Starting next Spring, the API will begin to return real payment card responses. Initially, the Wallet will support US billing and shipping addresses and the English language (en-US locale). Support for additional geographies and languages will be added in 2017.

Wrapping it up

Microsoft Wallet and the Payment Request API combine to provide a powerful tool for merchants to improve checkout conversion on the web, and to give customers a more pleasant and convenient shopping experience. This API is a great example of the power and flexibility of the web platform, and is on the road to broad interoperability, with Chrome for Android supporting the API starting with Chrome 54.

More details and full documentation for the Payment Request API in Microsoft Edge are available at the Payment Request Developer Guide on Microsoft Edge Dev, and the Payment Request API Reference on MSDN. You can preview Payment Request today, along with other new features coming to EdgeHTML 15, by joining the Windows Insider Program, or by downloading preview virtual machines from Microsoft Edge Dev for your Mac or PC.

If you encounter issues, you can file bugs on bugs.microsoftedge.com, or connect with us on Twitter at @MSEdgeDev. We look forward to hearing from you!

Andy Pavia, Program Manager, Microsoft Edge