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). Loading the Apple Pay button via COPYandPAY payment widget is just like loading any other brand, i.e. in step 2, APPLEPAY 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.

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 must be specified as a brand.

See an example below.

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

Todo Java Script

Apple Pay options

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

The Apple Pay Javascript API version.

For the best compatibility, use the lowest possible version number that supports the features required. The versions which operating systems first support are listed below:

  • 1 – macOS 10.12, iOS 10.0
  • 2 – macOS 10.12.1, iOS 10.1
  • 3 – macOS 10.13, iOS 11.0
  • 4 – macOS 10.14.1, iOS 12.1
  • 5 – macOS 10.14.2, iOS 12.1.1
  • 6 – macOS 10.14.4, iOS 12.2
1version: 3
displayNameNoA 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/AdisplayName: “MyStore”
totalYes/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.” }
currencyCodeYes/NoThe 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”
checkAvailabilityNo

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.
  • “canMakePaymentsWithActiveCard” – 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 setting the option merchantIdentifier.
canMakePaymentscheckAvailability: “canMakePaymentsWithActiveCard”
merchantIdentifierYes/NoThe merchant ID created when the merchant enrolled in Apple Pay. This parameter is required when checkAvailability is “canMakePaymentsWithActiveCard”N/AmerchantIdentifier: “com.company”
styleNoThe Apple Pay button style. The value must be one of the followings: “white-with-line”, “white”, “black”.white-with-linestyle: “black”
countryCodeNoThe merchant’s two-letter ISO 3166 country code.wpwlOptions.localecountryCode: “US”
merchantCapabilitiesNo

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.

supports3DSmerchantCapabilities: [“supports3DS”, “supportsCredit”]
supportedNetworksNo

The payment networks supported by the merchant. The supported values are: “amex”, “cartesBancaires” (4), “chinaUnionPay”, “discover”, “eftpos” (4), “electron” (4), “elo” (5), “interac”, “jcb” (2), “mada” (5), “maestro” (4), “masterCard”, “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”]
lineItemsNo

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/AlineItems: [{
label: “Bag Subtotal”,
amount: “35.00”
}, {
label: “Free Shipping”,
amount: “0.00”
}, {
label: “Estimated Tax”,
amount: “3.06”
}]
shippingMethodsNo

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.
N/AshippingMethods: [{
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”,
}]
shippingTypeNoIndicate how purchased items are to be shipped. The value must be one of the followings: “shipping”, “delivery”, “storePickup”, “servicePickup”.shippingshippingType: “shipping”
supportedCountriesNo

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/AsupportedCountries: [“US”]
requiredShippingContactFieldsNoAn array of shipping information that you require from the user to fulfill the order. The supported field names are: “email”, “name”, “phone”, “postalAddress”, and starting from version 3: “phoneticName”.N/ArequiredShippingContactFields: [ “postalAddress”, “email” ]
requiredBillingContactFieldsNoAn array of billing information that you require from the user to process the transaction. The supported field names are: “email”, “name”, “phone”, “postalAddress”, and starting from version 3: “phoneticName”.N/ArequiredBillingContactFields: [ “postalAddress” ]
submitOnPaymentAuthorizedNo

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 to request “email”, “name”, “phone”, and “postalAddress” from Apple Pay.

N/AsubmitOnPaymentAuthorized: [ “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
onCancelAn 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 () {
}
onPaymentMethodSelectedAn 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”.
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”
    }]
  };
}
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 contains only the first 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”
    }]
  };
}
onShippingMethodSelectedAn 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”
    }]
  };
}
onPaymentAuthorizedAn 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. For each object, the possible properties are:
  • emailAddress
  • familyName
  • givenName
  • phoneNumber
  • phoneticFamilyName – Typically used for transactions in Japan. Available in Apple Pay JS API version 3.
  • phoneticGivenName – Typically used for transactions in Japan. Available in Apple Pay JS API version 3.
  • addressLines – The street portion of the address for the contact.
  • locality – The city 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.
  • administrativeArea – The state for the contact.
  • subAdministrativeArea – The subadministrative area (such as a county or other region) in a postal address.
  • postalCode – The zip code or postal code, where applicable, for the contact.
  • country – The name of the country for the contact.
  • countryCode – The contact’s two-letter ISO 3166 country code.
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).

Todo Java Script

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
codeMust 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
contactFieldMust 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.
messageA localized, user-facing string that describes the error.