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 · 5 min read
Saved credit cards display

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

Web payments overview

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.

Payment Request API goals

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
For obvious security reasons, the Payments Request API only works in the HTTPS protocol.

Payment API Demo

Payment API demo

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

You should see a very simple counter with a buy button

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:

Review your payment

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.

Visa test card
Adding a Visa test card

Handling the payment

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


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.


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

Full Payment Demo

Making a payment only with the Payment API

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

Browser support

Is Payment API supported?

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:

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

If you want to level up your JavaScript game, I’d recommend going through this excellent book. Find the Kindle version here.

Thanks for reading — happy coding! ❤

Better Programming

Advice for programmers.

Indrek Lasn

Written by

Simplicity matters. Grow together. Follow me on Twitter @ https://twitter.com/lasnindrek

Better Programming

Advice for programmers.