Apple Pay

Enable Apple Pay as a payment method for your merchants

To test Apple Pay in our sandbox environment, configure your sandbox wallet according to Apple's testing guidelines.

Enabling Apple Pay for your merchants

Please contact your support representative to enable Apple Pay for your account.

Once Apple Pay support is enabled in your account, please follow the below steps

Step 1 - Select merchant from your partner portal and go to settings

Step 2 - Select Add Domain from the Apple Pay Section to start the merchant domain verification process. Please note that Apple Pay requires domain verification for each merchant.

Step 3 - Download the verification certificate from the Add Domain screen. After properly hosting the certificate file, select the "The file has been uploaded" checkbox and click the Add Domain button. If everything is correct, the domain will be verified and added to the merchant's account.

Using Apple Pay in your Web Application

For native app integration, please contact your assigned solution engineer for further implementation details

To use Apple Pay in your web application, the system must first verify the domain as described in the previous section.

This platform simplifies presenting Apple Pay during the checkout process in your web application. If you are already using the JS library, you only need to call an additional function to display the Apple Pay button.

To learn more about JS library, please see our guide.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Apple Pay Demo</title>
    <script src="https://console.payengine.co/js/1.0.0/embed.js?key=<your public key>" async></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/axios/0.22.0/axios.min.js" integrity="sha512-m2ssMAtdCEYGWXQ8hXVG4Q39uKYtbfaJL5QMTbhl2kc6vYyubrKHhr6aLLXW4ITeXSywQLn1AhsAaqrJl8Acfg==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>    
  </head>
  <body>
    <h4>Apple Pay</h4>
    <div id="button"></div>
    <script>
      const merchantId = "<Your Mercchant ID>";
      const amount = 10.00;

      //--> Send data to your backend after receving Apple Pay Token
      const submit = (token) => {
        axios
          .post(
            "<Your Back End Application>/api/charge",
            {
              merchant_id: merchantId,
              data: {
                cardToken: token,
                transactionAmount: String(amount),
              },
            }
          )
          .then((resp) => {
            //Handle Response from your backend
          })
          .catch((err) => {
            //Handle Error from your backend
          });
      };

      //--> Example of our library and Apple Pay
      window.onload = () => {
        PayEngine.ApplePay.configure({
          merchantId: merchantId,
          hmac: <HMAC>
          amount: amount,
          selector: "#button",
          buttonType: "buy", 
          buttonColor: 'black',
          //Remove the lines below if contact fields are not reqquired
          requiredShippingContactFields: [],
          requiredBillingContactFields: [],
          // This function called to provide result of Apple Pay Authorization
          callback: function (response, error) {
            if (!error) {
              //Handle Success here. Typically call your backend to call the card sale API
              submit(response.token);
            } else {
              //Handle Apple Pay Authorization Error
            }
          },
        });
      };
    </script>
  </body>
</html>

// Credit Card Sale
// Note that this call is not changed and can pass in Apple Pay Token just like Credit card tokens
exports.charge = async function (req, res) {
    try{
        const response = await axios.post(PayEngine_Server + "/api/payment/sale",
            {
                "merchant_id": req.body.merchantID,
                "data": {
                    "transactionAmount": req.body.amount,
                    "cardToken": req.body.token,
                    "currencyCode": "USD"
                }
            },
            {
                headers: {
                    'Content-type': 'application/json',
                    'Accept': 'text/plain',
                    'Authorization': 'Basic ' + secret_key
                }
            })
        console.log(response)
        res.json(response.data)
    }catch(error){
        res.json({error: error.response?.data ?? error})
    }
}

To erquest billing and/or shipping contact information associated with Apple Wallet please include the options in the requiredShippingContactFields and requiredBillingContactFields arrays.

"requiredShippingContactFields": [
    "postalAddress",
    "name",
    "phoneticName",
    "phone",
    "email"
]

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.

"requiredBillingContactFields": [
    "postalAddress"
]

You will receive the postal address as well as the user's name after the user authorizes the transaction.

The source of the information may be the user's Me contact card, the back of credit card in Wallet, or may be entered by the user directly into the payment sheet.

Sample Token Response

{
  "merchantId": "<YOUR MID>",
  "metadata": {
    "billingContact": {
      "addressLines": ["123 Main Street"],
      "administrativeArea": "TX",
      "country": "United States",
      "countryCode": "US",
      "familyName": "Doe",
      "givenName": "John",
      "locality": "Houston",
      "postalCode": "88065",
      "subAdministrativeArea": "",
      "subLocality": ""
    }
  },
  "token": "pe_sandbox_**************"
}

Presenting the Apple Pay button

As demonstrated in the example above, you can present Apple Pay as an option in your client app by calling the ApplePay.configure function. Please note that you need to provide the amount before calling this method. In a production environment, you also need to provide an HMAC value, similar to any other web component in your application.

PayEngine.ApplePay.configure({
  merchantId: <Your Merchant ID>,
  hmac: <HMAC>,
  amount: <Amount You want to charge i>,
  selector: "#applePayButton", 
  buttonType: "pay", 
  buttonColor: "default",
  callback: async function (response, error) {
    if (!error) {
        //Call Your backend server to execute sale API
    } else {
      // Handle error here
    }
  },
});

Customizing Apple Pay button

You can customize the label and color of your Apple Pay Button by providing buttonType and buttonColor attributes in Apple Pay configuration object.

buttonType: 'buy', // "add-money" | "buy" | "book" | "check-out" | "continue" | "contribute" | "donate" | "order" | "pay" | "plain" | 'reload' | 'rent' | 'set-up' | 'subscribe' | 'support' | 'tip' | 'top-up'
buttonColor: 'default', // "default" | "black" | "white"

Dynamic Pricing Setup with Apple Pay

Dynamic pricing allows you to adjust the total amount of a transaction based on user-selected shipping methods and shipping contacts. This section outlines how to implement dynamic pricing using the shippingMethods array, the onShippingContactSelected callback, and the onShippingMethodSelected callback in your Apple Pay integration.

Define shipping methods

Create an array of shipping methods that includes details such as the identifier, label, amount, and description. This array will be used to present shipping options to the user.

// Define shipping methods
const shippingMethods = [
  {
    identifier: "shipping-001",
    label: "$0.00: Free shipping",
    amount: 0.0,
    detail: "Free Shipping delivered in 5 business days.",
  },
  {
    identifier: "shipping-002",
    label: "$1.99: Standard shipping",
    amount: 1.99,
    detail: "Standard shipping delivered in 3 business days.",
  },
  {
    identifier: "shipping-003",
    label: "$2.99: Express shipping",
    amount: 2.99,
    detail: "Express shipping delivered in 1 business day.",
  },
];

// Configure button with shipping methods
PayEngine.ApplePay.configure({
  merchantId: <Your Merchant ID>,
  hmac: <HMAC>,
  amount: <Amount You want to charge i>,
  selector: "#applePayButton", 
  buttonType: "pay", 
  buttonColor: "default",
  shippingMethods: shippingMethods,
  callback: async function (response, error) {
    if (!error) {
        //Call Your backend server to execute sale API
    } else {
      // Handle error here
    }
  },
});

Handle shipping contact selection

Implement the onShippingContactSelected callback to dynamically adjust the available shipping options based on the user's selected shipping contact. This function will be triggered when the user selects a shipping address.

onShippingContactSelected: async (session, event) => {
  // Check the country code of the selected shipping contact
  if (event.shippingContact?.countryCode === "US") {
    // If shipping is not available for the selected country, return an error
    session.completeShippingContactSelection({
      newTotal: {
        label: "Total",
        amount: amount.toString(), // Base amount remains unchanged
      },
      errors: [new ApplePayError("shippingContactInvalid", "countryCode", "Shipping is not available for your location.")],
    });
  } else {
    // If shipping is available, complete the selection with the current total 
    // lineItems, and new shippingMethods
    
    // Simulate a server call to fetch newShippingMethods calculate the new total
    await new Promise((resolve) => setTimeout(resolve, 2000));
  
    session.completeShippingContactSelection({
      newShippingMethods: [
        {
          identifier: "shipping-002",
          label: "$3.99: Standard shipping",
          amount: 3.99,
          detail: "Standard shipping delivered in 3 business days.",
          selected: true // set this as default selected option
        },
        {
          identifier: "shipping-002",
          label: "$4.99: Standard shipping",
          amount: 4.99,
          detail: "Standard shipping delivered in 3 business days.",
        }
      ],
      newLineItems: [
        {
          label: "Product",
          amount: amount.toString(), // Base product amount
        },
        {
          label: "Shipping Fee",
          amount: 3.99.toString(), // Shipping fee amount
        },
      ],
      newTotal: {
        label: "Total",
        amount: amount.toString(), // Base amount remains unchanged
      },
    });
  }
},

Updating shipping contact properties

errors: a list of custom errors to display on the payment sheet.
newLineItems: an optional list of updated line items.
newShippingMethods: a list of shipping methods that are available to the updated shipping contact.
newTotal: the new total that results from a change in the shipping contact.

Handle shipping method selection

Implement the onShippingMethodSelected callback to dynamically adjust the total amount based on the selected shipping method. This function will be triggered when the user selects a shipping option

onShippingMethodSelected: async (session, event) => {
  // Simulate a server call to calculate the new total
  await new Promise((resolve) => setTimeout(resolve, 2000));

  // Calculate the shipping fee based on the selected method
  const shippingFee = parseFloat(event.shippingMethod.amount);
  const total = amount + shippingFee; // Update the total amount

  // Complete the shipping method selection with the new total
  session.completeShippingMethodSelection({
    newTotal: {
      label: "Total",
      amount: total.toString(), // Update the total amount as a string
    },
    newLineItems: [
      {
        label: "Product",
        amount: amount.toString(), // Base product amount
      },
      {
        label: "Shipping Fee",
        amount: shippingFee.toString(), // Shipping fee amount
      },
    ],
  });
},

Updating shipping method properties

newLineItems: an optional list of updated line items.
newTotal: the new total that results from a change in the shipping contact.

Complete payment method selection

Ensure that the total amount reflects any changes made during the shipping method selection. This is handled in the onPaymentMethodSelected callback.

onPaymentMethodSelected: (session, event) => {
  // calculate total and lineItems based on onShippingContactSelected and onShippingMethodSelected
  session.completePaymentMethodSelection({
    newLineItems: [
      ...newLineItems,
    ],
    newTotal: {
      label: "Total",
      amount: total.toString(), // Ensure the total is updated
    },
  });
},

Updating payment method properties

errors: a list of customized errors you provide that results from the user's change to the payment method.
newLineItems: an optional list of updated line items.
newShippingMethods: a list of shipping methods that results from the user's change to the payment method.
newTotal: the new total that results from a change in the shipping contact.

Param Definitions

ApplePayShippingMethod:

The Apple Pay sheet displays all the properties of a shipping method except identifier

@property {string} label - A human-readable label for the shipping method.
@property {string} detail - A human-readable description of the shipping method.
@property {string} amount - The cost of the shipping method.
@property {string} identifier - A unique identifier for the shipping method.

ApplePayLineItem

A line item in a payment request—for example, total, tax, discount, or grand total.

@property {ApplePayLineItemType} type - The type of line item.
@property {string} label - A human-readable label for the line item.
@property {string} amount - The amount of the line item.

ApplePayLineItemType

A type that indicates whether a line item is final or pending

The constant values are:

final: a line item representing the known,final cost
pending: a line item representing an estimated or unknown cost

PreviousRegistering a cloud connected device NextApple Pay in your native app

Last updated 1 month ago