Pay.js v2 Apple Pay™ Entry Reference

Please Note: This page includes references to features that are still under development. For the currently-supported feature set, see the Pay.js v1 documentation (previously Client JS).

Config Options

The Pay.js Apple Pay Entry can be configured with almost all of the options that Apple Pay provides. This allows you to customize the button appearance, set requirements for billing info, accept discount codes, provide shipping options, etc. Here we have listed any of the fields that are required from you, as well as those that the Pay.js library will pre-set, for all other options see the Apple Pay Documentation.

interface ApplePayConfig {
    targetDiv: string;
    displayName: string;
    paymentRequest: PaymentRequest;
    merchantId?: string;
    extended_response?: boolean;
    applePayBtn?: ApplePayBtn
};

ApplePayConfig

This is the main configuration object used by Pay.js to configure your Apple Pay instance.

Property	Type	Necessity	Description
targetDiv	string	Required	The target div element where the Apple Pay button should be appended as a child
displayName	string	Required	The business name that will be displayed on the Apple Pay payment sheet.
paymentRequest	PaymentRequest	Required	A request for payment, which includes information about payment-processing capabilities, the payment amount, and shipping information.
merchantId	string	Optional	The Apple Merchant ID you wish to be associated with this integration. If nothing is provided in the config, the deafult configuration on your merchant account (Settings > Apple Pay) will be used.
extended_response	boolean	Optional	If set to true the response from client.getPaymentKey() will be an object containing more detailed payment data in addition to the payment_key. The default is false which will only return the payment_key as a string.
applePayBtn	ApplePayBtn	Optional	Customize the look of the Apple Pay button.

PaymentRequest

This object will contain all of the payment data Apple needs to generate the payment sheet. For more info and additional options like requiredBillingContactFields and lineItems see Apple's documentation here: ApplePayPaymentRequest. Any of the properties included in Apple's documentation can be included here as well, we are only listing those that are required.

Property	Type	Necessity	Description
merchantCapabilities	ApplePayMerchantCapability	Pre-Set	An array of the payment capabilities that the merchant supports, such as credit or debit. The Pay.js library will set this as [ "supports3DS" ].
supportedNetworks	string[]	Pre-Set	The payment networks the merchant supports. The Pay.js library will set this as [ "amex", "discover", "jcb", "masterCard", "visa" ]
total	Total	Required	A line item that represents the total for the payment.
countryCode	string	Required	The merchant’s two-letter ISO 3166 country code.
currencyCode	string	Required	The three-letter ISO 4217 currency code for the payment.

Total

This object contains the final line item with the total amount that the customer is being charged. See Total for more info.

Property	Type	Necessity	Description
label	string	Required	Provide a business name. Use the same business name people see when they look for the charge on their bank or credit card statement, for example: Test Company.
type	string	Required	Must be set to final.
amount	string	Required	The total amount to be charged. Must be greater than zero. Ex. 1.00

ApplePayBtn

This object contains custom styling options for the Apple Pay button. Be sure to follow the Apple Pay Human Interface Guidelines whenever displaying the Apple Pay button.

Property	Type	Necessity	Description
type	string	Optional	The type of button you wish to display. For a list of options, see Apple's documentation here
color	string	Optional	The color scheme of the button. For a list of options, see Apple's documentation here

Status Change Events

The Pay.js Apple Pay Entry will send out events that you can listen for and assign a callback function using the on() function as shown below. A list of events and their descriptions can also be found below.

// listen for Apple Pay to be successfully completed
applePay.on('applePaySuccess', function () {
    // do something
});

Status Change Events

Event Name	Description
applePaySuccess	The Apple Pay session was completed successfully, and the customer is ready to pay.
applePayError	Something went wrong.
applePayCancelled	The user cancelled the Apple Pay session.
applePayPaymentAuthorized	The user authorized Apple Pay payment with Touch ID, Face ID, or a passcode. Callback must call completePayment() completion method. See ApplePayPaymentAuthorizedEvent for more info on how this is used.
applePayPaymentMethodSelected	The user selected a new payment method. Callback must call completePaymentMethodSelection() completion method. See ApplePayPaymentMethodSelectedEvent for more info on how this is used.
applePayCouponCodeChanged	The user entered or updated a coupon code. Callback must call completeCouponCodeChange() completion method. See ApplePayCouponCodeChangedEvent for more info on how this is used.
applePayShippingContactSelected	The user selected a shipping contact in the payment sheet. Callback must call completeShippingContactSelection() completion method. See ApplePayShippingContactSelectedEvent for more info on how this is used.
applePayShippingMethodSelected	The user selected a shipping method. Callback must call completeShippingMethodSelection() completion method. See ApplePayShippingMethodSelectedEvent for more info on how this is used.

The events applePayPaymentAuthorized, applePayPaymentMethodSelected, applePayCouponCodeChanged, applePayShippingContactSelected, and applePayShippingMethodSelected all originate from the Apple Pay JS API.and are being passed through by the Pay.js library to allow for updating the final price when changes are made to the session. The callback for these events are called with an argument containing information about the session so that you can determine if any changes need to be made. Then a specific completion method needs to be called within 30 secondsin order for the Apple Pay session to continue. A basic example is shown below, but more information for each event can be found in the Apple Pay on the Web documentation.

applePay.on('applePayPaymentMethodSelected', function (event) {
    // check event for changes (not included here)

    // create update object
    const applePayPaymentMethodethodUpdate = {
        newTotal: {
            label: "updated with payment method",
            amount: "1.00"
        }
    }

    // call completion method 
    applePay.completePaymentMethodSelection(applePayPaymentMethodethodUpdate);
});