The Payment Request API makes it easy to handle payments in a website or app. In this article, we'll take a look at how the API operates and what each of its components does.
Before getting into the details of how the API operates, there are items you'll need to know.
The merchant—either a person or an organization—whose website or app wishes to receive money through the Payment Request API.
The person or organization making a purchase using a website or app. The payer authenticates themselves, then authorizes payment, as required by the payment method.
The instrument by which payment is submitted, such as a credit card or online payment service.
An organization that provides the technology needed to submit payments using a given payment method. For example, when using a credit card to pay, the credit card processing service is the payment method provider.
The implementation of the code needed to interface with a particular payment method provider in order to process payments.
Some payment handlers use merchant validation, which is the process of validating the identity of a merchant in some way, usually using some form of cryptographic response such as a public key. Validated merchants are allowed to interface with a payment handler.
Payment handlers are identified by payment method identifiers, which are strings uniquely identifying the payment handler. These may be either one of the standardized payment handler identifiers, or a URL used by the payment processing service to both identify itself and to handle payments.
Standardized payment method identifiers are those listed in the payment method registry.
secure-payment-confirmationIdentifies the Secure Payment Confirmation method. The payment request data for this method is defined by the SecurePaymentConfirmationRequest dictionary. For more information see Using Secure Payment Confirmation.
basic-cardThis payment method identifier was intended to facilitate card-based payments on the Web through the Payment Request API. The Web Payments Working Group has deprecated this payment method.
These identifiers are typically provided by payment service providers during onboarding or integration and may vary substantially depending on the specifics of the service, API version, and communication technology. Developers will usually obtain these identifiers directly from their chosen payment service provider's documentation rather than discovering them independently.
https://apple.com/apple-payPayments are handled using the Apple Pay service. This payment method is primarily supported in Safari on compatible Apple devices.
https://google.com/payPayments are processed by Google Pay. Support depends on browsers that implement the Payment Handler API (currently primarily Chromium-based browsers).
A user agent may provide built-in support for certain types of payments. In addition, the Payment Handler API can be used to establish support for additional payment method providers, in browsers that support it. In either case, the payment handler is responsible for:
Some payment handlers use merchant validation, which is the process of validating the identity of a merchant in some way, usually using some form of cryptographic challenge. If the merchant doesn't successfully validate, it's not allowed to use the payment handler.
The exact validation technology depends on the payment handler, and merchant validation is entirely optional. In the end, the only thing that the website or app is responsible for is fetching the merchant's validation key and passing it into the event's complete() method.
paymentRequest.onmerchantvalidation = (event) => {
event.complete(fetchValidationData(event.validationURL));
};In this example, fetchValidationData() is a function which loads the payment handler specific identifying information from the address given by validationURL. Note this function must go through the merchant server, because a client typically does not access the validation URL itself.
By then delivering this data (or a Promise which resolves to the loaded data) to the payment handler by passing it into complete(), the payment handler can use the retrieved data and whatever algorithm and other data to support in order to verify that the merchant can use the payment handler.
Thus, it's important to note that the user agent never sends a merchantvalidation event, unless the user agent itself implements a payment handler. For instance, Safari has integrated support for Apple Pay, so the Apple Pay payment handler uses this to ensure that Apple Pay can be used to pay the merchant by sending merchantvalidation to the client, instructing it to fetch the server's validation data and deliver it to the payment handler by calling complete().