Apple Pay Drop-in integration

This page explains how to add Apple Pay to your existing Web Drop-in integration.

Requirements

Select which endpoint you are using:

Offering Apple Pay on web

When offering the option to pay with Apple Pay on web, there are additional things to consider if you use iframe elements. If you want to show Apple Pay on browser other than Safari, see compatibility to learn which devices and operating systems support this feature.

Apple Pay with iFrames

To show Apple Pay in an iframe element when the shopper is using Safari as their browser:

• For shoppers on Safari 17 later: add the allow attribute to the iframe to let the iframe communicate correctly with Apple Pay APIs:

  <iframe allow="payment">
  </iframe>

  Safari 17 is available on iOS 17 and later, and macOS 12 and later.

• For shoppers on Safari 16 or earlier: match the iframe origin and your top-level origin. The protocols, hosts (full domain name), and ports, when specified, must be the same for both pages.

Device compatibility

On v6.10.0 and later versions of Drop-in, you can offer Apple Pay on all supported third-party browsers, platforms, and devices, including Windows and Chromebooks. Shoppers can now initiate Apple Pay payments from any compatible device and complete their payment by scanning a code. See Devices compatible with Apple Pay on Apple Pay documentation.

On earlier versions of Drop-in , the support for Apple Pay on third-party browsers differ per shopper device:

• MacOS devices: available on Safari.
• iOS and iPadOS devices: available on all browsers, including web views.
• Non-Apple devices: not available.

API reference

You do not need to send additional fields for Apple Pay. To see optional fields that you can send for all payment methods, choose the endpoint you integrated:

• /sessions: This is the default with Drop-in v5.0.0 or later.
• /payments: If you implemented an additional use case.

If you run into an error, refer to Handle Apple Pay errors.

Drop-in configuration

Select which endpoint you are using:

Optional configuration

This optional configuration parameter is only accepted on the dropin instance.

Instant payment button configuration

Use the instantPaymentTypes object to display the Apple Pay payment button at the top of the list of available payment methods. The sample below shows how to do this:

Optional Apple Pay configuration

You can do the following:

• Configure the appearance of the Apple Pay button.
• Include additional data such as transaction information, fields for billing and shipping contact information.
• Configure how to render Apple Pay code.
• Add logic for specific events on your payment form.

Button configuration

Payment request data

Code rendering configuration

Events

The following event handlers are supported for Apple Pay. Select the event handler names to see the related Apple Pay documentation.

Optional Apple Pay Wallet Order Tracking

Supported in v6.0.0 or later.

You can use Apple Pay Wallet Order Tracking to give your shopper order tracking through Apple Pay. For more information, refer to the following resources from Apple:

• Apple Pay Wallet Order Tracking Demo
• Apple Pay Tech Talk about implementing Apple Pay with order management
• Example Order Packages

1. Implement onOrderTracking:

2. When onOrderTracking is called depends on which server-side flow your integration uses.

3. From your server, get the order details and pass it as orderDetails to your client side.
   If an error occurs, the Apple Pay payment overlay is closed, and the payment is successfully completed without creating an order in the shopper's Apple Wallet app.

Optional Apple Pay capabilities check

Supported in v6.10.0 or later.

You can use the applePayCapabilities method to check whether the device supports Apple Pay and if the shopper has an active card in their wallet for web payments. You can then configure when to offer Apple Pay depending on the available payment methods in your shopper's wallet. This is only recommended if you display Apple Pay on the product page.

To implement applePayCapabilities:

applepay.applePayCapabilities().then(capabilities => {
  // Check whether the person has an active payment method in their wallet.
  switch (capabilities.paymentCredentialStatus) {
    case "paymentCredentialsAvailable":
      // Display an Apple Pay button and offer Apple Pay as the primary payment option.
    case "paymentCredentialStatusUnknown":
      // Display an Apple Pay button and offer Apple Pay as a payment option.
    case "paymentCredentialsUnavailable":
      // Optionally, display an Apple Pay button.
    case "applePayUnsupported":
      // Do not show an Apple Pay button or offer Apple Pay.
  }
});

Recurring payments

Apple Pay supports tokenization for recurring transactions on v5.39.0 and later.

To enable recurring payments, you must include recurringPaymentRequest when configuring Apple Pay.

To make recurring payments, refer to Tokenization to:

• Create a token through the initial payment
• Use the token in subsequent payments.
• Manage tokens.

Test and go live

Use Apple's test card numbers to test your integration.

For a full list of test cards and instructions how to add these to your test device, see Sandbox testing on Apple's Developer website.

Check the status of an Apple Pay test payment in your Customer Area > Transactions >  Payments.

Going live

To process live Apple Pay payments, your API credential needs to have the API Clientside Encryption Payments role. You can check this in your live Customer Area or ask your Admin user to verify.

See also