Pay with Apple Pay SDK

Overview

Apple Pay is a mobile payment and digital wallet service provided by Apple Inc.

Buyers can use Apple Pay on PayPal to make payments on the web using the Safari web browser or an iOS device.

Sellers can use Apple Pay on PayPal to sell:

physical goods, such as clothes and electronics
digital goods, such as software
intangible professional services, such as concerts or gym memberships.

Visit this site for more information about Apple Pay.

Supported countries and currencies

Apple Pay supports payments in 36 countries and 22 currencies:

Countries: Australia, Austria, Belgium, Bulgaria, Canada, China, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hong Kong, Hungary, Ireland, Italy, Japan, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Singapore, Slovakia, Slovenia, Spain, Sweden, United States, United Kingdom
Currencies: AUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD, USD

The Apple Pay button shows up on your website when a customer uses the Safari web browser on an eligible device. When your buyer selects the Apple Pay button, they confirm purchase details and authorize the payment on a payment sheet.

Visit this site for more details about Apple Pay's compatibility.

A buyer taps or clicks on the Apple Pay button on your website.
The Safari browser or iOS device shows the payer a payment sheet.
The buyer can choose a different shipping address and payment method.
The buyer authorizes the payment

Integration video

Watch our video tutorial for this integration:

Know before you code

You must be an approved partner to integrate the Apple Pay SDK.

For customers to pay with Apple Pay, they must be in a region where Apple Pay is supported, and their devices must meet the following requirements:

Device compatibility: The device must support Apple Pay.
iOS version: iOS 12.1 or later.
Desktop: macOS 10.14.1 or later.
Supported browsers: Safari. With the latest Apple Pay SDK, customers can also pay using non-Safari browsers.

PayPal also provides iframe support for ApplePay. To use ApplePay within an iframe:

The iframe tag must have the attribute allow="payment".
The parent domain hosting the iframe needs to have it's domain validated by following the usual process with PayPal.

Check Compatibility

Currently supports Apple Pay one-time payments with the payer present.

Review Apple's terms and conditions for the Apple Pay platform. See Apple's developer terms for more information.

Check Apple Docs

1. Onboard sellers

You'll need to onboard your sellers so they can use this product. Modify your Partner Referral API call to include "PAYMENT_METHODS" in the "products" array and "APPLE_PAY" in the "capabilities" array for merchant onboarding.
Add the COMPONENTS=APPLEPAY script tag to enable Apple Pay.
See Onboard merchants for more information.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'PayPal-Partner-Attribution-ID: BN-CODE' \
-d '{
  "operations": [
    {
      "operation": "API_INTEGRATION",
      "api_integration_preference": {
        "rest_api_integration": {
          "integration_method": "PAYPAL",
          "integration_type": "THIRD_PARTY",
          "third_party_details": {
            "features": [
              "PAYMENT",
              "REFUND"
            ]
          }
        }
      }
    }
  ],
  "products": [
    "PPCP",
    "PAYMENT_METHODS"
  ],
  "capabilities": [
    "APPLE_PAY"
  ],
  "legal_consents": [
    {
      "type": "SHARE_DATA_CONSENT",
      "granted": true
    }
  ]
}'

2. Set up your sandbox account to accept Apple Pay

Before you can accept Apple Pay on your website, verify that your sandbox business account supports Apple Pay.

Partners can use the PayPal Developer Dashboard to set up their sandbox accounts to accept Apple Pay. The integration for partner accounts includes creating a sandbox business account through sandbox.paypal.com. If the Apple Pay status for the account shows as disabled, complete the sandbox onboarding steps to enable Apple Pay.

Log into the PayPal Developer Dashboard and go to your sandbox account.
Go to Apps & Credentials.
Make sure you are in the PayPal sandbox environment by selecting Sandbox at the top.
Select or create an app.
Scroll down to Mobile and digital payments and check if Apple Pay is enabled. If Apple Pay isn't enabled, select the Apple Pay checkbox.

If you created a sandbox business account through sandbox.paypal.com, and the Apple Pay status for the account shows as disabled, complete the sandbox onboarding steps to enable Apple Pay.

Tip: When your integration is ready to go live, read the Go live section for details about the additional steps needed for Apple Pay onboarding.

3. Set up your testing environment

Before you develop your Apple Pay on the web integration, you need to set up your PayPal account, client ID, and sandbox emails for testing.

Download and host the domain association file for your sandbox environment.
Register your sandbox domain.
Create an Apple Pay sandbox account for testing. You don't need an Apple developer account to go live.

Important: You need to verify any domain names that you want to show an Apple Pay button. Apple rejects payments from unverified domains. The Apple Pay payment method won't work if the domain isn't registered.

Download and host sandbox domain association file

Download the domain association file for your sandbox environment.
Host the file on your test environment at /.well-known/apple-developer-merchantid-domain-association.

Register your sandbox domain

Request an access token by sending a POST request to https://api-m.sandbox.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the merchant ID for which you are registering the domain.
Register the domain by sending a POST request to https://api-m.sandbox.paypal.com/v1/customer/wallet-domains. Include the following in your request:

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion.
3. "provider_type": "APPLE_PAY" to indicate that this is an APPLE_PAY domain registration.
4. "domain": {"name": "example.com" }, and replace "example.com" with the domain you would like to register.

Example JSON request:
```
// Register a domain
{
  "provider_type":"APPLE_PAY",
    "domain": {
    "name":"example.com"
      }
}
```
You will receive a 201 CREATED response with the merchant and domain registration details if this is successful.

Deregister your sandbox domain

Request an access token by sending a POST request to https://api-m.sandbox.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the merchant ID for which you are deregistering the domain.
Deregister the domain by sending a POST request to https://api-m.sandbox.paypal.com/v1/customer/unregister-wallet-domain. Include the following in your request:

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion.
3. "provider_type": "APPLE_PAY" to indicate that this is an APPLE_PAY domain deregistration
4. "domain": { "name": "example.com" }, and replace "example.com" with the domain you would like to deregister.
5. "reason": "Why you are deregistering this domain" to indicate the reason for deregistration.

Example JSON request:
```
// Deregister a domain
{
  "provider_type":"APPLE_PAY",
    "domain": {
    "name":"example.com"
    },
  "reason":"Merchant requested to deregister domain",
}
```
You will receive a 200 OK response with the merchant and domain deregistration details if this is successful.

View list of registered sandbox domains

Request an access token by sending a POST request to https://api-m.sandbox.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the merchant ID that you are registering the domain for.
Query the list of registered domains by sending a GET request to https://api-m.sandbox.paypal.com/v1/customer/wallet-domains.

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion to indicate the merchant for which you are getting the domain.
You will receive a 200 OK response with the registered domain under the wallet_domains field if this is successful.

Create Apple Pay sandbox account

Create an Apple Pay sandbox account on the Apple Developer website to get a test wallet and test cards to test your Apple Pay integration.

If you already have an Apple sandbox account, you can use that account.

Create an Apple developer account.
Create an Apple sandbox account.

4. Integrate Apple Pay checkout

Follow this integration process to add Apple Pay as a checkout option, customize the payment experience, and process payments.

Important: You can find a complete example in the GitHub repo.

Call the Orders API

To accept Apple Pay directly on your website, create API endpoints on your server that communicate with the PayPal Orders V2 API. These endpoints can create an order, authorize payment, and capture payment for an order.

Server-side example (Node.js)

The following example uses the PayPal Orders V2 API to add routes to an Express server for creating orders and capturing payments. Find the complete sample code in the GitHub repo.

import * as PayPal from "./paypal-api.js";

// Create order
app.post("/api/orders", async (req, res) => {
  const order = await paypal.createOrder();
  res.json(order);
});

// Capture payment
app.post("/api/orders/:orderID/capture", async (req, res) => {
  const {
    orderID
  } = req.params;
  const captureData = await paypal.capturePayment(orderID);
  res.json(captureData);
});

5. Set up your Apple Pay button

You need to Integrate with the Apple Pay JavaScript SDK and PayPal JavaScript SDK to add Apple Pay to your site.

Integrate PayPal JavaScript SDK

Use this script to integrate with the PayPal JavaScript SDK:

<scriptsrc="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID¤cy=USD&buyer-country=US&merchant-id=SUB_MERCHANT_ID&components=applepay"></script>

Include applepay in the components list.

Integrate Apple JavaScript SDK

Use this script to integrate with the Apple JavaScript SDK:

<scriptsrc="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>

PayPal's Apple Pay component interacts with your JavaScript code in 4 areas:

Checking merchant eligibility for Apple Pay: paypal.Applepay().config()
Creating an Apple Pay session
Handling the onvalidatemerchant callback: paypal.Applepay().validateMerchant()
Handling the onpaymentauthorized callback: paypal.Applepay().confirmOrder()

Before you show the Apple Pay button, make sure that you can create an Apple Pay instance and that the device can make an Apple Pay payment.

Use ApplePaySession.canMakePayments to check if the device can make Apple Pay payments.

Tip: When testing, you need to be logged into the iCloud account for your testing environment. Testing in the sandbox requires you to log into an iTunes Connect sandbox tester account, which you can create with an Apple Developer account. When you test in a live environment, log into a live iCloud account.

Check for device and merchant eligibility before setting up the Apple Pay button.

To check eligibility, use the PayPal JavaScript SDK API paypal.Applepay().config().

<div id="applepay-container"></div>

if (!window.ApplePaySession) {
  console.error('This device does not support Apple Pay');
}

if (!ApplePaySession.canMakePayments()) {
  console.error('This device is not capable of making Apple Pay payments');
}

const applepay = paypal.Applepay();

applepay.config()
  .then(applepayConfig => {
    if (applepayConfig.isEligible) {
      document.getElementById("applepay-container").innerHTML = '<apple-pay-button id="btn-appl" buttonstyle="black" type="buy" locale="en">';
    }
  })
  .catch(applepayConfigError => {
    console.error('Error while fetching Apple Pay configuration.');
  });

You can find more details on how to set up the Apple Pay button in Apple's developer documentation.

6. Create Apple Pay session

The ApplePaySession object manages the Apple Pay payment process on the web. Create a new ApplePaySession each time a payer explicitly requests a payment, such as inside an onclick event. If you don't create an ApplePaySession each time, you get a "Must create a new ApplePaySession from a user gesture handler" JavaScript exception. For more information about this error, visit Apple's Creating an Apple Pay Session page.

For each ApplePaySession, create an ApplePayPaymentRequest object, which includes information about payment processing capabilities, the payment amount, and shipping information.

The response object of the PayPal JavaScript SDK API paypal.Applepay().config() provides the following parameters in the ApplePayPaymentRequest object:

countryCode
merchantCapabilities
supportedNetworks

// Note: the `applepayConfig` object in this request is the response from `paypal.Applepay().config()`.
const paymentRequest = {
  countryCode: applepayConfig.countryCode,
  merchantCapabilities: applepayConfig.merchantCapabilities,
  supportedNetworks: applepayConfig.supportedNetworks,
  currencyCode: "USD",
  requiredShippingContactFields: ["name", "phone", "email", "postalAddress"],
  requiredBillingContactFields: ["postalAddress"],
  total: {
    label: "Demo",
    type: "final",
    amount: "100.00",
  },
};

const session = newApplePaySession(4, paymentRequest);

Include the new ApplePaySession inside a gesture handler, such as an onclick event or an addEventListener click handler.

Creating an ApplePaySession object throws a JavaScript exception if any of the following occurs:

Any Apple Pay JavaScript API is called from an insecure page that doesn't use https.
An incorrect payment request is passed. Payment requests are incorrect if they contain missing, unknown or invalid properties, or if the total amount is negative.

onvalidatemerchant callback

Use paypal.Applepay().validateMerchant() in the onvalidatemerchant callback to create a validated Apple Pay session object:

session.onvalidatemerchant=(event)=>{
    applepay.validateMerchant({
    validationUrl: event.validationURL,
        displayName:"My Store"
        })
        .then(validateResult=>{
            session.completeMerchantValidation(validateResult.merchantSession);
        })
        .catch(validateError=>{
            console.error(validateError);
            session.abort();
    });
};

onpaymentauthorized callback

Safari calls the onpaymentauthorized callback with an event object. The event object passes a token which you need to send to PayPal to confirm the order.

Capture the order using the PayPal Orders V2 API. Use paypal.Applepay().confirmOrder() to send the orderID, the Apple Pay token, billing contact details, and confirm the order.

session.onpaymentauthorized = (event) = >
{
  console.log('Your billing address is:', event.payment.billingContact);
  console.log('Your shipping address is:', event.payment.shippingContact);
  // The `billingContact` and `shippingContact` object use the
  // `ApplePayPaymentContact` format. Find more details about this object at
  // this URL:
  // https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentcontact
  fetch(`/ api / orders`, {
    method : 'post'
    body :
        // You can use the "body" parameter to pass optional, additional order
        // information, such as: amount, and amount breakdown elements like tax,
        // shipping, and handling item data, such as sku, name, unit_amount, and
        // quantity shipping information, like name, address, and address type
        // Name and address information is passed by
        // `event.payment.shippingContact`.
  })
      .then(res = > res.json())
      .then((createOrderData) = > {
        var orderId = createOrderData.id;
        applepay
            .confirmOrder({
              orderId : orderId,
              token : event.payment.token,
              billingContact : event.payment.billingContact
            })
            .then(confirmResult = > {
              session.completePayment(ApplePaySession.STATUS_SUCCESS);
              // Submit approval to the server and authorize or capture the
              // order.
              fetch(`/ api / orders / ${orderId} / capture`, {
                method : "post",
              })
                  .then(res = > res.json())
                  .then(captureResult = > { console.log(captureResult); })
                  .catch(captureError = > console.error(captureError));
            })
            .catch(confirmError = > {
              if (confirmError) {
                console.error('Error confirming order with applepay token');
                console.error(confirmError);
                session.completePayment(ApplePaySession.STATUS_FAILURE);
              }
            });
      });
};

7. Show the payment sheet

After you have created the Apple Pay session and added the callbacks, call the session's begin method to show the payment sheet. You can only call the begin method when a payer explicitly requests a payment, such as inside an onclick event. The begin method throws a JavaScript exception if the buyer doesn't explicitly request the action:

session.begin();

After the payer starts a payment in the browser, they use their Apple device to authorize the payment.

Customize payment

Customize payment using the Apple Pay JavaScript SDK.

The commonly used customizations for Apple Pay are:

Customization, Apple Pay SDK Details
Customization	Apple Pay SDK Details
A set of line items that explain the subtotal, tax, discount, and additional charges for the payment.	`lineItems`
The billing information fields that the payer must provide to fulfill the order.	`requiredBillingContactFields`
The shipping information fields that the payer must provide to fulfill the order.	`requiredShippingContactFields`
The payer's billing contact information.	`billingContact`
The payer's shipping contact information.	`shippingContact` Call the `onshippingcontactselected` event handler when the user selects a shipping contact in the payment sheet.
The shipping method for a payment request.	`ApplePayShippingMethod`Call the `onshippingmethodselected` event handler when the user selects a shipping method in the payment sheet.

8. Test your integration

Ensure your integration with Apple Pay is configured properly for sandbox and production environments.

Use your personal sandbox login information during checkout to complete a payment using Apple Pay. Then, log into the sandbox site sandbox.paypal.com to see that the money has moved into your account.

Open your test page with the Safari web browser on an iOS device or computer.
Get a test card from your Apple sandbox account.
Add the test card to your Apple Wallet on your iOS device or by using the Safari browser on the web.
Tap the Apple Pay button to open a pop-up with the Apple Pay payment sheet.
Make a payment using the Apple Pay payment sheet.
If you have an additional confirmation page on your merchant website, continue to confirm the payment.
Log in to your merchant account and continue to your confirmation page to confirm that the money you used for payment showed up in the account.

9. Go live

Make Apple Pay available to buyers using your website or app.

Important: Before going live, complete production onboarding to process Apple Pay payments with your live PayPal account.

Live environment

If you are a new partner setting up a marketplace or platform for individual sellers, fill in this form to become an approved partner. Then, see Get Started and Configure your account to sign up for a PayPal business account.

Use your personal production login information during checkout to complete an Apple Pay transaction. Log into paypal.com to see the money move out of your account.

Getting started in your live environment

You need to verify any domain names in your production environment that will show an Apple Pay button. If Apple hasn't verified a domain, they will reject any payments from that domain.

Download and host the domain association file for your live environment.
Register your live domain on your PayPal Developer Dashboard.

Important: The Apple Pay payment method won't work if the domain isn't registered. There is no option to override this.

Download and host live domain association file

Download the domain association file for your live environment.
Host the file on your production site at /.well-known/apple-developer-merchantid-domain-association.

Download

Important: The partner that owns the domain is responsible for registering that domain.

Register your live domain

Request an access token by sending a POST request to https://api.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the Merchant ID for which you are registering the domain.
Register the domain by sending a POST request to https://api-m.paypal.com/v1/customer/wallet-domains. Include the following in your request:

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion.
3. "provider_type": "APPLE_PAY" to indicate that this is an APPLE_PAY domain registration.
4. "domain": { "name": "example.com" }, and replace "example.com" with the domain you would like to register.

Example JSON request:
```
// Register a domain
{
    "provider_type":"APPLE_PAY",
    "domain":{
        "name":"example.com"
        }
}
```
You will receive a 201 CREATED response with the merchant and domain registration details if this is successful.

Note: When Apple verifies a domain, it makes a request to retrieve the domain verification file. Ensure that:

The file is not served with a 3XX status code. Apple does not support HTTP URL redirects for the domain association file.
This file is served via HTTPS 1.1.
Important: This file is served with Content-Type: application/octet-stream to indicate that this is a binary file download.
The HTTP response for this request returns this file as a binary object and not as HTML, or plain text.
Access to this file is not behind a firewall. See Apple documentation on allowing Apple IP addresses.

Deregister your live domain

Request an access token by sending a POST request to https://api.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the merchant ID for which you are deregistering the domain.
Deregister the domain by sending a POST request to https://api-m.paypal.com/v1/customer/unregister-wallet-domain. Include the following in your request:

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion.
3. "provider_type": "APPLE_PAY" to indicate that this is an APPLE_PAY domain deregistration
4. "domain": { "name": "example.com" }, and replace "example.com" with the domain you would like to deregister.
5. "reason": "Why you are deregistering this domain" to indicate the reason for deregistration.

Example JSON request:
```
// Deregister a domain
{
    "provider_type":"APPLE_PAY",
    "domain":{
        "name":"example.com"
        },
    "reason":"Merchant requested to deregister domain",
}
```
You will receive a 200 OK response with the merchant and domain deregistration details if this is successful.

View list of registered live domains

Request an access token by sending a POST request to https://api.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the merchant ID that you are registering the domain for.
Query the list of registered domains by sending a GET request to https://api.paypal.com/v1/customer/wallet-domains.

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion to indicate the merchant for which you are getting the domain.
You will receive a 200 OK response with the registered domains under the wallet_domains field if this is successful.

Testing your live environment

When testing a purchase in production, consider:

The business account receiving money can't also make the purchase.
If you create a personal account with the same information as the business account, those accounts might experience restrictions.

How to test Apple Pay payments in a live environment

Open your test page with Safari on iOS or desktop.
Select the Apple Pay button to open a pop-up with the Apple Pay payment sheet.
Proceed with the Apple Pay checkout transaction.
If you have an additional confirmation page on your merchant website, confirm the payment.
Log in to your seller account and confirm that the money has moved into that account.

Troubleshoot your integration

Make sure that there are no browser console warnings or errors. The JavaScript SDK configuration attributes have distinct validation checks for input formatting and values.

If the validation fails, the web browser's developer console shows warning messages that say which property is incorrect and what you need to do to address the issue. The library generally attempts to revert to the safe default values if missing or incorrect inputs exist.

Next steps and customizations

Get started testing, add security to your checkout experience, or create customizations for your audience.

Integrate Expanded Checkout

Add more card payment options to your integration.

Overview

Apple Pay is a mobile payment and digital wallet service provided by Apple Inc.

Buyers can use Apple Pay on PayPal to make payments on the web using the Safari web browser or an iOS device.

Sellers can use Apple Pay on PayPal to sell:

physical goods, such as clothes and electronics
digital goods, such as software
intangible professional services, such as concerts or gym memberships.

Visit this site for more information about Apple Pay.

Supported countries and currencies

Apple Pay supports payments in 36 countries and 22 currencies:

Countries: Australia, Austria, Belgium, Bulgaria, Canada, China, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hong Kong, Hungary, Ireland, Italy, Japan, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Singapore, Slovakia, Slovenia, Spain, Sweden, United States, United Kingdom
Currencies: AUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD, USD

How it works

Visit this site for more details about Apple Pay's compatibility.

A buyer taps or clicks on the Apple Pay button on your website.
The Safari browser or iOS device shows the payer a payment sheet.
The buyer can choose a different shipping address and payment method.
The buyer authorizes the payment

Integration video

Watch our video tutorial for this integration:

Know before you code

You must be an approved partner to integrate the Apple Pay SDK.

For customers to pay with Apple Pay, they must be in a region where Apple Pay is supported, and their devices must meet the following requirements:

Device compatibility: The device must support Apple Pay.
iOS version: iOS 12.1 or later.
Desktop: macOS 10.14.1 or later.
Supported browsers: Safari. With the latest Apple Pay SDK, customers can also pay using non-Safari browsers.

PayPal also provides iframe support for ApplePay. To use ApplePay within an iframe:

The iframe tag must have the attribute allow="payment".
The parent domain hosting the iframe needs to have it's domain validated by following the usual process with PayPal.

Check Compatibility

Currently supports Apple Pay one-time payments with the payer present.

Review Apple's terms and conditions for the Apple Pay platform. See Apple's developer terms for more information.

Check Apple Docs

1. Onboard sellers

You'll need to onboard your sellers so they can use this product. Modify your Partner Referral API call to include "PAYMENT_METHODS" in the "products" array and "APPLE_PAY" in the "capabilities" array for merchant onboarding.
Add the COMPONENTS=APPLEPAY script tag to enable Apple Pay.
See Onboard merchants for more information.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'PayPal-Partner-Attribution-ID: BN-CODE' \
-d '{
  "operations": [
    {
      "operation": "API_INTEGRATION",
      "api_integration_preference": {
        "rest_api_integration": {
          "integration_method": "PAYPAL",
          "integration_type": "THIRD_PARTY",
          "third_party_details": {
            "features": [
              "PAYMENT",
              "REFUND"
            ]
          }
        }
      }
    }
  ],
  "products": [
    "PPCP",
    "PAYMENT_METHODS"
  ],
  "capabilities": [
    "APPLE_PAY"
  ],
  "legal_consents": [
    {
      "type": "SHARE_DATA_CONSENT",
      "granted": true
    }
  ]
}'

2. Set up your sandbox account to accept Apple Pay

Before you can accept Apple Pay on your website, verify that your sandbox business account supports Apple Pay.

Log into the PayPal Developer Dashboard and go to your sandbox account.
Go to Apps & Credentials.
Make sure you are in the PayPal sandbox environment by selecting Sandbox at the top.
Select or create an app.
Scroll down to Mobile and digital payments and check if Apple Pay is enabled. If Apple Pay isn't enabled, select the Apple Pay checkbox.

If you created a sandbox business account through sandbox.paypal.com, and the Apple Pay status for the account shows as disabled, complete the sandbox onboarding steps to enable Apple Pay.

Tip: When your integration is ready to go live, read the Go live section for details about the additional steps needed for Apple Pay onboarding.

3. Set up your testing environment

Before you develop your Apple Pay on the web integration, you need to set up your PayPal account, client ID, and sandbox emails for testing.

Download and host the domain association file for your sandbox environment.
Register your sandbox domain.
Create an Apple Pay sandbox account for testing. You don't need an Apple developer account to go live.

Download and host sandbox domain association file

Download the domain association file for your sandbox environment.
Host the file on your test environment at /.well-known/apple-developer-merchantid-domain-association.

Register your sandbox domain

Request an access token by sending a POST request to https://api-m.sandbox.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the merchant ID for which you are registering the domain.
Register the domain by sending a POST request to https://api-m.sandbox.paypal.com/v1/customer/wallet-domains. Include the following in your request:

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion.
3. "provider_type": "APPLE_PAY" to indicate that this is an APPLE_PAY domain registration.
4. "domain": {"name": "example.com" }, and replace "example.com" with the domain you would like to register.

Example JSON request:
```
// Register a domain
{
  "provider_type":"APPLE_PAY",
    "domain": {
    "name":"example.com"
      }
}
```
You will receive a 201 CREATED response with the merchant and domain registration details if this is successful.

Deregister your sandbox domain

Request an access token by sending a POST request to https://api-m.sandbox.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the merchant ID for which you are deregistering the domain.
Deregister the domain by sending a POST request to https://api-m.sandbox.paypal.com/v1/customer/unregister-wallet-domain. Include the following in your request:

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion.
3. "provider_type": "APPLE_PAY" to indicate that this is an APPLE_PAY domain deregistration
4. "domain": { "name": "example.com" }, and replace "example.com" with the domain you would like to deregister.
5. "reason": "Why you are deregistering this domain" to indicate the reason for deregistration.

Example JSON request:
```
// Deregister a domain
{
  "provider_type":"APPLE_PAY",
    "domain": {
    "name":"example.com"
    },
  "reason":"Merchant requested to deregister domain",
}
```
You will receive a 200 OK response with the merchant and domain deregistration details if this is successful.

View list of registered sandbox domains

Request an access token by sending a POST request to https://api-m.sandbox.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the merchant ID that you are registering the domain for.
Query the list of registered domains by sending a GET request to https://api-m.sandbox.paypal.com/v1/customer/wallet-domains.

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion to indicate the merchant for which you are getting the domain.
You will receive a 200 OK response with the registered domain under the wallet_domains field if this is successful.

Create Apple Pay sandbox account

Create an Apple Pay sandbox account on the Apple Developer website to get a test wallet and test cards to test your Apple Pay integration.

If you already have an Apple sandbox account, you can use that account.

Create an Apple developer account.
Create an Apple sandbox account.

4. Integrate Apple Pay checkout

Follow this integration process to add Apple Pay as a checkout option, customize the payment experience, and process payments.

Important: You can find a complete example in the GitHub repo.

Call the Orders API

Server-side example (Node.js)

The following example uses the PayPal Orders V2 API to add routes to an Express server for creating orders and capturing payments. Find the complete sample code in the GitHub repo.

import * as PayPal from "./paypal-api.js";

// Create order
app.post("/api/orders", async (req, res) => {
  const order = await paypal.createOrder();
  res.json(order);
});

// Capture payment
app.post("/api/orders/:orderID/capture", async (req, res) => {
  const {
    orderID
  } = req.params;
  const captureData = await paypal.capturePayment(orderID);
  res.json(captureData);
});

5. Set up your Apple Pay button

You need to Integrate with the Apple Pay JavaScript SDK and PayPal JavaScript SDK to add Apple Pay to your site.

Integrate PayPal JavaScript SDK

Use this script to integrate with the PayPal JavaScript SDK:

<scriptsrc="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID¤cy=USD&buyer-country=US&merchant-id=SUB_MERCHANT_ID&components=applepay"></script>

Include applepay in the components list.

Integrate Apple JavaScript SDK

Use this script to integrate with the Apple JavaScript SDK:

<scriptsrc="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>

PayPal's Apple Pay component interacts with your JavaScript code in 4 areas:

Checking merchant eligibility for Apple Pay: paypal.Applepay().config()
Creating an Apple Pay session
Handling the onvalidatemerchant callback: paypal.Applepay().validateMerchant()
Handling the onpaymentauthorized callback: paypal.Applepay().confirmOrder()

Before you show the Apple Pay button, make sure that you can create an Apple Pay instance and that the device can make an Apple Pay payment.

Use ApplePaySession.canMakePayments to check if the device can make Apple Pay payments.

Check for device and merchant eligibility before setting up the Apple Pay button.

To check eligibility, use the PayPal JavaScript SDK API paypal.Applepay().config().

<div id="applepay-container"></div>

if (!window.ApplePaySession) {
  console.error('This device does not support Apple Pay');
}

if (!ApplePaySession.canMakePayments()) {
  console.error('This device is not capable of making Apple Pay payments');
}

const applepay = paypal.Applepay();

applepay.config()
  .then(applepayConfig => {
    if (applepayConfig.isEligible) {
      document.getElementById("applepay-container").innerHTML = '<apple-pay-button id="btn-appl" buttonstyle="black" type="buy" locale="en">';
    }
  })
  .catch(applepayConfigError => {
    console.error('Error while fetching Apple Pay configuration.');
  });

You can find more details on how to set up the Apple Pay button in Apple's developer documentation.

6. Create Apple Pay session

For each ApplePaySession, create an ApplePayPaymentRequest object, which includes information about payment processing capabilities, the payment amount, and shipping information.

The response object of the PayPal JavaScript SDK API paypal.Applepay().config() provides the following parameters in the ApplePayPaymentRequest object:

countryCode
merchantCapabilities
supportedNetworks

// Note: the `applepayConfig` object in this request is the response from `paypal.Applepay().config()`.
const paymentRequest = {
  countryCode: applepayConfig.countryCode,
  merchantCapabilities: applepayConfig.merchantCapabilities,
  supportedNetworks: applepayConfig.supportedNetworks,
  currencyCode: "USD",
  requiredShippingContactFields: ["name", "phone", "email", "postalAddress"],
  requiredBillingContactFields: ["postalAddress"],
  total: {
    label: "Demo",
    type: "final",
    amount: "100.00",
  },
};

const session = newApplePaySession(4, paymentRequest);

Include the new ApplePaySession inside a gesture handler, such as an onclick event or an addEventListener click handler.

Creating an ApplePaySession object throws a JavaScript exception if any of the following occurs:

Any Apple Pay JavaScript API is called from an insecure page that doesn't use https.
An incorrect payment request is passed. Payment requests are incorrect if they contain missing, unknown or invalid properties, or if the total amount is negative.

onvalidatemerchant callback

Use paypal.Applepay().validateMerchant() in the onvalidatemerchant callback to create a validated Apple Pay session object:

session.onvalidatemerchant=(event)=>{
    applepay.validateMerchant({
    validationUrl: event.validationURL,
        displayName:"My Store"
        })
        .then(validateResult=>{
            session.completeMerchantValidation(validateResult.merchantSession);
        })
        .catch(validateError=>{
            console.error(validateError);
            session.abort();
    });
};

onpaymentauthorized callback

Safari calls the onpaymentauthorized callback with an event object. The event object passes a token which you need to send to PayPal to confirm the order.

Capture the order using the PayPal Orders V2 API. Use paypal.Applepay().confirmOrder() to send the orderID, the Apple Pay token, billing contact details, and confirm the order.

session.onpaymentauthorized = (event) = >
{
  console.log('Your billing address is:', event.payment.billingContact);
  console.log('Your shipping address is:', event.payment.shippingContact);
  // The `billingContact` and `shippingContact` object use the
  // `ApplePayPaymentContact` format. Find more details about this object at
  // this URL:
  // https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentcontact
  fetch(`/ api / orders`, {
    method : 'post'
    body :
        // You can use the "body" parameter to pass optional, additional order
        // information, such as: amount, and amount breakdown elements like tax,
        // shipping, and handling item data, such as sku, name, unit_amount, and
        // quantity shipping information, like name, address, and address type
        // Name and address information is passed by
        // `event.payment.shippingContact`.
  })
      .then(res = > res.json())
      .then((createOrderData) = > {
        var orderId = createOrderData.id;
        applepay
            .confirmOrder({
              orderId : orderId,
              token : event.payment.token,
              billingContact : event.payment.billingContact
            })
            .then(confirmResult = > {
              session.completePayment(ApplePaySession.STATUS_SUCCESS);
              // Submit approval to the server and authorize or capture the
              // order.
              fetch(`/ api / orders / ${orderId} / capture`, {
                method : "post",
              })
                  .then(res = > res.json())
                  .then(captureResult = > { console.log(captureResult); })
                  .catch(captureError = > console.error(captureError));
            })
            .catch(confirmError = > {
              if (confirmError) {
                console.error('Error confirming order with applepay token');
                console.error(confirmError);
                session.completePayment(ApplePaySession.STATUS_FAILURE);
              }
            });
      });
};

7. Show the payment sheet

session.begin();

After the payer starts a payment in the browser, they use their Apple device to authorize the payment.

Customize payment

Customize payment using the Apple Pay JavaScript SDK.

The commonly used customizations for Apple Pay are:

Customization, Apple Pay SDK Details
Customization	Apple Pay SDK Details
A set of line items that explain the subtotal, tax, discount, and additional charges for the payment.	`lineItems`
The billing information fields that the payer must provide to fulfill the order.	`requiredBillingContactFields`
The shipping information fields that the payer must provide to fulfill the order.	`requiredShippingContactFields`
The payer's billing contact information.	`billingContact`
The payer's shipping contact information.	`shippingContact` Call the `onshippingcontactselected` event handler when the user selects a shipping contact in the payment sheet.
The shipping method for a payment request.	`ApplePayShippingMethod`Call the `onshippingmethodselected` event handler when the user selects a shipping method in the payment sheet.

8. Test your integration

Ensure your integration with Apple Pay is configured properly for sandbox and production environments.

Open your test page with the Safari web browser on an iOS device or computer.
Get a test card from your Apple sandbox account.
Add the test card to your Apple Wallet on your iOS device or by using the Safari browser on the web.
Tap the Apple Pay button to open a pop-up with the Apple Pay payment sheet.
Make a payment using the Apple Pay payment sheet.
If you have an additional confirmation page on your merchant website, continue to confirm the payment.
Log in to your merchant account and continue to your confirmation page to confirm that the money you used for payment showed up in the account.

9. Go live

Make Apple Pay available to buyers using your website or app.

Important: Before going live, complete production onboarding to process Apple Pay payments with your live PayPal account.

Live environment

Use your personal production login information during checkout to complete an Apple Pay transaction. Log into paypal.com to see the money move out of your account.

Getting started in your live environment

You need to verify any domain names in your production environment that will show an Apple Pay button. If Apple hasn't verified a domain, they will reject any payments from that domain.

Download and host the domain association file for your live environment.
Register your live domain on your PayPal Developer Dashboard.

Important: The Apple Pay payment method won't work if the domain isn't registered. There is no option to override this.

Download and host live domain association file

Download the domain association file for your live environment.
Host the file on your production site at /.well-known/apple-developer-merchantid-domain-association.

Download

Important: The partner that owns the domain is responsible for registering that domain.

Register your live domain

Request an access token by sending a POST request to https://api.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the Merchant ID for which you are registering the domain.
Register the domain by sending a POST request to https://api-m.paypal.com/v1/customer/wallet-domains. Include the following in your request:

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion.
3. "provider_type": "APPLE_PAY" to indicate that this is an APPLE_PAY domain registration.
4. "domain": { "name": "example.com" }, and replace "example.com" with the domain you would like to register.

Example JSON request:
```
// Register a domain
{
    "provider_type":"APPLE_PAY",
    "domain":{
        "name":"example.com"
        }
}
```
You will receive a 201 CREATED response with the merchant and domain registration details if this is successful.

Note: When Apple verifies a domain, it makes a request to retrieve the domain verification file. Ensure that:

The file is not served with a 3XX status code. Apple does not support HTTP URL redirects for the domain association file.
This file is served via HTTPS 1.1.
Important: This file is served with Content-Type: application/octet-stream to indicate that this is a binary file download.
The HTTP response for this request returns this file as a binary object and not as HTML, or plain text.
Access to this file is not behind a firewall. See Apple documentation on allowing Apple IP addresses.

Deregister your live domain

Request an access token by sending a POST request to https://api.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the merchant ID for which you are deregistering the domain.
Deregister the domain by sending a POST request to https://api-m.paypal.com/v1/customer/unregister-wallet-domain. Include the following in your request:

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion.
3. "provider_type": "APPLE_PAY" to indicate that this is an APPLE_PAY domain deregistration
4. "domain": { "name": "example.com" }, and replace "example.com" with the domain you would like to deregister.
5. "reason": "Why you are deregistering this domain" to indicate the reason for deregistration.

Example JSON request:
```
// Deregister a domain
{
    "provider_type":"APPLE_PAY",
    "domain":{
        "name":"example.com"
        },
    "reason":"Merchant requested to deregister domain",
}
```
You will receive a 200 OK response with the merchant and domain deregistration details if this is successful.

View list of registered live domains

Request an access token by sending a POST request to https://api.paypal.com/v1/oauth2/token. Note the access token from the response body.
Generate a PayPal Auth Assertion header and make a note of it. Make sure to replace merchant_payer_id with the merchant ID that you are registering the domain for.
Query the list of registered domains by sending a GET request to https://api.paypal.com/v1/customer/wallet-domains.

1. The authorization header with the value Bearer: <your_access_token>.
2. The paypal-auth-assertion header with the value your_generated_auth_assertion to indicate the merchant for which you are getting the domain.
You will receive a 200 OK response with the registered domains under the wallet_domains field if this is successful.

Testing your live environment

When testing a purchase in production, consider:

The business account receiving money can't also make the purchase.
If you create a personal account with the same information as the business account, those accounts might experience restrictions.

How to test Apple Pay payments in a live environment

Open your test page with Safari on iOS or desktop.
Select the Apple Pay button to open a pop-up with the Apple Pay payment sheet.
Proceed with the Apple Pay checkout transaction.
If you have an additional confirmation page on your merchant website, confirm the payment.
Log in to your seller account and confirm that the money has moved into that account.

Troubleshoot your integration

Make sure that there are no browser console warnings or errors. The JavaScript SDK configuration attributes have distinct validation checks for input formatting and values.

Next steps and customizations

Get started testing, add security to your checkout experience, or create customizations for your audience.

Integrate Expanded Checkout

Add more card payment options to your integration.

Pay with Apple Pay SDK

Integrate Expanded Checkout

On this page

On this page

On this page

If you accept cookies, we'll use them to improve and customise your experience and enable our partners to show you personalised PayPal ads when you visit other sites. Manage cookies and learn more

Pay with Apple Pay SDK

Integrate Expanded Checkout

On this page

On this page