Framework

Apple Pay JS

Use JavaScript to incorporate Apple Pay into your websites.

Overview

The Apple Pay JavaScript API lets you accept Apple Pay payments on the web. The Apple Pay JavaScript API is supported on the following platforms:

  • iOS 10. Apple Pay JavaScript is supported on all iOS devices with a Secure Element. It is supported both in Safari and in SFSafariViewController objects.

  • macOS 10.12. Apple Pay JavaScript is supported in Safari. The user must have an iPhone, Apple Watch, or a MacBook Pro with Touch ID that can authorize the payment.

Apple Pay is available in supported regions.

The Apple Pay JavaScript API is analogous to the PassKit framework for using Apple Pay in apps. If you have used the PassKit API, then the Apple Pay JavaScript API should feel familiar to you.

Sample code is available here: EmporiumWeb: Request and handle Apple Pay payments on the web.

Apple Pay Requirements

There are three requirements for using Apple Pay on your website:

  • You must have an Apple Developer Account.

  • All pages that incorporate Apple Pay must be served over HTTPS.

  • Your website must comply with the Apple Pay guidelines. For more information, see Apple Pay on the Web Acceptable Use Guidelines.

Server Requirements

To incorporate Apple Pay on your website, your server must have the following setup:

  • All pages that include Apple Pay must be served over HTTPS.

  • Your domain must have a valid SSL certificate.

  • Your server must support the Transport Layer Security (TLS) 1.2 protocol and one of the cipher suites listed in Table 1.

  • To enable merchant validation, your server must allow access over HTTPS (TCP over port 443) to the Apple Pay IP addresses provided in Listing 1 below.

Listing 1

Apple Pay IP addresses and domain names for merchant validation in production, and in testing

For production environment:
17.171.78.7      apple-pay-gateway-nc-pod1.apple.com
17.171.78.71     apple-pay-gateway-nc-pod2.apple.com
17.171.78.135    apple-pay-gateway-nc-pod3.apple.com
17.171.78.199    apple-pay-gateway-nc-pod4.apple.com
17.171.79.12     apple-pay-gateway-nc-pod5.apple.com
17.141.128.7     apple-pay-gateway-pr-pod1.apple.com
17.141.128.71    apple-pay-gateway-pr-pod2.apple.com
17.141.128.135   apple-pay-gateway-pr-pod3.apple.com
17.141.128.199   apple-pay-gateway-pr-pod4.apple.com
17.141.129.12    apple-pay-gateway-pr-pod5.apple.com
17.171.78.9      apple-pay-gateway-nc-pod1-dr.apple.com
17.171.78.73     apple-pay-gateway-nc-pod2-dr.apple.com
17.171.78.137    apple-pay-gateway-nc-pod3-dr.apple.com
17.171.78.201    apple-pay-gateway-nc-pod4-dr.apple.com
17.171.79.13     apple-pay-gateway-nc-pod5-dr.apple.com
17.141.128.9     apple-pay-gateway-pr-pod1-dr.apple.com
17.141.128.73    apple-pay-gateway-pr-pod2-dr.apple.com
17.141.128.137   apple-pay-gateway-pr-pod3-dr.apple.com
17.141.128.201   apple-pay-gateway-pr-pod4-dr.apple.com
17.141.129.13    apple-pay-gateway-pr-pod5-dr.apple.com
For sandbox testing only:
17.171.85.7      apple-pay-gateway-cert.apple.com

Configuring Your Environment

Similar to Apple Pay in apps, you must register a merchant identifier and set up cryptographic keys. However, iOS has digitally signed entitlements in the app binary that add an additional layer of security. These entitlements help validate and verify both the user and the merchant.

To provide a similar layer of security on the web, there are a few additional steps required to configure your environment and to validate payment requests.

To accept Apple Pay on the web, you need the following three pieces of information:

  • Merchant ID. A unique identifier that represents a merchant for Apple Pay.

    The same merchant ID can be used for Apple Pay payments both in-app and on the web. For information on creating your merchant ID, see Configuring Your Environment in Apple Pay Programming Guide.

  • Payment Processing Certificate. A certificate used to securely transfer payment data. Apple Pay servers use the payment processing certificate’s public key to encrypt the payment data. Use the private key to decrypt the data when processing payments.

    The same payment processing certificate can be used for Apple Pay payments both in-app and on the web. For information on creating your Payment Processing Certificate, see Configuring Your Environment in Apple Pay Programming Guide.

  • Merchant Identity Certificate. A Transport Layer Security (TLS) certificate used to authenticate your merchant sessions with the Apple Pay servers. The merchant identity certificate is only required for Apple Pay on the web.

To register and verify your domain, and create your Merchant Identity Certificate:

  1. In Member Center, select Certificates, Identifiers, and Profiles.

  2. Under Identifiers, select Merchant IDs.

  3. Select the merchant ID from the list, and click Edit.

  4. In the Apple Pay on the Web section, click the Add Domain button.

  5. Enter your fully qualified domain name, and click Continue.

  6. The site creates a file and makes it available to download. Download this file and host it at the provided location.

    Your server must support the TLS 1.2 protocol and one of the cipher suites listed in Table 1.

    Table 1

    Supported cipher suites

    Ciphersuite Value

    Description

    0xC02F

    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

    0xC027

    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

    0xC013

    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

    0x009E

    TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

    0x0067

    TLS_DHE_RSA_WITH_AES_128_CBC_SHA256

    0x009C

    TLS_RSA_WITH_AES_128_GCM_SHA256

    0x003C

    TLS_RSA_WITH_AES_128_CBC_SHA256

  7. As soon as the file is available on your server, click the Verify button. If the verification succeeds, the site returns to the iOS Merchant ID Settings page and shows a green Verified status label.

  8. In the Apple Pay on the Web section, click the Create Certificate button. Follow the instructions to create and download your Merchant Identity Certificate. Use this certificate when requesting a merchant session during payment validation. For more information, see Merchant Validation in ApplePaySession.

Maintaining Your Environment

To continue using Apple Pay for the web, your domain verification and the certificates that you set up in the Configuring Your Environment section must remain valid.

You can view the certificate expiration dates on the Certificates, Identifiers, and Profiles page in your account on the Apple developer website. Under Identifiers, select Merchant IDs. Then select your domain's merchant ID and select Edit. Certificate expiration dates appear for each of the certificates listed on the page. You can also update the certificates on this page.

Renew certificates before they expire to avoid interruptions in your Apple Pay service.

Renewing Domain Verification

Your domain verification expires when its SSL certificate expires.

Apple sends an email reminder to the team agent of your Apple developer account before your SSL certificate expires. Follow the instructions in the email to:

  1. Update the domain's SSL certificate

  2. Reverify the domain.

If your domain verification expires, the domain reverts to a "pending" status in your Apple developer account. Calls to Start Session fail and your website cannot use Apple Pay until the domain is reverified.

You can continue to use your existing Merchant Identity Certificate after the domain has been reverified.

Symbols

Creating an Apple Pay Session

ApplePaySession

A session object for managing the payment process on the web.

Working with Events

ApplePayPaymentAuthorizedEvent

The ApplePayPaymentAuthorizedEvent class defines the attributes contained by the onpaymentauthorized callback function.

ApplePayPaymentMethodSelectedEvent

The ApplePayPaymentMethodSelectedEvent class defines the attributes contained by the onpaymentmethodselected callback function.

ApplePayShippingContactSelectedEvent

The ApplePayShippingContactSelectedEvent class defines the attributes contained by the onshippingcontactselected callback function.

ApplePayShippingMethodSelectedEvent

The ApplePayShippingMethodSelectedEvent class defines the attribute contained by the onshippingmethodselected callback function.

ApplePayValidateMerchantEvent

The ApplePayValidateMerchantEvent class defines the attributes contained by the onvalidatemerchant callback function.

Data Types

ApplePay JS Data Types

Lists the dictionaries used in Apple Pay JS that are not described elsewhere.