Apple Pay

Apple Pay

Introduction

Loading the Apple Pay button via Primeiro Pay 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.

Fast Checkout

Sometimes you might want to display the Apple Pay button early on the payment workflow where you do not yet have a checkout ID. Usually, the shopper can decide whether to continue with the normal checkout, or to immediately pay with Apple Pay.

It is possible to display the Apple Button first and create a checkout ID later. In step 2:

  • Use paymentWidgets.js without a checkout ID
    <script src="https://test.oppwa.com/v1/paymentWidgets.js"></script>
  • Define a callback function in wpwlOptions.createCheckout to create a checkout
We will call the callback function once the Apple Pay button is clicked. The function should return a checkout ID, or a promise that will return a checkout ID. Specifically, the returned object can be any thenable object. In particular, both JavaScript Promise and jQuery Promise are supported.

Example:

wpwlOptions.createCheckout = function() {
    // Call your server to create a checkout
    return $.post("https://your.server")
    .then(function(response) {
        // Assume that your server returned the response containing checkoutId
        return response.checkoutId;
    });
};

Options

Apple Pay provides a list of features that can be used via the API Reference.

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

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.

The full reference of all available options is shown below in this page.

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

References

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

ParameterDescriptionExamples
version

The Apple Pay Javascript API version. The default version number is 1.

Safari 11 supports Apple Pay versions 1 through 3 on:

  • Devices running iOS 11.
  • Computers running macOS 10.13.
For computers running a version of macOS prior to 10.13, Safari 11 supports only Apple Pay versions 1 and 2.
version: 3
displayName 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. displayName: "MyStore"
total 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.
  • 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".
total: { label: "COMPANY, INC." }
currencyCode The three-letter ISO 4217 currency code for the payment. If not specified, the currency from the checkout is used. currencyCode: "USD"
checkAvailability 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.
The default value is "canMakePayments".
checkAvailability: "canMakePaymentsWithActiveCard"
merchantIdentifier The merchant ID created when the merchant enrolled in Apple Pay. This parameter is required when checkAvailability is "canMakePaymentsWithActiveCard" merchantIdentifier: "com.company"
style The Apple Pay button style. The value must be one of the followings: "white-with-line", "white", "black". The default value is "white-with-line". style: "black"
countryCode The merchant’s two-letter ISO 3166 country code. The default is the value set in wpwlOptions.locale. countryCode: "US"
merchantCapabilities 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. The default value is ["supports3DS"].
merchantCapabilities: ["supports3DS", "supportsCredit"]
supportedNetworks The payment networks supported by the merchant. The supported values are: "amex", "chinaUnionPay", "discover", "jcb", "masterCard", "privateLabel", "visa". Note that "jcb" is only available starting in version 2. The default value is ["amex", "discover", "masterCard", "visa"]. supportedNetworks: ["amex", "chinaUnionPay", "discover", "jcb", "masterCard", "visa"]
lineItems 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.
lineItems: [{
  label: "Bag Subtotal",
  amount: "35.00"
}, {
  label: "Free Shipping",
  amount: "0.00"
}, {
  label: "Estimated Tax",
  amount: "3.06"
}]
shippingMethods 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.
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 Indicate how purchased items are to be shipped. The value must be one of the followings: "shipping", "delivery", "storePickup", "servicePickup". The default value is "shipping". shippingType: "shipping"
supportedCountries

An array of supported countries. It 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.
supportedCountries: ["US"]
requiredShippingContactFields An 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 in version 3: "phoneticName". requiredShippingContactFields: [ "postalAddress", "email" ]
requiredBillingContactFields An 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 in API version 3: "phoneticName". requiredBillingContactFields: [ "postalAddress" ]
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".
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.
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.
onShippingContactSelected:
function (shippingContact) {
  // Calculate new costst
  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. 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"
  • 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
}

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.
Example:
wpwlOptions.applePay.onPaymentAuthorized = function(payment) {
    // Inspected payment.shippingContact.postalCode and found out that it is invalid.
    return {
        status: "FAILURE",
        errors: [{
            code: "shippingContactInvalid",
            contactField: "postalCode",
            message: "ZIP Code is invalid"
        }]
    };
};

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"
        };
    });
};