Apple Pay on the web using your own checkout page: decryption is done by you and you use your own Apple account

Integrate Apple Pay on the Web in your own checkout pages, and handle the decryption of the Apple Pay payment tokens yourself by following the instructions on this page. Be aware that if you choose to handle decryption of the Apple Pay payment tokens in your systems, you have to adhere to the PCI SAQ-D requirements. Before you start integrating Apple Pay on the Web in this manor, please consider whether integrating Apple Pay on the Web with Worldline's certificate, or with your own certificate but with payment token decryption by Worldline are an option for you, as they require less effort.

You will need to take care of the following steps:

• Enable Apple Pay on your merchant ID with us
• Create an Apple Pay Developer account
• Set up an Apple Pay payment processing certificate and store the private key safely
• Set up a merchant ID with Apple and create a merchant identity certificate with Apple
• Register the domain where you will host the Apple Pay button with Apple 
• Host the verification file provided by Apple
• Whitelist the IP addresses and domains of Apple
• Implement Apple Pay on the web
• Sent the payment token to your systems for decryption and sent the decrypted payment details to complete the payment

Enabling Apple Pay at Worldline

First make sure Apple Pay is enabled for your account with us (merchant ID). To do so contact your account manager at Worldline who will work together with your implementation manager. They will be able to set the product up for you.

Create an Apple developer account

If you do not have one yet, make sure to set up an Apple Developer account. Have a look at the following page for instructions and more information about organisational Developer accounts.

Configuring Apple Pay on the web

In order to start accepting Apple Pay payments on your website, some configuration needs to be in place. Apple Pay requires setting up a payment processing certificate to protect your customers payment details. The certificate is used to encrypt their payment details, which creates the Apple Pay payment token. This token can be securely sent from you website to your server. The private part of the certificate will be used to decrypt the token to finish the payment.

Another security measure is that Apple only allows Apple Pay payments to be initiated from registered and validated domains. Both the certificate, and the registered domains need to be configured before you can start implementing Apple Pay on your website.

If you choose this option you’ll be setting up your merchant ID, Apple Pay payment processing certificate, merchant certificate and verified domains with Apple. You will need to whitelist Apple Pay's IP addresses and domains as well. No configuration with us is required.  Please consult the Apple Pay Setup section in Apple’s documentation to set this up.

Please note that this option requires you to implement the decryption of the Apple Pay payment token on your own systems, which also means you need to adhere to the PCI requirements to be able to process this payment date. Once the token is decrypted, the payment details can be sent via the Create Payment API. See also Decrypting the payment token yourself.

Implementing Apple Pay on the web

The next step is to add code to your website to start accepting Apple Pay payments. This guide assumes that you will be using our JavaScript Client SDK in combination with Apple’s APIs where required. For information on how to initialise and work with our JavaScript Client SDK, please consult our Client SDK documentation. For detailed information on the mentioned Apple Pay APIs, please consult Apple’s official documentation.

1. Retrieve Apple Pay via the payment product(s) API

The first step is to use the JavaScript Client SDK to retrieve the Apple Pay payment product via the payment product(s) API. This will retrieve data that is required in the next steps, such as the supported networks. While retrieving the payment product details, the SDK will also perform a call to Apple's canMakePayments API, checking whether Apple Pay is available with the device and settings your customer is using. If this check fails, the Apple Pay payment product will not be returned by the SDK, indicating that Apple Pay is not available for the current transaction.

const APPLE_PAY_PRODUCT_ID = 302;

const paymentDetails = {
  totalAmount: 1,
  isRecurring: false,
  countryCode: 'US',
  currency: 'USD',
};

const paymentProductSpecificInputs = {
  applePay: {
    merchantName: 'MyMerchantName',
  },
};

try {
  // session is an instance of the Session object, which is the main entry point for the SDK
  const paymentProduct = await session.getPaymentProduct(
    APPLE_PAY_PRODUCT_ID,
    paymentDetails,
    paymentProductSpecificInputs,
  );

  // set payment product to the PaymentRequest to encrypt later
  const paymentRequest = session.getPaymentRequest();
  paymentRequest.setPaymentProduct(paymentProduct);

  // Apple pay is available, show the Apple Pay button
} catch (err) {
  // Apple Pay is not available, offer your customer another payment option to complete the payment
}

2. Show the Apple Pay button

Once you know Apple Pay is available, you can show the Apple Pay button to your customer. Please consult Apple’s documentation on displaying the Apple Pay button.

3. Initialise the payment

The next step is to respond to your customer clicking the Apple Pay button by creating an Apple Pay payment session and finishing the payment. 

In order to collect your customers email address, shipping address, and potentially charge for shipping costs via Apple Pay, you have to integrate with Apple’s Apple Pay API directly. The JavaScript SDK can still help you with obtaining the supported networks, and preparing the payment details for the Create Payment API. Please consult Apple's documentation on ApplePaySession for details on the required and returned values of their API. The snippet below shows how to setup and complete a payment via the Apple Pay API.

Before the payment sheet will be shown to your customer, the onvalidatemerchant callback on the ApplePaySession object will be called. When this function is called, you are required to request an Apple Pay payment session via the url that is provided as a parameter. 

/**
 * OnClick Apple Button callback handler
 * Creates an Apple Pay payment.
 */
function onApplePayButtonClick() {
  const paymentRequest = session.getPaymentRequest();
  const paymentProduct = paymentRequest.getPaymentProduct();
  const supportedNetworks = paymentProduct.paymentProduct302SpecificData.networks;

  // Initialise the Apple Pay Payment Request
  const applePayPaymentRequest = {
    supportedNetworks,
    // other payment values here...
  };

  // Try to support the lowest minimal version
  const minimalSupportedVersion = 1;

  const applePaySession = new ApplePaySession(
    minimalSupportedVersion,
    applePayPaymentRequest
  );

  // start Apple Pay
  applePaySession.begin();

  // Handle Apple's merchant validation request
  applePaySession.onvalidatemerchant = async (event) => {
    try {
      const paymentRequestPayload = {
        displayName: 'Visa 1233',
        validationUrl: event.validationURL,
        domainName: window.location.hostname
      };

      // The create payment product session API will handle 
      // the Apple Pay server-to-server  merchant validation
      const { paymentProductSession302SpecificOutput } = await session.createPaymentProductSession(
        APPLE_PAY_PRODUCT_ID, 
        paymentRequestPayload
      );

      // Complete the merchant validation by providing the merchantSession object to the ApplePaySession
      const merchantSession = JSON.parse(paymentProductSession302SpecificOutput!.sessionObject);
     applePaySession.completeMerchantValidation(merchantSession);
    } catch(error) {
      // Somehting went wrong, cancel the payment
     applePaySession.abort();
    }
  };

  applePaySession.onshippingcontactselected = (event) => {
    // Store the updated shipping details and potentially update
   // the payment by adding new line items

    const applePaySchippingContactUpdate = {
     newTotal: ``,
      newLineItems: ``,
      // other values here...
    };

   applePaySession.completeShippingContactSelection(applePayShippingContactUpdate);
  };

  applePaySession.onpaymentauthorized = (event) => {
    const token = event.payment.token;
   const status = token
      ? ApplePaySession.STATUS_SUCCESS
      : ApplePaySession.STATUS_FAILURE;

    applePaySession.completePayment(status);

    switch(status) {
      case ApplePaySession.STATUS_SUCCESS:
        // Store the payment token in the PaymentRequest
        const paymentData = token.paymentData;
        paymentRequest.setValue('encryptedPaymentData', JSON.stringify(paymentData));
        break;
      case ApplePaySession.STATUS_FAILURE:
       // No payment token means the payment failed. Let your customer know and
        // complete the payment with a failed status.
        break;
    }
  };
}

4. Preparing and sending the payment token

When the payment completes successfully, you will receive the Apple Pay payment result, which contains the Apple Pay payment token. This payment token needs to be provided in the Create Payment API to complete the payment. Send the payment token to your own backend servers, where it can be decrypted using the payment processing certificate's private key.

Sending the payment details

After decryption, you have to use the mobilePaymentMethodSpecificInput.decryptedPaymentData field in the Create Payment API to provide the payment details. Below is an example on how you can provide the decrypted payment data in the create payment request.

{
    "order" : {
        "amountOfMoney" : {
            "currencyCode" : "EUR",
            "amount" : 2980
        },
        "customer" : {
            "locale" : "en_US",
            "merchantCustomerId" : "1234",
            "billingAddress": {
                "countryCode": "NL"
            }
        }    
    },
    "mobilePaymentMethodSpecificInput": {
        "paymentProductId": 302,
        "decryptedPaymentData": {
            "dpan": "4111111111111111",
            "eci": "05",
            "expiryDate": "1220",
            "cryptogram": "<paymentData.onlinePaymentCryptogram>"
        }
    }
}

Sequence diagrams

Full sequence for integrating Apple Pay by using the Apple Pay API directly.