How Payment Request API works

When a customer tries to purchase something from your website, the site must ask the customer to provide payment information and, optionally, other information such as shipping preference. You can achieve this easily and quickly using the Payment Request API (PR API).

Basic structure

Constructing a PaymentRequest object requires two parameters: payment methods and payment details. In addition, a third payment options parameter is optional. A basic request could be created like this:

const request = new PaymentRequest(paymentMethods, paymentDetails);

Let's look at how each parameter is built and used.

Payment methods

The first parameter, paymentMethods, is a list of supported payment methods in an array variable. Each element in the array comprises two components, supportedMethods and, optionally, data.

For supportedMethods, the merchant needs to specify a Payment Method Identifier such as https://bobbucks.dev/pay. The existence and content of data depends on the content of supportedMethods and payment app provider's design.

Both pieces of information should be provided by the payment app provider.

// Supported payment methods
const paymentMethods = [{
  supportedMethods: 'https://bobbucks.dev/pay',
  data: {
    ... // Optional parameters defined by the payment app provider.
  }
}];

Payment details

The second parameter, paymentDetails, is passed as an object and specifies payment details for the transaction. It contains the required value total, which specifies the total amount due from the customer. This parameter can also optionally list the purchased items.

In the example below, the optional purchased items list (just one item, in this case) is shown, as is the required total amount due. In both cases the currency unit is specified with each individual amount.

const paymentDetails = {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
};

Check whether the payment method is available

Before invoking the payment procedure, the merchant can check whether the user and the environment are ready for making a payment.

Calling canMakePayment() checks if the browser supports at least one payment method specified in the object.

request.canMakePayment().then(result => {
  if (result) {
    // This browser supports the specified payment method.
  } else {
    // This browser does NOT support the specified payment method.
  }
}).catch(e => {
  // An exception
});

Learn more about PaymentRequest.canMakePayment() on MDN

The show() method

After setting the two parameters and creating the request object as shown above, you can call the show() method, which displays the payment app user interface.

{% Aside 'warning' %}

To call the show() method, you must add a user activation. This means the call must be inside an event listener, such as click. Note that Chrome enforces this constraint from version 102.

{% endAside %}

request.show().then(response => {
  // [process payment]
  // send to a PSP etc.
  response.complete('success');
});

{% Aside %}

basic-card payment method is deprecated from Chrome 100. If the browser doesn't support any of the specified payment methods, it will throw NotSupportedError. Make sure to first check the payment method availability with canMakePayment().

{% endAside %}

How payment app user interface will look is completely up to the payment app provider. After the customer agrees to make a payment, a JSON object is passed to the merchant which contains all the required information to transfer money. The merchant can then send it to the PSP to process the payment.

Finally, you may close the Payment Request UI by completing the process with response.complete('success') or response.complete('fail') depending on the result that the PSP returns.

Next up

Learn more about Web Payments.