Apple Pay

Apple Pay

Introduction

Apple Pay can be utilized as a checkout option on a payment page as well as a direct checkout option on the cart page (fast checkout). After configuring your environment, loading the Apple Pay button via COPYandPAY payment widget is just like loading any other brand, i.e. in step 2, APPLEPAY (The "Payment Orchestration Platform" handles the decryption of the Applepay token) or APPLEPAYTKN (Acquirer handles the Token decryption) must be specified as a brand. Once the Apple Pay button will be used by the consumer, the Apple Pay payment sheet will appear on the device.

As soon as the consumer starts to interact with the Apple Pay payment sheet, several events will be triggered. All events can be consumed by implementing the COPYandPAY API callback functions. All callback functions offered by the Apple Pay SDK are wrapped into the COPYandPAY API. No interaction with the Apple Pay SDK is required.

For steering the Apple Pay payment sheet or for updating data on the Apple Pay payment sheet after the consumer started to interact with it, several options are available.

Configuration

Processing Apple Pay requires certificates. You can either use our certificates or create your own certificates. Using our certificates is recommended as:

  • It is easier and faster to integrate.
  • Apple developer account is not required.
  • You do not need to worry about expiring certificates. We will re-new them for you.

In addition to the certificates, your server must be set up such that pages are served over HTTPS. See Setting Up Your Server for more details.

Use our Apple Pay certificates

  1. In CheckoutGate Platform, select your merchant in the entity tree. Navigate to Administration -> Mobile Payment, expand the section Apple Pay Web Merchant Registration, click Check registration status.
  2. Download the domain-verification file and host it at the specified path. Note that 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 CheckoutGate Platform, select your merchant in the entity tree. Navigate to Administration -> Mobile Payment, expand the section Apple Pay - Payment Processing Certificate, click Generate keys and download CSR (certificate signing request).
  2. 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.
  3. Upload the certificate in CheckoutGate Platform, where the CSR was created.

Merchant Identity Certificate

  1. In CheckoutGate Platform, select your merchant in the entity tree. Navigate to Administration -> Mobile Payment, expand the section Apple Pay on the Web, click Generate keys and download CSR (certificate signing request).
  2. 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.
  3. Upload the certificate in CheckoutGate Platform, where the CSR was created.

Finally, add your domain name in Apple Developer. See Configuring Your Environment for more detailed instructions.

Apple Pay on the payment page

Loading the Apple Pay button via COPYandPAY payment widget is just like loading any other brand, i.e. in step 2, APPLEPAY or APPLEPAYTKN(if the Acquirer will handle the Token decryption) must be specified as a brand.

See an example below.

Note that the Apple Pay button only appears on compatible devices.

Apple Pay options

As with other options, you can modify the Apple Pay payment sheet behavior by using wpwlOptions.applePay.

ParameterMandatoryDescriptionDefault valueExamples
version No

The Apple Pay Javascript API version.

For the best compatibility, use the lowest possible version number that supports the features required. See Apple Pay on the Web Version History for version information. The list below gives a quick overview of some selected versions and supported operating systems:
  • 1 - macOS 10.12, iOS 10.0
  • 3 - macOS 10.13, iOS 11.0
  • 4 - macOS 10.14.1, iOS 12.1
  • 8 - macOS 10.15.1, iOS 13.2
  • 10 - macOS 11, iOS 14
  • 12 - macOS 12, iOS 15
  • 14 - macOS 13, iOS 16
1 version: 3
checkAvailability No Specify the Apple Pay support detection method. The value must be one of the followings:

  • "canMakePayments" - only checks to ensure that the device supports processing payments with Apple Pay. It does not verify whether or not the user has any provisioned cards in Wallet.

  • "applePayCapabilities" - (new) checks if the device supports Apple Pay and whether the person has an active card in Wallet that qualifies for web payments. This method asynchronously contacts the Apple Pay servers as part of the verification process.

    The Apple Pay button is displayed on supported devices, including third-party browsers. On third-party browsers, a device with iOS 18 is required to complete the payment.

    You can query the response about the device's support PaymentCredentialStatusResponse from the form attribute named data-applepayCapabilities.

    This option requires configuring the option merchantIdentifier.

  • "canMakePaymentsWithActiveCard" - (depracated) checks if the device supports Apple Pay and there is at least one active card in Wallet that is qualified for payments on the web.

    This option requires configuring the option merchantIdentifier.
 canMakePayments checkAvailability: "applePayCapabilities"
merchantIdentifier Yes/No The merchant ID created when the merchant enrolled in Apple Pay. This parameter is required when checkAvailability is "applePayCapabilities" or "canMakePaymentsWithActiveCard". If you use our certificates, set this option with our entityId. N/A merchantIdentifier: "com.company"
buttonSource No The Apple Pay button source. There are two options to render the Apple Pay button:

The "css" option usually works fine. However, if some buttonType does not work for you, please try the "js" option.

If checkAvailability is "applePayCapabilities", the button is always rendered wih Javascript to support third-party browsers.

 css buttonSource: "js"
buttonStyle No The Apple Pay button style. The value must be one of the followings: "white-outline", "white", "black". white-outline buttonStyle: "black"
buttonType No

A type that indicates the button types that you can display to initiate Apple Pay transactions. The supported values are: "add-money", "book", "buy", "check-out", "continue", "contribute", "donate", "order", "pay", "plain", "reload", "rent", "subscribe", "support", "tip", "top-up".

Note that with buttonSource="css" some button types might require specific versions, or might not work at all. See the reference for more details.

 plain buttonType: "check-out"
displayName No A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display. Do not localize the name. The value is displayed in the Touch Bar on supported models of MacBook Pro. N/A displayName: "MyStore"
total Yes/No An object representing the total for the payment. It can contain the following properties:
  • label - Provide a business name for the label field. Use the same business name people will see when they look for the charge on their bank or credit card statement.
  • amount - If not specified, the amount from the checkout is used.
    This parameter is required for the fast checkout.
  • type - "final" or "pending". If "pending", the Apple Pay payment sheet does not display the value in amount, and instead displays pending. The default value is "final".
 amount:{checkout amount}
type:final		 total: { label: "COMPANY, INC." }
currencyCode Yes/No The three-letter ISO 4217 currency code for the payment. If not specified, the currency from the checkout is used.
This parameter is required for the fast checkout.		 {checkout currency} currencyCode: "USD"
countryCode No The merchant’s two-letter ISO 3166 country code. wpwlOptions.locale countryCode: "US"
merchantCapabilities No The payment capabilities supported by the merchant. The supported values are:
  • "supports3DS" - This value must be supplied.
  • "supportsCredit" - If present, only transactions that are categorized as credit cards are allowed.
  • "supportsDebit" - If present, only transactions that are categorized as debit cards are allowed.
  • "supportsEMV" - Include this value only if you support China Union Pay transactions.
If both or neither supportsCredit and supportsDebit values are supplied, the transaction allows both credit and debit cards. 		supports3DS merchantCapabilities: ["supports3DS", "supportsCredit"]
supportedNetworks No

The payment networks supported by the merchant. The supported values are: "amex", "bancomat" (14), "bancontact" (14), "cartesBancaires" (4), "chinaUnionPay", "dankort" (13), "discover", "eftpos" (4), "electron" (4), "elo" (5), "girocard" (11), "interac", "jcb" (2), "mada" (5), "maestro" (4), "masterCard", "mir" (11), "privateLabel", "visa", "vPay" (4).

Note that the numbers in the parentheses indicate the Apple Pay versions where they are first available, e.g. "jcb" is only available starting from version 2. The payment networks without numbers are available from version 1. 		["amex", "discover", "masterCard", "visa"] supportedNetworks: ["amex", "chinaUnionPay", "discover", "jcb", "masterCard", "visa"]
lineItems No An array of items explaining additional charges, discounts, and pending costs. Each item represents a line on the payment sheet. The item must contain:
  • "label" - A short, localized description of the line item. Provide the label in title case–for example, VAT Tax, Gift Wrap and Card, or Discount. The label cannot be empty.
  • "amount" - The monetary amount of the item.
Note that you should provide the total separately by using the total property. Also, the array cannot be empty, if present. 		N/A lineItems: [{
  label: "Bag Subtotal",
  amount: "35.00"
}, {
  label: "Free Shipping",
  amount: "0.00"
}, {
  label: "Estimated Tax",
  amount: "3.06"
}]
shippingMethods No An array of available methods for shipping physical goods. Each shipping method must contain:
  • "label" - A short description of the shipping method.
  • "detail" - Additional description of the shipping method.
  • "amount" - The nonnegative cost associated with this shipping method.
  • "identifier" - A client-defined value used to identify this shipping method.
  • "dateComponentsRange" - (available from version 12) The expected range of dates for shipping or picking up an item. It should contain startDateComponents and endDateComponents. Each date component can contain: years, months, days as numbers.
N/A 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 No Indicate how purchased items are to be shipped. The value must be one of the followings: "shipping", "delivery", "storePickup", "servicePickup". shipping shippingType: "shipping"
supportedCountries No

An array that limits payment cards to those that were issued in specific countries. Indicate the supported countries by using ISO 3166 country codes.

The supportedCountries list does not affect the currency used for the transaction, and it applies to all payment cards in Wallet.

Available in Apple Pay JS API version 3. 		N/A supportedCountries: ["US"]
supportsCouponCode No

A Boolean value that determines whether the payment sheet displays the coupon code field.

Available in Apple Pay JS API version 12. 		false supportsCouponCode: true
couponCode No

The initial coupon code.

Available in Apple Pay JS API version 12. 		N/A couponCode: "DISCOUNT20"
requiredShippingContactFields No The fields of shipping information the user must provide to fulfill the order. The supported field names are: "email", "name", "phone", "postalAddress", and starting from version 3: "phoneticName". You will receive the customer's name when you request postalAddress. If you don't need the customer's address, you can request the name contact field directly. N/A requiredShippingContactFields: [ "postalAddress", "email" ]
shippingContact No

If you have an up-to-date shipping address on file, you can set it here.

The information you provide in shippingContact is displayed in the payment sheet as the default shipping address. The user can either keep the address you provided or select another address.

Provide your user's shipping contact info only if you are requiring shipping contact information.

The possible properties are:
  • phoneNumber
  • emailAddress
  • givenName
  • familyName
  • phoneticGivenName - Typically used for transactions in Japan. Available in Apple Pay JS API version 3.
  • phoneticFamilyName - Typically used for transactions in Japan. Available in Apple Pay JS API version 3.
  • addressLines - The street portion of the address for the contact.
  • subLocality - Additional information associated with the location, typically defined at the city or town level (such as district or neighborhood), in a postal address.
  • locality - The city for the contact.
  • postalCode - The zip code or postal code, where applicable, for the contact.
  • subAdministrativeArea - The subadministrative area (such as a county or other region) in a postal address.
  • administrativeArea - The state for the contact.
  • country - The name of the country for the contact.
  • countryCode - The contact’s two-letter ISO 3166 country code.
 N/A shippingContact: {
  addressLines: ["123 Any Street"],
  locality: "Any Town",
  administrativeArea: "CA",
  postalCode: "95014",
  countryCode: "US",
  familyName: "COMPANY, INC."
}
requiredBillingContactFields No The fields of billing information the user must provide to process the transaction. The only supported field is: "postalAddress". You will receive the postal address as well as the user's name after the user authorizes the transaction. N/A requiredBillingContactFields: [ "postalAddress" ]
billingContact No

If you have an up-to-date billing address on file, you can set it here. This billing address appears in the payment sheet. The user can either use the address you specify or select a different address.

Note: If you supply a billing address, you must also request "postalAddress" in requiredBillingContactFields.

See shippingContact for all available properties. 		N/A billingContact: {
  addressLines: ["123 Any Street"],
  locality: "Any Town",
  administrativeArea: "CA",
  postalCode: "95014",
  countryCode: "US",
  familyName: "COMPANY, INC."
}
shippingContactEditingMode No A value that indicates whether the shipping mode prevents the user from editing the shipping address. The supported values are:
  • "enabled" - The user can edit the shipping contact on the payment sheet.
  • "storePickup" - The user can’t edit the shipping contact on the payment sheet.
Set the value to storePickup for an in-store or other pickup to prevent the user from editing the shipping address.
Add postalAddress to requiredShippingContactFields to display the pickup address. Set the shippingContact to the pickup address.
Available in Apple Pay JS API version 12. 		enabled shippingContactEditingMode: "storePickup"
submitOnPaymentAuthorized No Automatically submit customer information and billing address received from Apple Pay as a part of the transaction. Possible values are:
  • customer: data from Apple Pay is submitted to the following customer fields: customer.email, customer.phone, customer.givenName, customer.surname
  • billing: data from Apple Pay is submitted to the following billing fields: billing.street1, billing.stree2, billing.city, billing.state, billing.postcode, billing.country
Note that this parameter must be used together with the parameter requiredBillingContactFields and requiredShippingContactFields to request "email", "name", "phone", and "postalAddress" from Apple Pay. 		N/A submitOnPaymentAuthorized: [ "customer", "billing" ]

Apple Pay callback functions

If the callback functions are used and data will get updated due to the consumer interaction with the Apple Pay payment sheet, the COPYandPAY checkout needs to get updated as well.

The following table lists all available Apple Pay callback functions that you can use with wpwlOptions.applePay.

Callback functionDescriptionExamples
onCancel An event handler that is called when the Apple Pay payment sheet is dismissed. Note that this function can be called even after the onPaymentAuthorized event handler has been called. onCancel:
function () {
}
onPaymentMethodSelected An event handler that is called when a new payment method is selected. The event parameter is an object that describes the selected Apple Pay payment card. The object contains:
  • displayName - A string, suitable for display, that describes the card.
  • network - A string, suitable for display, that is the name of the payment network backing the card.
  • type - The value is one of the followings: "debit", "credit", "prepaid", "store".
  • billingContact - (available from version 11) See onPaymentAuthorized for the list of available properties.
The handler should return an object containing:
  • newTotal - Required. The new total resulting from a change in the payment method. See the parameter total for the object structure.
    • Note that the amount is required.
  • newLineItems - An optional updated list of line items resulting from a change in the payment method. See the parameter lineItems for the object structure.
Alternatively, if the handler processing fails, e.g. there is an error while calculating the new total, the payment sheet can be dismissed, and therefore ending Apple Pay without completing a transaction, by returning an object containing:
  • status - "ABORT"
 onPaymentMethodSelected:
function (paymentMethod) {
  // Calculate new costs
  return {
    newTotal: {
      label: "Total",
      amount: "42.00"
    },
    newLineItems: [{
      label: "Shipping",
      amount: "2.00"
    }, {
      label: "Tax",
      amount: "3.00"
    }]
  };
}
onCouponCodeChanged

An event handler called by the system when the user enters or updates a coupon code. The parameter is the updated coupon code from the payment sheet.

The handler should return an object containing:
  • newTotal - Required. The updated total resulting from the coupon code update. See the parameter total for the object structure.
  • newLineItems - An optional updated list of line items incorporating the coupon code update. See the parameter lineItems for the object structure.
Alternatively, if the handler processing fails, e.g. there is an error while calculating the new total, the payment sheet can be dismissed, and therefore ending Apple Pay without completing a transaction, by returning an object containing:
  • status - "ABORT"
Available in Apple Pay JS API version 12. 		onCouponCodeChanged:
function (couponCode) {
  // Calculate new costs
  return {
    newTotal: {
      label: "Total",
      amount: "42.00"
    },
    newLineItems: [{
      label: "Shipping",
      amount: "2.00"
    }, {
      label: "Tax",
      amount: "3.00"
    }]
  };
}
onShippingContactSelected

An event handler that is called when a shipping contact is selected in the payment sheet. The event parameter is a redacted shipping contact. The redacted information includes only the necessary data for completing tasks such as calculating taxes or shipping costs. The information may differ based on the user's geographic region.

For Canada and United Kingdom, a redacted shipping address excludes the last three characters of the postal code. For US addresses, the redacted zip code contains the first five digits.

The full postal code is provided after the user authorizes the transaction. See onPaymentAuthorized for the full list of property names

The handler should return an object containing:
  • newTotal - Required. The new total resulting from a change in the shipping contact. See the parameter total for the object structure.
    • Note that the amount is required.
  • newLineItems - An optional updated list of line items resulting from a change in the shipping contact. See the parameter lineItems for the object structure.
  • newShippingMethods - An optional updated list of shipping methods that are available to the updated shipping contact. See the parameter shippingMethods for the object structure.
  • errors - List of custom errors to display on the payment sheet. If there are multiple errors, list the most important error first. See Errors for more information.
Alternatively, if the handler processing fails, e.g. there is an error while calculating the new total, the payment sheet can be dismissed, and therefore ending Apple Pay without completing a transaction, by returning an object containing:
  • status - "ABORT"
 onShippingContactSelected:
function (shippingContact) {
  // Calculate new costs
  return {
    newTotal: {
      label: "Total",
      amount: "42.00"
    },
    newLineItems: [{
      label: "Shipping",
      amount: "2.00"
    }, {
      label: "Tax",
      amount: "3.00"
    }]
  };
}
onShippingMethodSelected An event handler that is called when a shipping method is selected in the payment sheet. The event parameter is an object that describes the selected shipping method for delivering physical goods. The object contains:
  • label - A short description of the shipping method.
  • detail - Additional description of the shipping method.
  • amount - The nonnegative cost associated with this shipping method.
  • identifier - A client-defined value used to identify this shipping method.
The handler should return an object containing:
  • newTotal - Required. The new total resulting from a change in the shipping method. See the parameter total for the object structure.
    • Note that the amount is required.
  • newLineItems - An optional updated list of line items resulting from a change in the shipping method. See the parameter lineItems for the object structure.
Alternatively, if the handler processing fails, e.g. there is an error while calculating the new total, the payment sheet can be dismissed, and therefore ending Apple Pay without completing a transaction, by returning an object containing:
  • status - "ABORT"
 onShippingMethodSelected:
function (shippingMethod) {
  // Calculate new costs
  return {
    newTotal: {
      label: "Total",
      amount: "42.00"
    },
    newLineItems: [{
      label: "Shipping",
      amount: "2.00"
    }, {
      label: "Tax",
      amount: "3.00"
    }]
  };
}
onPaymentAuthorized

An event handler that is called when the user has authorized the Apple Pay payment with Touch ID, Face ID, or passcode. The event parameter contains: shippingContact and billingContact. See shippingContact for all available properties.

If the handler returns nothing, it is considered successful and the payment will proceeds. Otherwise, the handler can return an object containing:
  • status - Must be one of: "SUCCESS", "FAILURE", "ABORT". If ABORT is returned, the payment sheet will be dismissed.
  • errors - List of custom errors to display on the payment sheet. If there are multiple errors, list the most important error first. See Errors for more information.
onPaymentAuthorized:
function (payment) {
  //Save contacts from
  //payment.shippingContact
  //and
  //payment.billingContact
}

Promises

Your handler can return a promise if it needs to do an asynchronous work. It can be any thenable object. In particular, both JavaScript Promise and jQuery Promise are supported.

For example, the total amount might have been changed because a different shipping method was selected. You will need to implement onPaymentAuthorized, and use an ajax call to your server to do a server-to-server call to update the checkout amount. The function should return a promise, which once fulfilled, should signify that the call is 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, you might want to offer several shipping options by using applePay.shippingMethods, or calculate the tax when a shipping address is selected by using applePay.onShippingContactSelected.

To quick start your integration, we recommend use our example code below as a guidance (Click js tab to see the code example).

Apple Pay registration tokens

You can use Apple Pay together with Tokenization during payment, i.e. add createRegistration=true in the checkout request, to create a registration token that can be used in subsequent payments.

Add one of the following options to wpwlOptions.applePay to accordingly adjust the Apple Pay payment sheet: automaticReloadPaymentRequest, recurringPaymentRequest, deferredPaymentRequest

You can set only one of these options.
ParameterDescriptionExamples
automaticReloadPaymentRequest

A dictionary that represents a request to set up an automatic reload payment, such as a store card top-up or a prepaid account. See ApplePayAutomaticReloadPaymentRequest for more details.

Apple Pay issues an Apple Pay Merchant Token if the user's payment network supports merchant-specific payment tokens. Otherwise, Apple Pay issues a device token as usual.

Leave the field tokenNotificationURL empty. We set the value for you and handle token notifications on your behalf, i.e. when life-cycle updates to the merchant token, for example, when the card issuer or the user deletes the merchant token, occur, we receive notifications from Apple Pay and update the token for you.

automaticReloadPaymentRequest: {
  paymentDescription: "Card Top-up",
  automaticReloadBilling: {
    type: "final",
    label: "Automatic Top-up",
    amount: "10.00",
    paymentTiming: "automaticReload",
    automaticReloadPaymentThresholdAmount: "2.00",
  },
  billingAgreement: "Reload when below $2",
  managementURL: "https://your-domain.com/token-management"
}
recurringPaymentRequest

A dictionary that represents a request to set up a recurring payment, typically a subscription. See ApplePayRecurringPaymentRequest for more details.

Apple Pay issues an Apple Pay Merchant Token if the user's payment network supports merchant-specific payment tokens. Otherwise, Apple Pay issues a device token as usual.

Leave the field tokenNotificationURL empty. We set the value for you and handle token notifications on your behalf, i.e. when life-cycle updates to the merchant token, for example, when the card issuer or the user deletes the merchant token, occur, we receive notifications from Apple Pay and update the token for you.

recurringPaymentRequest: {
  paymentDescription: "Subscription",
  regularBilling: {
    type: "final",
    label: "Subscription",
    amount: "20.00",
    paymentTiming: "recurring",
    recurringPaymentStartDate: new Date("2022-01-01T00:00:00"),
    recurringPaymentIntervalUnit: "month",
    recurringPaymentIntervalCount: 6,
    recurringPaymentEndDate: new Date("2024-01-01T00:00:00")
  },
  billingAgreement: "Change $20 every six months starting on 01/01/2022 and ending on 01/01/2024",
  managementURL: "https://your-domain.com/token-management"
}
deferredPaymentRequest

A dictionary that represents a request to set up a deferred payment, such as a hotel booking or a pre-order. See ApplePayDeferredPaymentRequest for more details.

deferredPaymentRequest: {
  paymentDescription: "Hotel",
  deferredBilling: {
    type: "final",
    label: "After Trial Period",
    amount: "50.00",
    paymentTiming: "deferred",
    deferredPaymentDate: new Date("2024-01-01T00:00:00")
  },
  billingAgreement: "Charge $50 on 01/01/2024",
  managementURL: "https://your-domain.com/token-management"
}

Errors

Your handlers onShippingContactSelected and onPaymentAuthorized can return an array of errors if there is something wrong with the given shippingContact or billingContact. Each error can point to a specific problem in a contact field. The object structure is as follows:

ParameterDescription
code Must be one of the followings:
  • "shippingContactInvalid" - Shipping address or contact information is invalid or missing. Use contactField to indicate the exact field with the error.
  • "billingContactInvalid" - Billing address information is invalid or missing. Use contactField to indicate the exact field with the error.
  • "addressUnserviceable" - The merchant cannot provide service to the shipping address (for example, can't deliver to a P.O. Box). This code does not require contactField
contactField Must be one of the followings: "phoneNumber", "emailAddress", "name", "phoneticName", "postalAddress", "addressLines", "locality", "subLocality", "postalCode", "administrativeArea", "subAdministrativeArea", "country", "countryCode", if the code is "shippingContactInvalid" or "billingContactInvalid". Otherwise, this field is optional.
message A localized, user-facing string that describes the error.