Payment Request API overview

How the Payment Request API works

The Payment Request API (PR API) gives web merchants a standardized way to collect payment information and, when needed, shipping preferences from customers. The API handles the complexity of invoking the payment app and returning the customer's chosen payment data to your site.

Creating a PaymentRequest object

To start a transaction, instantiate a PaymentRequest with a list of supported payment methods, the transaction payment details, and an optional third parameter for payment options such as shipping configuration. Here's a minimal example:

const request = new PaymentRequest(paymentMethods, paymentDetails);

Defining payment methods

The paymentMethods parameter is an array where each element contains the required supportedMethods string plus an optional data object. The supportedMethods value is a Payment Method Identifier such as https://bobbucks.dev/pay. The structure and content of data is defined by the payment app provider and varies based on the method. Both of these values are supplied by the payment app provider, so the merchant simply passes them through:

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

Specifying payment details

The second argument, paymentDetails, is an object that describes the transaction. Every request must include the total value, which is the amount due from the customer. You may also include a displayItems array to list the individually purchased items. Each amount, whether for the total or an item, must specify its currency and value:

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' }
  }
};

Checking for supported payment methods

The browser checks the user's environment when the PaymentRequest object is constructed. To proactively verify whether the user can produce at least one of the requested payment methods, call canMakePayment() before launching the UI. It returns true if the browser supports at least one of the methods in the request:

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
});

Displaying the payment app

Once the request is set up, call show() to display the payment app's user interface:

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

The look of this interface is up to the payment app provider. After the customer confirms the payment, the browser resolves the promise with a response object containing all the data needed to process the money transfer. Send that to your payment service provider (PSP), and once it returns its result, conclude the flow by calling either response.complete('success') or response.complete('fail') to close the UI.