What Is the Native Payment Request API?

Did you know that many modern browsers have a built-in Payment Request API

Indrek Lasn
Jul 1, 2019 · 5 min read
Image for post
Image for post

Payment Request API — a W3C browser standard facilitates the exchange of payment and contact information.

Image for post
Image for post

The Payment Request API provides a browser-based method of connecting users, and their preferred payment systems and platforms, to preferred merchants requiring payment for goods and services.

Image for post
Image for post

This is a brilliant option since the idea behind the Payment API is to standardize how we pay for things, reduces friction when it comes to implementing accepting payments, and produces less volatile bugs.

What the PaymentRequest API looks like:

As you can see, we create a new instance of the Payment API with a constructor method. The payment constructor takes two mandatory parameters and one optional parameter:

  • methodData — an object containing information concerning the payment provider, such as what payment methods are supported, etc.
  • details — an object containing information concerning the specific payment, such as the total payment amount, tax, and shipping cost
  • options (optional) — an object containing additional options related to the payment
Image for post
Image for post

Payment API Demo

Image for post
Image for post

As we can see, the payment is directly integrated into the browser. No more insecure third-party redirects or API calls — everything happens directly in the browser!

Getting started

The Payment API is experimental technology and is apt to change in the future. I still encourage getting familiar with this new API since I believe the proposal is strong and here to stay; maybe some incremental additional new features will be added.

If you wish to follow the examples along, grab a copy of the repository.

git clone https://github.com/indreklasn/payments-request-api-example.git && yarn && yarn start

This shell command will clone the repo, install the dependencies, and start the server at localhost:3000

Image for post
Image for post

Note: The Payment API works on localhost for testing purposes.

Since our app is simple, we’re going to place all payment related logic into the app.js file.

Here’s some boilerplate code. We grab the DOM elements and hook them up with the increment and decrement buttons. We also show the final count to the user.

Imagine the increment as adding an item to the basket, decrement as removing the item from the basket, and count showing the total price to pay for the cart checkout.

Implementing the payment

Once the user clicks the BUY button, we create a new instance of the payment request. Now we need to define buildSupportedPaymentMethodData and the buildShoppingCartDetails methods.

The first argument buildSupportedPaymentMethodData is a method that returns an array of objects of all the supported payment methods.

The second argument buildShoppingCartDetails shows the information used to build up the purchase.

This constitutes, for example, what the user is buying; how much it costs; and what is the total sum.

Notice this time we return an object, instead of an array of objects.

Ok, we’re ready to show the payment request window to the user. Let’s call the show method on the request instance. This returns a paymentResponse promise. If you’re not too familiar with promises, check out this article.

If we press the BUY button, we should see this prompt:

Image for post
Image for post

You probably need to add a payment card. I recommend using the Visa test card. Insert the number, your name, and address. Those don’t have to be valid for test purposes.

Image for post
Image for post
Image for post
Image for post

Handling the payment

Once we insert a card and approve the payment, we’re getting a paymentResponse returned from the promise request.

Image for post
Image for post

Since the payment is fulfilled now, all the methods and properties are read-only on the paymentResponse object.

Let’s call paymentResponse.complete() to indicate to the user that everything went as expected.

Image for post
Image for post

Voila! That’s all the code we need for our super-simple shopping cart.


Full Payment Demo

Image for post
Image for post

Here’s the source code in case you want to take a deeper dive.

Browser support

Image for post
Image for post

Since this is a relatively new API, it’s not too well supported yet. Brave, Chrome, Safari, Firefox, and Edge all support the new Payment APIs, and you can already try it with your browser.

On a side note, clearly, the new Payment API needs more work to be done, especially for mobile browsers. I wouldn’t rely on this API too much for mobile just yet.


Where to go from here?

So much to learn with so little time. I highly recommend reading the following:

Web Component Essentials

These are are all really useful and articulate sources to learn more about the Payments APIs.

Bonus: If you want to take your JavaScript abilities to the next level, I’d recommend reading the “You Don’t Know JS” book series.

Thanks for reading — happy coding! ❤

Better Programming

Advice for programmers.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store