Create Digital Wallet Payment Requests

Applies to: Web Payments SDK

Learn how to create a digital wallet payment request using the Web Payments SDK.

Link to section

Overview

You can create a digital wallet payment request, handle payment request events, and update the payment request after the buyer makes changes to the shipping address or shipping options.

If your application recalculates fees, taxes, and charges based on the buyer shipping location chosen in the Google Pay, Apple Pay, or Afterpay payment sheet, use the PaymentRequest endpoint to set the initial shipping options and shipping charges in the payment sheet and react to the buyer's shipping-related choices.

The PaymentRequestUpdate object has properties that correspond to PaymentRequestOptions properties that are set when you create the payment request. When the callback update parameter is invoked, the PaymentRequestUpdate properties replace the property values in the initial request.

Link to section

Requirements and limitations

The following steps add code to the application you created from the quickstart project sample. If you haven't created an application from using the quickstart project sample or from completing the tasks in Web Payments SDK Quickstart, you need to do so before completing these steps. You should also have completed the Apple Pay, Google Pay, or Afterpay example before continuing.

You can find a complete example of the PaymentRequest code on GitHub.

Note

A payment request update (PaymentRequest.update) can only succeed when the expected Apple Pay, Google Pay, or Afterpay payment sheet isn't open. Otherwise, the update method fails and returns a false value.

Link to section

Shipping addresses

Your application doesn't need to gather shipping address information from the buyer who pays with a digital wallet. Google Pay and Apple Pay collect and store shipping addresses for the buyer and return the buyer's preferred shipping address to your application in the shippingcontactchanged event. This event provides a contact parameter of the ShippingContact type. Be sure to set requestShippingContact: true in the payment request so that the buyer is prompted to choose a shipping address.

Link to section

Shipping options

Shipping options let buyers choose a shipping method and cost. These options must be provided by your application with each payment request because the digital wallet providers don't store a seller's shipping options.

It might also be necessary to give a buyer a different set of shipping options after the buyer changes the shipping address on the digital wallet page. In this case, your application updates the ShippingOption array with new shipping choices. When the buyer selects a different shipping option, your application handles another event to update a LineItem to show the updated line item and total amount paid.

The shippingoptionchanged event provides an option parameter of the ShippingOption type. Use this parameter to get the shipping option selected by the buyer.

Link to section

Payment request events

The PaymentRequest object exposes the addEventListener function so you can provide your own callback logic to be invoked by the digital wallet on the following actions:

  • The digital wallet page is loaded.
  • The buyer selects a shipping address.
  • The buyer selects a shipping option.

Any of these actions might require your application to recalculate the fees, shipping charges, or shipping options shown on the digital wallet payment page. If a buyer selects a shipping address to a location where you have no shipping, your application should react by updating the payment page with an error message and removing any initial options offered.

These are the typical events that your application should handle:

  • The buyer changes the shipping address to a location with different shipping fees. The shippingcontactchanged event is fired. Your application recalculates the shipping fees for each shipping option offered and updates the payment request.
  • The buyer selects one of the updated shipping options. The shippingoptionchanged event is fired. Your application updates the shipping fee line item in the payment request.

Depending on the payment method, the shipping address information might be redacted — for example, Apple Pay's shipping information includes only the necessary data for completing transaction tasks, such as calculating taxes or shipping costs — and shouldn't be considered complete. The TokenResult object contains the full shipping address.

Important

When updating a line item in the payment request, be sure to provide the complete set of LineItem objects (including the updated line item). Otherwise, the initial set of line items is replaced by the single line item that your application updated.

Link to section

1. Create a payment request

A new PaymentRequest is created by providing a PaymentRequestOptions object to the payments.paymentRequest function as an argument.

This example creates a PaymentRequest with the following details:

  • The payment is in the United States and in USD.
  • The payment consists of a purchase of $2, shipping charges of $0, and taxes of $.00 (taxes are updated in the following step and when the shipping address is selected).
  • The digital wallet page shows billing and shipping addresses for the buyer.
  • There are two shipping options: free and expedited. Each option is shown with a cost to the buyer.
  • The total purchase amount is the sum of the purchase amount + .00 tax + free shipping.

Create a payment request

  1. Replace the current buildPaymentRequest function code with the following code:

  2. Add the following helper function to calculate the total payment:

    function calculateTotal(lineItems) { const amount = lineItems .reduce((total, lineItem) => { return total + parseFloat(lineItem.amount); }, 0.0) .toFixed(2); return { amount, label: 'Total' }; }

The PaymentRequest created by the example sets the details that are shown when the digital wallet payment page is opened for the buyer. The digital wallet sheet doesn't recalculate shipping charges or the total amount based on buyer actions, such as updating the shipping address or selecting a shipping option. You implement the ability to recalculate amounts and update the payment page in the next steps.

Test the application

  1. Open a browser to http://localhost:3000 to verify that the server is running.

  2. Choose a digital wallet button, such as the Google Pay button.

    Your web page looks like the following page:

    An animation showing the Google Pay payment method being clicked to open the Google Pay sheet and being used to pay $1.00.

    Success

    If the digital wallet page shows line amounts, shipping and billing addresses, and a total payment amount, you're ready to write the code that reacts to payment request events.

If you change the shipping option to Expedited in the user interface, the line items and total don't change at this point.

Link to section

2. Add a shipping option changed event listener

The buyer might select the non-default shipping option, which requires your application to recalculate the total payment based on the newly selected shipping option.

Did you know?

You should get the selected shipping option from this event when it's invoked when loading the payment form. The buyer might accept the default shipping option and close the form without selecting a different option. In this case, the shippingoptionchanged event is only invoked once, when the form is loaded.

The following example updates the shipping line item with the amount of the selected option and recalculates the total amount. The selected shipping option is provided as the option parameter in the callback signature.

  1. Add a shippingoptionchanged event listener to your PaymentRequest in the buildPaymentRequest function at checkpoint 2.

  2. Add the updateOrAddLineItems helper function to the script tag. This function updates the amounts for changed line items (in this case Shipping) or adds the line item to the list if it doesn't exist.

Test the application

  1. Open a browser to http://localhost:3000 to verify that the server is running.

  2. Choose the digital wallet button to open the digital wallet payment.

  3. Choose the second shipping option.

    Your web page looks like the following page:

    An animation showing the Google Pay payment method being clicked to open the Google Pay sheet, the buyer selecting a different shipping option, the total purchase amount being updated, and $2.20 being paid.

    Success

    When selecting the second shipping option on the digital wallets page, the total should update to include that cost. For digital wallets that show line items, you should also see an updated shipping amount.

Link to section

3. Add a shipping contact changed event listener

If your application initiates shipping a product to the buyer, you should handle the shippingcontactchanged event. This event provides a contact parameter of the ShippingContact type that includes any relevant contact information, including the shipping address.

Did you know?

You should get the shipping address from this event when it's invoked when loading the payment form. The buyer might accept the default shipping address and close the form without selecting a different address. In this case, the shippingcontactchanged event is only invoked once, when the form is loaded.

Your application might have different shipping options and charges based on the buyer's shipping address. If the buyer changes the address, your application reacts by recalculating charges or offering different shipping options.

This example changes the shipping charges for the two shipping options depending on what state is being shipped to. If the state is California, free shipping is offered. In California, express shipping has a lower charge. Elsewhere, the fees are higher. The tax is calculated based on what state the buyer lives in.

The example calculates the new shipping option charges and calculates a new total payment amount.

  1. Add a shippingcontactchanged event listener to your PaymentRequest in the buildPaymentRequest function at checkpoint 3.

  2. Add the following helper method to calculate a new tax amount:

The total payment amount shown is based on a default choice of the first shipping option.

Test the application

  1. Open a browser to http://localhost:3000 to verify that the server is running.

  2. Choose the digital wallet button to open the digital wallet payment.

  3. Change the shipping address to any non-California address or the following address.

    Your web page looks like the following page:

    An animation showing a Google Pay transaction, with Expedited Shipping and a new address being selected.

    Success

    If the digital wallet page is updated, the shipping amount of the select option changes to the higher amount for a non-California shipping address.

Link to section

See also