+ In order to use the API, the developer needs to provide and keep track + of a number of key pieces of information. These bits of + information are passed to the PaymentRequest constructor as + arguments, and subsequently used to update the payment request being + displayed to the user. Namely, these bits of information are: +
++ Once a PaymentRequest is constructed, it's presented to the end + user via the show() method. The show() returns a promise + that, once the user confirms request for payment, results in a + PaymentResponse. +
+methodData argument
+ + The methodData sequence contains PaymentMethodData + dictionaries containing the payment method identifiers for the + payment methods that the web site accepts and any associated + payment method specific data. +
+
+ const methodData = [
+ {
+ supportedMethods: "basic-card",
+ data: {
+ supportedNetworks: ["visa", "mastercard"],
+ supportedTypes: ["debit", "credit"],
+ },
+ },
+ {
+ supportedMethods: "https://example.com/bobpay",
+ data: {
+ merchantIdentifier: "XXXX",
+ bobPaySpecificField: true,
+ },
+ },
+ ];
+
+ details argument
+ + The details contains information about the transaction + that the user is being asked to complete, such as the line items in + an order. +
+
+ const details = {
+ id: "super-store-order-123-12312",
+ displayItems: [
+ {
+ label: "Sub-total",
+ amount: { currency: "USD", value: "55.00" },
+ },
+ {
+ label: "Sales Tax",
+ amount: { currency: "USD", value: "5.00" },
+ },
+ ],
+ total: {
+ label: "Total due",
+ amount: { currency: "USD", value: "65.00" },
+ },
+ };
+
+ + Here we see an example of how to add two shipping options to the + details. +
+
+ const shippingOptions = [
+ {
+ id: "standard",
+ label: "🚛 Ground Shipping (2 days)",
+ amount: { currency: "USD", value: "5.00" },
+ selected: true,
+ },
+ {
+ id: "drone",
+ label: "🚀 Drone Express (2 hours)",
+ amount: { currency: "USD", value: "25.00" }
+ },
+ ];
+ Object.assign(details, { shippingOptions });
+
+ + Here we see how to add a processing fee for using a credit card. + Notice that it requires recalculating the total. +
+
+ // Credit card incurs a $3.00 processing fee.
+ const creditCardFee = {
+ label: "Credit card processing fee",
+ amount: { currency: "USD", value: "3.00" },
+ };
+
+ // Modifiers apply when the user chooses to pay with
+ // a credit card.
+ const modifiers = [
+ {
+ additionalDisplayItems: [creditCardFee],
+ supportedMethods: "basic-card",
+ total: {
+ label: "Total due",
+ amount: { currency: "USD", value: "68.00" },
+ },
+ data: {
+ supportedTypes: "credit",
+ },
+ },
+ ];
+ Object.assign(details, { modifiers });
+
+ options argument
+ + The options dictionary contains information the developer + needs from the user to perform the payment (e.g., the payer's name + and shipping address). +
+
+ const options = {
+ requestPayerEmail: false,
+ requestPayerName: true,
+ requestPayerPhone: false,
+ requestShipping: true,
+ }
+
+ PaymentRequest
+ + Having gathered all the prerequisite bits of information, we can now + construct a PaymentRequest and request that the browser + present it to the user: +
+
+ async function doPaymentRequest() {
+ try {
+ const request = new PaymentRequest(methodData, details, options);
+ // See below for a detailed example of handling these events
+ request.onshippingaddresschange = ev => ev.updateWith(details);
+ request.onshippingoptionchange = ev => ev.updateWith(details);
+ const response = await request.show();
+ await validateResponse(response);
+ } catch (err) {
+ // AbortError, SecurityError
+ console.error(err);
+ }
+ }
+ async function validateResponse(response) {
+ try {
+ if (await checkAllValuesAreGood(response)) {
+ await response.complete("success");
+ } else {
+ await response.complete("fail");
+ }
+ } catch (err) {
+ // Something went wrong...
+ response.complete("unknown");
+ }
+ }
+ doPaymentRequest();
+
+ + Prior to the user accepting to make payment, the site is given an + opportunity to update the payment request in response to user input. + This can include, for example, providing additional shipping options + (or modifying their cost), removing items that cannot ship to a + particular address, etc. +
+
+ const request = new PaymentRequest(methodData, details, options);
+ request.onshippingaddresschange = async ev => {
+ // Can we ship here?
+ try {
+ const json = request.shippingAddress.toJSON();
+ const { shippingOptions, total } = await calculateShipping(json);
+ const newDetails = {...details, ...{ shippingOptions, total }};
+ ev.updateWith(newDetails);
+ } catch (err) {
+ ev.updateWith({ error: `Sorry! we can't ship to your address.` });
+ }
+ };
+ // update the total
+ request.onshippingoptionchange = ev => {
+ const shippingOption = shippingOptions.find(
+ option => option.id === request.id
+ );
+ const newTotal = {
+ currency: "USD",
+ value: calculateNewTotal(shippingOption),
+ label: "Total due",
+ };
+ ev.udpateWith({ ...details, total: newTotal });
+ };
+
+ - The following example shows how to construct a PaymentRequest - and begin the user interaction: -
-
- function validateResponse(response) {
- // check that the response is ok... throw if bad, for example.
- }
-
- async function doPaymentRequest() {
- const payment = new PaymentRequest(methodData, details, options);
- payment.addEventListener("shippingaddresschange", event => {
- // Process shipping address change
- });
- let paymentResponse;
- try {
- paymentResponse = await payment.show();
- // paymentResponse.methodName contains the selected payment method.
- // paymentResponse.details contains a payment method specific
- // response.
- validateResponse(paymentResponse);
- paymentResponse.complete("success");
- } catch (err) {
- console.error("Uh oh, bad payment response!", err.message);
- paymentResponse.complete("fail");
- }
- }
- doPaymentRequest();
-
- The methodData sequence contains - PaymentMethodData dictionaries containing the payment - method identifiers for the payment methods that the web - site accepts and any associated payment method specific - data. -
-
- const methodData = [{
- supportedMethods: "basic-card",
- data: {
- supportedNetworks: ['visa', 'mastercard'],
- supportedTypes: ['debit']
- }
- }, {
- supportedMethods: "https://example.com/bobpay",
- data: {
- merchantIdentifier: "XXXX",
- bobPaySpecificField: true
- }
- }];
- const request = new PaymentRequest(methodData, details, options);
-
- - The details object contains information about the - transaction that the user is being asked to complete such as the - line items in an order. -
-
- const details = {
- id: "super-store-order-123-12312",
- displayItems: [{
- label: "Sub-total",
- amount: { currency: "USD", value: "55.00" }, // US$55.00
- }, {
- label: "Sales Tax",
- amount: { currency: "USD", value: "5.00" }, // US$5.00
- }],
- total: {
- label: "Total due",
- amount: { currency: "USD", value: "60.00" }, // US$60.00
- }
- }
- const request = new PaymentRequest(methodData, details, options);
-
- - The options object contains information the developer - needs from the user to perform the payment (e.g., the payer's name - and shipping address). -
-
- const options = {
- requestShipping: true
- }
- const request = new PaymentRequest(methodData, details, options);
-
- The PaymentRequest(methodData, details, options) constructor MUST act as follows: