In this article I want to tell you about the Payment Request API, a native API of the modern browsers that I discovered the other day and that aims to facilitate the user agent to act as an intermediary between users and sellers of services or products.

I have taken this weekend to mess with this API a little and here I leave a small article as an introduction in case you want to try it in one of your side projects. At the end of the article you will find a repository from which you can download a basic project written in React where I use this API in case you want to start working from there.

The truth is that it looks very good so as always, let’s do it!

0. Introduction

Before starting and in case you are considering using this API in production, tell them that according to the web caniuse.com it gives 85% support among browsers, so keep that in mind if you are going to start working with it.

And, although it is obvious at this point, this API is only available if our page works under HTTPS.

Objectives of the Payment Request API

Based on the Payment Request API documentation on w3.org, its objectives are:

• Allow the “user agent” to act as an intermediary between the seller, the user and the payment method provider by providing a consistent experience in all the websites that implement this API. This, for example, is an improvement in accessibility, since it is the browser that controls the input elements so that they are accessible to all types of users.
• Streamline the payment experience taking into account the user’s payment preferences (which are stored in the browser preventing the user from having to enter them multiple times), security requirements and seller information.
• Standardize the communication flow between the seller, the user and the payment method.

That is, it is a very interesting API in order to reduce the “friction” that the user means to deal with different forms of payment and forms on the different websites where you want to make purchases.

Below I will show you a simple example explaining how to integrate it.

1. The PaymentRequest object

To start working with this API we will focus on the PaymentRequest object.

Since as I mentioned before, not all browsers support it, we can perform the compatibility check using the following code extracted from the documentation provided by Google for this API:

if(window.PaymentRequest) {
  // Use Payment Request API
} else {
  // Fallback to traditional checkout
}

The PaymentRequest builder receives 3 arguments:

• An array to specify the payment methods supported.
• An object to specify the details of the transaction.
• And an object of options where to modify some aspects of the behavior of the browser once it begins to control the payment process such as requesting the name, email or telephone number of the buyer or his shipping address.

For example, we can create the following PaymentRequest object:

The explanation of the code is as follows:

• The supportedPaymentMethods object defines that we accept payments with VISA and MasterCard cards.
• The paymentDetails object establishes a single (total) payment of € 20.
• Finally the object options (which is not required in the constructor) we leave it empty in order not to complicate this example.

With this the next step will be to add a button that allows us to delegate the payment process to the browser.

2. Payment process and PaymentResponse object

Once we have created the PaymentRequest object, the next thing we will do is add a button to our code that launches the payment process linked to the browser.

In this way, when the button is pressed, what we will do is execute the show method of the PaymentRequest object which returns a Promise that when resolved will return a PaymentResponse object with the result of the process.

PaymentResponse object contain the following properties:

• methodName with the payment method selected by the user.
• details, with the details of the payment made.
• payerName that will be null unless we have set the value true for the requestPayerName property in the options object.
• payerPhone that will be null unless we have set the value true for the requestPayerPhone property in the options object.
• payerEmail that will be null unless we have set the value true for the requestPayerEmail property in the options object.
• shippingInfo for shipping information.

Therefore, if we now click on the Pay button, what we will obtain will be a dialogue like the following:

Now, if we click on the Add button we can set the card we want to use. In order not to use real data we can use the card number provided by VISA for testing:

4242 4242 4242 4242

Once this is done, we can complete the payment by clicking on the Pay button:

And we will get the following PaymentResponse object by console:

If you realize, the modal that launches the browser to manage the payment does not close automatically once the payment is completed but we will have to do it using the complete method of the PaymentResponse object.

This method receives as argument a string with one of the following values:

• success to indicate that the payment has been processed successfully. In this case, the browser may show the user a message informing them that the payment has been completed correctly.
• fail, if there has been a failure processing the payment and, again, it is up to the browser to show a message or not informing the user of this.
• unknown, in the event that the result of the transaction is unknown or irrelevant. This will force the browser to not present any notification by itself unlike the previous two cases. This is the default value.

Therefore, to the previous code we will add the following:

So now, the modal opened by the browser is closed.

The need to have to use the complete method of the PaymentResponse object is because we may want to validate the payment or register it in our “backend”:

Conclusions

As you have seen, the Payment Request API provides us with a native and easy way to add a payment gateway to our application so that we can simplify this process and standardize it.

Of course, this article has only been an introduction, since there is much more behind this API, such as the possibility of managing shipping methods, handling errors that happen or checking if the payment methods that the user has registered in their browser are compatible with those of our platform using the canMakePayment method.

If you want to try the example of this article in your browser you can clone the following repository:

References

Do you want to read more articles like this?

If you liked this article I encourage you to subscribe to the newsletter that I send every Sunday with similar publications to this and more recommended content: 👇👇👇