Introduction

You can use Apple Pay as a checkout option on the payment page or as a direct checkout option on the cart page (fast checkout). After configuring your environment, load the Apple Pay button via the COPYandPAY payment widget like any other brand. In step 2, specify APPLEPAY (the Payment Orchestration Platform handles the Apple Pay token decryption) or APPLEPAYTKN (the acquirer handles the token decryption). After the consumer uses the Apple Pay button, the Apple Pay payment sheet appears on the device.

When the consumer interacts with the Apple Pay payment sheet, other events trigger. Consume these events by implementing the COPYandPAY API callback functions. The COPYandPAY API wraps all callback functions from the Apple Pay SDK, eliminating the need for direct interaction with the Apple Pay SDK.

To steer the Apple Pay payment sheet or update data on it after the consumer starts interacting, use the available options.

Configuration

Processing Apple Pay requires certificates. You can use Peach Payments' certificates or create your own. Use Peach Payments' certificates because:

• It is easier and faster to integrate.
• An Apple developer account is not required.
• You do not need to manage expiring certificates. Peach Payments renews them for you.

In addition to the certificates, your server must serve pages over HTTPS. See Setting up your server for more details.

Use Peach Payments' Apple Pay certificates

1. In Smart Payments Platform, select your merchant in the entity tree. Go to Administration -> Mobile Payment, expand the section Apple Pay Web Merchant Registration, and click Check registration status.
2. Download the domain-verification file and host it at the specified path. This step is not mandatory for UAT.
3. Enter your domain name and click Register.

Use your own Apple Pay certificates

With your Apple Developer account, create a merchant ID and generate two certificates: Payment Processing Certificate and Merchant Identity Certificate.

Payment processing certificate

1. In Smart Payments Platform, select your merchant in the entity tree.
2. Go to Administration -> Mobile Payment, expand the section Apple Pay - Payment Processing Certificate, and click Generate keys to download the CSR (certificate signing request).
3. In Apple Developer, select the merchant ID and choose Create Certificate under Apple Pay Payment Processing Certificate. Upload the CSR from the previous step and download the certificate.
4. Upload the certificate in Smart Payments Platform, where you created the CSR.

Merchant identity certificate

1. In Smart Payments Platform, select your merchant in the entity tree.
2. Go to Administration -> Mobile Payment, expand the section Apple Pay on the Web, and click Generate keys to download the CSR.
3. In Apple Developer, select the merchant ID and choose Create Certificate under Apple Pay Merchant Identity Certificate. Upload the CSR from the previous step and download the certificate.
4. Upload the certificate in Smart Payments Platform, where you created the CSR.

Add your domain name in Apple Developer. See Configuring your environment for more detailed instructions.

The payment page

Load the Apple Pay button via the COPYandPAY payment widget like any other brand. In step 2, specify APPLEPAY or APPLEPAYTKN (if the acquirer handles token decryption) as the brand.

See an example below.

📘

The Apple Pay button only appears on compatible devices.

<form action="https://developer.peachpayments.com/docs/oppwa-integrations-copyandpay" class="paymentWidgets" data-brands="APPLEPAY"></form>

<style>
  body {
    background-color: #f6f6f5;
  }
</style>

<script>
  var wpwlOptions = {
    applePay: {
      displayName: "MyStore",
      total: { label: "COMPANY, INC." }
    }
  };
</script>

body {background-color:#f6f6f5;}

var wpwlOptions = {
  applePay: {
    displayName: "MyStore",
    total: { label: "COMPANY, INC." }
  }
}

Apple Pay options

Like other options, change the Apple Pay payment sheet behaviour using wpwlOptions.applePay.

Callback functions

📘

When using callback functions, if the consumer updates the data in the Apple Pay payment sheet, update the COPYandPAY checkout as well.

The table below lists the available Apple Pay callback functions for use with wpwlOptions.applePay.

Promises

Your handler returns a promise if it needs to do asynchronous work. It can be any thenable object. Both JavaScript Promise and jQuery Promise work.

For example, selecting a different shipping method might change the total amount. Use onPaymentAuthorized and make an AJAX call to your server for a server-to-server request to update the checkout amount. The function returns a promise, which, when fulfilled, confirms that the call has completed.

Example:

wpwlOptions.applePay.onPaymentAuthorized = function(payment) {
    // Call your server to update the checkout
    return $.post("https://your.server", {
        amount: theNewAmount
    }).then(function() {
        return {
            status: "SUCCESS"
        };
    });
};

Options and callback example

For example, use applePay.shippingMethods to offer multiple shipping options or applePay.onShippingContactSelected to calculate the tax when the consumer selects a shipping address.

To quick start your integration, use Peach Payments' example code below as guidance (click the JavaScript tab to see the code example).

<form action="https://developer.peachpayments.com/docs/oppwa-integrations-copyandpay" class="paymentWidgets" data-brands="APPLEPAY"></form>

body {background-color:#f6f6f5;}

var subTotalAmount = 7731;
var shippingAmount = 0;
var taxAmount = 1469;
var currency = "EUR";
var applePayTotalLabel = "COMPANY, INC.";

function getAmount() {
    return ((subTotalAmount + shippingAmount + taxAmount) / 100).toFixed(2);
}

function getTotal() {
    return {
        label: applePayTotalLabel,
        amount: getAmount()
    };
}

function getLineItems() {
    return [{
        label: "Subtotal",
        amount: (subTotalAmount / 100).toFixed(2)
    }, {
        label: "Shipping",
        amount: (shippingAmount / 100).toFixed(2)
    }, {
        label: "Tax",
        amount: (taxAmount / 100).toFixed(2)
    }];
}

var wpwlOptions = {
    applePay: {
        version: 3,
        checkAvailability: "applePayCapabilities",
        merchantIdentifier: "merchant.com.test",
        buttonSource: "js",
        buttonStyle: "white-outline",
        buttonType: "buy",
        displayName: "MyStore",
        total: getTotal(),
        currencyCode: currency,
        countryCode: "US",
        merchantCapabilities: ["supports3DS"],
        supportedNetworks: ["amex", "discover", "masterCard", "visa"],
        lineItems: getLineItems(),
        shippingMethods: [{
            label: "Free Shipping",
            amount: "0.00",
            identifier: "free",
            detail: "Delivers in five business days"
        }, {
            label: "Express Shipping",
            amount: "5.00",
            identifier: "express",
            detail: "Delivers in two business days"
        }],
        shippingType: "shipping",
        supportedCountries: ["US"],
        onCancel: function () {
            console.log("onCancel");
        },
        onPaymentMethodSelected: function (paymentMethod) {
            console.log("onPaymentMethodSelected: " + paymentMethod.type);
            subTotalAmount = (["debit", "credit"].includes(paymentMethod.type)) ? 7731 : 7431;
            return {
                newTotal: getTotal(),
                newLineItems: getLineItems()
            };
        },
        requiredShippingContactFields: ["postalAddress", "email"],
        requiredBillingContactFields: ["postalAddress"],
        onShippingContactSelected: function (shippingContact) {
            console.log("onShippingContactSelected: " + JSON.stringify(shippingContact));
            taxAmount = (shippingContact.administrativeArea === "FL") ? 1269 : 1469;
            var update = {
                newTotal: getTotal(),
                newLineItems: getLineItems()
            };
            if (shippingContact.postalCode === "95014") {
                update.errors = [{
                    code: "shippingContactInvalid",
                    contactField: "postalCode",
                    message: "ZIP Code is invalid"
                }];
            }
            return update;
        },
        onShippingMethodSelected: function (shippingMethod) {
            console.log("onShippingMethodSelected: " + JSON.stringify(shippingMethod));
            shippingAmount = (shippingMethod.identifier === "free") ? 0 : 500;
            return {
                newTotal: getTotal(),
                newLineItems: getLineItems()
            };
        },
        onPaymentAuthorized: function (payment) {
            console.log("onPaymentAuthorized payment: " + JSON.stringify(payment));
        }
    }
};

Result:

Registration tokens

You can use Apple Pay together with Tokenisation during payment by adding createRegistration=true in the checkout request. This creates a registration token that you can use for subsequent payments.

Add one of the following options to wpwlOptions.applePay to adjust the Apple Pay payment sheet:

• automaticReloadPaymentRequest
• recurringPaymentRequest
• deferredPaymentRequest

📘

You can set only one of these options at a time.

Errors

Handlers onShippingContactSelected and onPaymentAuthorized return an array of errors if the provided shippingContact or billingContact contains an issue. Each error identifies a specific problem in a contact field. The object structure is: