Payment request api apple pay

Introducing the Payment Request API for Apple Pay

We’re pleased to announce that Safari 11.1 on macOS and Safari on iOS 11.3 now support the W3C Payment Request API for conducting Apple Pay transactions on the web.

We first introduced Apple Pay on the Web in macOS Sierra and iOS 10. Apple Pay brought novel ease-of-use, security, and privacy to online transactions, so we’ve been encouraged to see it widely adopted by merchants in the years since. However, we recognize that merchants need to support multiple payment methods, and doing so comes at the cost of increased complexity. Payment Request aims to reduce this complexity by supporting payment methods across multiple browsers using a standard API.

Today I’ll take you step-by-step through an Apple Pay transaction using Payment Request. If you’ve already worked with Apple Pay JS, this should look familiar to you. If you haven’t, this is a great place to get started!

Prerequisites

This post assumes that you have already registered a merchant identifier and set up your server environment to process Apple Pay transactions. You can find detailed instructions for doing this in the Apple Pay on the Web documentation.

Showing Apple Pay Buttons

Apple Pay transactions are always initiated by your customer, so you’ll need to display an Apple Pay button for them to tap or click. For a consistent visual appearance, WebKit provides built-in support for rendering Apple Pay buttons. Here’s how to display the most basic type of Apple Pay button:

There are several other types of buttons available in various styles. Here’s a few that you might have seen while shopping in Safari:

See Displaying Apple Pay Buttons for more information on the button types and styles available.

According to the Apple Pay on the Web Human Interface Guidelines, you should display Apple Pay buttons whenever your customer is using a supported device. To check if your customer’s device supports Apple Pay, call ApplePaySession.canMakePayments() :

If your customer taps or clicks an Apple Pay button, you should always present the Apple Pay payment sheet. If they haven’t yet enrolled a payment card you can accept in Apple Pay, Safari prompts them to do so before continuing with your transaction. Since these rules are specific to Apple Pay, Apple Pay JS’s ApplePaySession API is required for this step. The remainder of the transaction can be conducted using standard Payment Request API.

Constructing a PaymentRequest

When your customer taps or clicks an Apple Pay button, you initiate the transaction by constructing a new PaymentRequest :

The PaymentRequest constructor takes three arguments: the payment methods you support, the details to show to your customer (like shipping options and total amount), and any options you require.

Payment Methods

Payment methods represent the means by which you can accept payments from your customer using Payment Request. You specify the payment methods you accept as a sequence of PaymentMethodData dictionaries, each of which contains an identifier ( supportedMethods ) and associated data .

To use Apple Pay with Payment Request, include it as a payment method. Apple Pay’s URL-based payment method identifier is «https://apple.com/apple-pay» , and its associated data is an ApplePayRequest dictionary. Here’s what a PaymentMethodData dictionary for Apple Pay might look like:

Safari only supports the Apple Pay payment method, but other browsers might support additional payment methods. When you specify multiple payment methods in a request, the browser decides which to present to your customer based on device availability and user preference.

Payment Details

Payment details are represented by the PaymentDetailsInit dictionary. It contains your transaction’s total amount, display items, shipping options, and payment method-specific modifiers (more on modifiers below). Here’s what valid payment details might look like for a $20 item plus tax and two shipping options:

You can choose a default shipping option by setting the selected attribute to true as we did above for «Ground Shipping» . The total amount must not be negative, and when using Apple Pay, all payment amounts in your request must use the same ISO 4217 currency code. It is up to you to ensure the correctness of your payment details; Safari does not do any currency calculations on your behalf.

What about modifiers?

You can optionally include a sequence of modifiers in your payment details. Modifiers update your transaction’s display items and total when criteria you specify for a given payment method are satisfied. In Apple Pay, you can use modifiers to adjust the price based on the type of payment card selected in the Apple Pay payment sheet. For instance, the following modifier applies a $1.00 discount when your customer selects a debit card in Apple Pay:

Modifiers provide some of the functionality present in the paymentmethodselected event from Apple Pay JS. See ApplePayModifier for more information.

Payment Options

Payment options are represented by the PaymentOptions dictionary. If you need to request your customer’s name, email address, or phone number – or request a certain type of shipping – you can do so here:

If you set requestShipping to true , the shipping options you specified in Payment Details are presented in the payment sheet for your customer to choose between. You receive the requested information once your customer authorizes payment.

Exceptions

Safari might raise an exception when constructing a new PaymentRequest . Exceptions can occur for the following reasons:

• The frame is not in a secure context.
• The frame is a cross-origin subframe.
• No payment methods were specified.
• A payment method identifier is invalid.
• Calling JSON.stringify() on the payment method data failed.
• Invalid currency amounts were specified (e.g., negative total or multiple currencies).

canMakePayment() method

Once you’ve constructed a PaymentRequest , you can ask it if your customer will be able to authorize a transaction given the payment methods you can accept. You do this by calling the canMakePayment() method, which returns a promise that resolves to either true or false . In Safari, when Apple Pay is one of the payment methods, canMakePayment() resolves to true only if your customer has an active card enrolled in Apple Pay. This is the equivalent of how ApplePaySession.canMakePaymentsWithActiveCard() behaves in Apple Pay JS.

As we discussed in Showing Apple Pay Buttons, the Apple Pay Human Interface Guidelines require you to show an Apple Pay button whenever your customer is on supported hardware, whether or not they have an active card enrolled. Therefore, you should not hide Apple Pay buttons when canMakePayment() resolves to false . Always show an Apple Pay button if ApplePaySession.canMakePayments() returns true , and always present the Apple Pay payment sheet when your customer taps or clicks the button. Safari prompts your customer to enroll a payment card if they haven’t done so already before continuing with your transaction. For more information, see Human Interface Guidelines > Apple Pay on the Web.

show() method

When your customer taps or clicks an Apple Pay button, you should present the Apple Pay payment sheet. You do this by calling the show() method, which returns a promise that resolves to a PaymentResponse once your customer authorizes payment. The promise is rejected with an AbortError if your customer cancels the transaction.

You can optionally call show() with a promise for a PaymentDetailsUpdate . Sometimes you might still be in the process of calculating payment details when your customer taps or clicks the Apple Pay button. In this case, you can construct a new PaymentRequest with placeholders for details, then call show() with a promise to provide up-to-date details later. When you resolve this promise, Safari displays the updated details in the Apple Pay payment sheet.

Safari might reject the promise returned by show() with an exception. Exceptions can occur for the following reasons:

• show() was not triggered by user activation (e.g., a tap or click).
• The request has already been aborted.
• An Apple Pay session is already active.
• Payment method data is invalid (e.g., is missing required fields).

abort() method

If you need to abort the presented transaction, you can call the abort() method. When you do this, Safari dismisses the Apple Pay payment sheet and rejects the promise returned by show() with an AbortError . If the transaction has already been aborted, or show() has not yet been called, calling abort() throws an InvalidStateError .

Merchant Validation

Before Safari can present the Apple Pay payment sheet, you must acquire a payment session from Apple. This process is referred to as merchant validation.

Soon after you call show() , Safari dispatches the merchantvalidation event to your PaymentRequest object. The event defines a validationURL attribute representing the Apple URL your server contacts to receive a payment session. You must call the event’s complete() method with a promise that you resolve with this payment session once you receive it.

Here is what a merchantvalidation event handler might look like:

You can learn more about merchant validation from Requesting an Apple Pay Payment Session.

Shipping Events

Once you’ve received a merchant session, Safari presents the Apple Pay payment sheet to your customer. If you’ve requested shipping, your customer is able to select between your shipping options and provide a shipping address. When they make these selections in the payment sheet, Safari dispatches a shippingoptionchange or shippingaddresschange event to your PaymentRequest object.

shippingoptionchange

When the user selects a shipping option, Safari dispatches the shippingoptionchange event. In your event handler, you can determine the selected shipping option by checking the PaymentRequest ‘s shippingOption attribute. To update the payment details based on the selected shipping option, call updateWith() on the event object with a promise that resolves to a PaymentDetailsUpdate .

When requesting shipping with Apple Pay, you must always listen for shippingoptionchange and call updateWith() with a promise that resolves within 30 seconds, otherwise, the transaction will time out.

shippingaddresschange

When your customer selects a shipping address, Safari dispatches the shippingaddresschange event. In your event handler, you can determine the selected shipping address by checking the PaymentRequest ‘s shippingAddress attribute. To update the payment details based on the selected shipping address, call updateWith() on the event object with a promise that resolves to a PaymentDetailsUpdate . If you are unable to ship to the selected address, you can provide an error message in your PaymentDetailsUpdate that Safari displays to your customer.

When using Apple Pay, Safari might redact some details from the shipping address. For instance, in the United States, only city, state, 5-digit ZIP code, and country are provided. Safari provides the full, un-redacted shipping address once your customer authorizes payment.

When requesting shipping with Apple Pay, you must always listen for shippingaddresschange and call updateWith() with a promise that resolves within 30 seconds, otherwise the transaction will time out.

Handling Payment Authorization

When your customer authorizes payment, Safari resolves the promise you received from calling show() with a PaymentResponse . Depending on what you requested in your PaymentOptions , the response might contain the selected shipping option, shipping address, name, email, and phone number of your customer.

The response also contains the payment method identifier used to conduct the transaction ( methodName ), along with its associated details . When Apple Pay is the selected payment method, the associated details is an ApplePayPayment dictionary. ApplePayPayment contains the Apple Pay token you use to process the payment authorization. It also includes your customer’s billing and shipping contact information as ApplePayPaymentContact s if you required this in your ApplePayRequest .

When you have finished processing the payment authorization, you call the complete() method on PaymentResponse to indicate the result of your processing. You can call complete() with a status of «success» or «failure» . At this point, the Apple Pay payment sheet is dismissed.

You now have all the pieces you need to conduct an Apple Pay transaction using Payment Request. Here’s what an Apple Pay session might look like using Payment Request:

Let’s see how this works in a live demo. If you are viewing this post on a device capable of Apple Pay, you should see an Apple Pay button below. Feel free to click it! Don’t worry, no matter what you do in the payment sheet, your card won’t be charged anything.

Availability

The Payment Request API is available in Safari 11.1 on macOS Sierra and macOS High Sierra, Safari on iOS 11.3, and Safari Technology Preview.

More Information

Apple provides comprehensive documentation for Apple Pay on the Web. Here are a few links you might find useful:

Источник

Apple Pay on the Web
Interactive Demo

Try an Apple Pay test transaction using the button below.
Transactions made on this site do not charge your card.

Overview

Use this page to learn how to enable Apple Pay on the web using Apple Pay JS or the Payment Request API. This demo preconfigures the Apple Pay button below with default values. Explore further by modifying values in the code blocks throughout the page to customize payment sheet experiences. This demo displays a transcript of server responses after each transaction for context. Click or tap the the «Show Transcript» tab to view the transaction transcript.

As well as letting you try out the Apple Pay JavaScript APIs, this demo can also serve as a tutorial for your own implementation. It assumes you have already set up your environment to process Apple Pay transactions, and are familiar with Apple Pay best practices. Before starting your integration, we recommend reviewing Getting Started with Apple Pay and the Apple Pay on the Web Human Interface Guidelines. For more information about supporting Apple Pay on your website, see Apple Pay on the Web.

This demo generates source code that you can copy into your own project. Click or tap the the «Show Source» tab to view the source code. The demo updates the source code as you change values in the code blocks through the page. Once you are happy with the configuration, click or tap the «Copy» button inside the «Show Source» tab to copy the source code to your clipboard.

Requirements

This demo uses Apple Pay JS version 3, and to run this demo you must be using:

• iOS devices running iOS 11 or later
• Safari 11 on macOS 10.13 or later

Display an Apple Pay button

To display an Apple Pay Button, use the following code to load the button script into your webpage from the content delivery network:

The JavaScript Apple Pay button provides a variety of Apple Pay button types that you can use on your website to initiate a transaction. You can specify the Apple Pay button style, type, and localization using attributes. Use CSS to set other properties, such as the size and corner radius. Using the official Apple Pay button element ensures your site will display the latest style, render correctly across devices, and follow Apple Guidelines. For design guidance, see Human Interface Guidelines > Apple Pay > Buttons and Marks.

Try it: Display Settings

Use the following tools to try the different display settings on the button shown below:

Button Corner Radius

Corner Radius: 3px

Button Padding Y

Button Padding Y: 0px

Button Padding X

Button Padding X: 0px

Button Box Sizing

Create a Payment Request

When your customer clicks or taps the Apple Pay button, you must first construct an ApplePaySession object which includes the ApplePayPaymentRequest dictionary detailing the transaction details the payment sheet will display.

The ApplePayPaymentRequest requires details including: the total payment for the transaction, the currency, and the supported payment networks. You can optionally pass lineItems to show additional charges and discounts, and shippingMethods to allow the customer to choose from different shipping options. If you require address or contact details from your customer, request them by passing values in the requiredShippingContactFields or requiredBillingContactFields .

Try it: ApplePayPaymentRequest

Modify the values in the ApplePayPaymentRequest shown below and click or tap the Apple Pay button to view the payment sheet. Choose Basic Request to see a payment sheet with only the required fields. Choose Detailed Request to show code including optional fields, such as lineItems.

Complete Merchant Validation

Before being able to display the payment sheet to the customer, you must generate a valid payment session by interacting with Apple Pay Servers. For security reasons, your server must do this, not your browser client code, unlike everything else in this demo. To start the merchant validation process, call the begin method on the session object you created above.

Once you do, the browser will invoke your onvalidatemerchant handler, which must fetch a merchant session from your server.

Refer to the instructions in Requesting an Apple Pay Payment Session document to implement your server endpoint responsible for fetching the merchant session object from Apple Pay servers. If successful, Apple Pay servers will return a merchant session object, which your server must then pass back as the response to the browser.

Once you have the merchant session response object in the browser, you must complete your onvalidatemerchant handler by passing that object to the completeMerchantValidation method on the session object. The browser will then display the payment sheet.

The following code shows an example of how to validate merchant:

Respond to Payment Sheet Interactions

After merchant validation is complete, Apple Pay provides the information about your customer’s payment sheet selections so that you can calculate the final transaction cost. The final details of a transaction may depend on user payment method, billing address, shipping address, or shipping method. To handle these adjustments, implement the optional handlers onpaymentmethodselected , onshippingmethodselected , and onshippingcontactselected . When the browser calls one of these handlers, you have 30 seconds to process it and call the corresponding callback function, otherwise the transaction times out. All callbacks accept an object with newTotal (required) and newLineItems (optional) keys. In addition, you may specify newShippingMethods to update shipping methods, and errors to indicate problems with the user’s selected shipping address when calling completeShippingContactSelection . You may also call the callbacks with an empty object or null value if the payment sheet needs no changes.

Event Handlers	Callback Function	Update Structure	Update Properties
onpaymentmethodselected	completePaymentMethodSelection	ApplePayPaymentMethodUpdate	newTotal (required) newLineItems (optional)
onshippingmethodselected	completeShippingMethodSelection	ApplePayShippingMethodUpdate	newTotal (required) newLineItems (optional)
onshippingcontactselected	completeShippingContactSelection	ApplePayShippingContactUpdate	newTotal (required) newLineItems (optional) newShippingMethods (optional) errors (optional)

Demo Note: The test transaction always passes in a default success response when it calls completePaymentMethodSelection . The test transaction passes in newLineItems and newTotal when it calls completeShippingMethodSelection . See responses in the transcript.

Request a Shipping Address

If you pass requiredShippingContactFields in the payment request with a postalAddress value, Apple Pay provides redacted address information before the user authenticates the transaction. After the user authenticates, Apple Pay provides the full contact information.

The redacted payment information includes only the data needed to complete required transaction tasks, such as calculating taxes or shipping costs, and may differ based on the user’s geographic region.

The following code shows an example of a redacted payment information:

Try it: completeShippingContactSelection

Choose ‘Success’ with or without updating line items and total below. Choose ‘Failure’ to see completeShippingContactSelection response with custom errors. You may edit the ApplePayShippingContactUpdate response object below to experiment with different responses. Click or tap the Apple Pay button below to see how the payment sheet displays updates or address errors.

Источник