Apple Pay

Create a merchant

Before you can use Apple Pay, you need to create a Merchant record to use for the transaction. You can create a merchant from inside the payments tab in the Evervault Dashboard or via the Merchants API.

Verify your domain with Apple

After creating a merchant, Apple needs to verify the domains associated with it. You can add and verify your domains using the Evervault Dashboard under Payments > Apple Pay.

Alternatively, you can serve this identifier file from /.well-known/apple-developer-merchantid-domain-association on your domain, then register your domain via the Merchant API.

You can check the status of your domain verification with Apple via the Dashboard or by using the Merchant API. It may take up to 10 minutes for the verification to complete.

Install the SDK

Our JavaScript SDK is distributed from our CDN, and can be installed by placing this script tag in the head of your HTML file. The SDK must be loaded directly from our CDN and cannot be bundled with your application or self hosted.

1<script src="https://js.evervault.com/v2"></script>

Once the SDK is installed, initialize it using your Team ID and App ID. You can find these in the Evervault Dashboard.

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");

You can also install Evervault via the @evervault/js package on npm. This package is a light wrapper which handles loading the SDK from our CDN and also provides TypeScript definitions.

1import { loadEvervault } from "@evervault/js";
2
3const evervault = loadEvervault("<TEAM_ID>", "<APP_ID>");

Create a transaction

Next, you will need to create a transaction to describe the payment you want to process. You will need to provide the amount, currency, country, and merchant details for the transaction. With Apple Pay a transaction can be a Payment Transaction or a Disbursement Transaction. You can pass either transaction type to the Apple Pay component.

1const transaction = evervault.transactions.create({
2  amount: 1000,
3  currency: "USD",
4  country: "US",
5  merchantId: "merchant_8f3dc605aa5d",
6  lineItems: [
7    {
8      label: "Example Item 1",
9      amount: 800,
10    },
11    {
12      label: "Example Item 2",
13      amount: 100,
14    },
15    {
16      label: "Tax",
17      amount: 100,
18    }
19  ],
20});

Mount the Apple Pay component

Now that you have created a transaction, you can create and mount the Apple Pay component to display the Apple Pay button to your users. The Apple Pay component takes the transaction you created as a first argument and an options object with a process function that will be called with the encrypted payment method when the user completes the payment. The process function is an asynchronous function that takes the encrypted payment method as the first argument and an object with a fail function as the second argument. The fail function can be called with an error message to display an error to the user.

1const apple = evervault.ui.applePay(transaction, {
2  process: async (paymentMethod, { fail }) => {
3    try {
4      console.log(paymentMethod.networkToken.number);
5      // ev:Tk9D:hY5KJanIPOHBoI8S:AsnnjRl0FDe2zEddBAQG/eI2vN+b...:$
6
7      // Send the encrypted payment method to your backend for processing
8    } catch (error) {
9      fail({
10        message: "Cannot pay with payment credentials",
11      });
12    }
13  },
14});
15
16apple.on("cancel", () => {
17  console.log("Apple Pay canceled");
18});
19
20apple.on("error", (error) => {
21  console.error("Apple Pay error", error);
22});
23
24apple.on("success", () => {
25  console.log("Apple Pay success");
26});
27
28apple.on("ready", () => {
29  console.log("Apple Pay button is ready!");
30});
31
32const availability = await apple.availability();
33
34if (availability === "available") {
35  // Mount the Apple Pay component to a container element
36  apple.mount("#apple-pay");
37} else {
38  // Apple pay is not available on the device
39}

Abort an active session

If the user changes their shipping address to a country that uses a different currency, you cannot update the currency on an open Apple Pay sheet. Call abort() to dismiss the sheet, update your transaction with the new currency and country, then let the user tap the Apple Pay button again. Note that abort() only works before the user authorizes payment — once they've authorized, use fail() in the process callback instead.

1const apple = evervault.ui.applePay(transaction, {
2  requestShipping: true,
3  onShippingAddressChange: async (address) => {
4    const newCurrency = currencyForCountry(address.country);
5
6    if (newCurrency !== transaction.details.currency) {
7      await apple.abort();
8      return { amount: 0, lineItems: [] };
9    }
10
11    return {
12      amount: calculateTotal(address),
13      lineItems: getLineItems(address),
14    };
15  },
16  process: async (paymentMethod) => {
17    // ...
18  },
19});
20
21apple.on("cancel", () => {
22  // Update checkout form currency/country and recreate the transaction if needed
23});

Process the payment

The process function is called when the user authorizes the payment. This is where you should finalize the payment with your payment processor. The encrypted payment method will be passed to the process function as the first argument. This should be sent to your backend which can then use Relay to safely send the decrypted payment method to any payment provider.

The full encrypted payment method object contains the following data:

1{
2  "networkToken": {
3    "number": "ev:Tk9D:hY5KJanIPOHBoI8S:AsnnjRl0FDe2zEddBAQG/eI2vN+b...:$",
4    "expiry": {
5      "month": "12",
6      "year": "31"
7    },
8    "tokenServiceProvider": "Apple"
9  },
10  "card": {
11    "brand": "visa",
12    "lastFour": "1234",
13    "displayName": "visa 1234",
14    "paymentMethodType": "debit",
15    "funding": "debit",
16    "segment": "consumer",
17    "country": "ie",
18    "currency": "eur",
19    "issuer": "Revolut Bank Uab"
20  },
21  "cryptogram": "ev:Tk9D:vUVeybXqrA9Ds4rZ...=:$",
22
23  // The ECI value is optional with Apple Pay.
24  // Learn more here: https://developer.apple.com/documentation/passkit/payment-token-format-reference#Detailed-payment-data-keys-3D-Secure
25  "eci": "5",
26
27  // Only available on disbursement transactions
28  "billingContact": {
29    "familyName": "Doe",
30    "givenName": "John",
31    "emailAddress": "john.doe@example.com",
32    "phoneNumber": "1234567890",
33    "address": {
34      "addressLines": ["123 Main St", "Apt 4B"],
35      "administrativeArea": "State",
36      "country": "Country",
37      "countryCode": "XX",
38      "locality": "City",
39      "postalCode": "12345",
40      "subAdministrativeArea": "",
41      "subLocality": ""
42    }
43  }
44}

The optional card.paymentMethodType field is one of credit, debit, prepaid, or store. It reflects the funding type of the card the customer selected in Apple Wallet (from the Payment Request API’s payment method). Prefer it over BIN-derived metadata such as funding when you need to know how the user intends to pay: for dual-network cards, BIN-based fields can still report credit even when the customer picked their debit card. If Apple does not provide a type, the field is omitted.

Use Apple Pay with your PSP

You can use Evervault's Apple Pay integration with any PSP. This means you:

• Don't use your PSP's Apple Pay integration.
• Use network tokens (provided by Evervault) with your PSP's APIs.

Evervault generates network tokens for Apple Pay transactions, not your PSP. After you have the network token, use it for all payments, retries, etc. with your PSP. There's no additional configuration (e.g., certificates) with your PSP or Apple needed. Most PSPs have network token APIs and parameters for passing network token data. Like other 3rd party API calls, use Relay to decrypt network token data and send it to your PSP.

Availability

You can use the availability method to check if Apple Pay is available on the device. This method returns a promise that resolves to a string indicating the availability status.

• available - Apple Pay is available on the device.
• unavailable - Apple Pay is supported but not currently available on the device.
• unsupported - Apple Pay is not supported on the device.

1const apple = evervault.ui.applePay(transaction, { ...  })
2const availability = await apple.availability();
3console.log(availability);
4// "available"

In order for Apple Pay to be available, the user's device or browser must meet the following requirements:

• The web page must be served over HTTPS.
• Have at least one card added to their Apple Wallet.
• The user must be using a compatible browser. Apple Pay is supported on Safari, Chrome, and Edge.
• If using Safari:
  • The user must have Apple Pay enabled in their browser settings. Settings > Advanced > Allow websites to check for Apple Pay and Apple card.
  • The user must have access to the biometric authentication controls on their device. If using a laptop this means the laptop must not be in clamshell mode and the user must have access to the Touch ID sensor.

Customization

Apple Pay allows you to customize the appearance of the payment button with various predefined styles. These can be passed as additional options when initializing the Apple Pay component. You can see the available options in the JS SDK documentation.

1const apple = evervault.ui.applePay(transaction, {
2  style: "black",
3  borderRadius: 10,
4  ...
5});

Configure card networks

Apple Pay allows you to specify the card networks that are supported by your merchant. This can be done by passing the allowedCardNetworks options when initializing the Apple Pay component. You can see the available options in the Apple Pay docs. Please check with your payment processor to ensure that the card networks you specify are supported.

1const apple = evervault.ui.applePay(transaction, {
2  allowedCardNetworks: ["visa", "mastercard"],
3  ...
4});

Transaction updates

Apple Pay allows you to update the transaction after a user has launched the Apple Pay modal. This can be done by leveraging the options described below.

Responding to shipping address changes

You may want to alter the transaction amount based on the shipping address provided by the user. Apple Pay allows you to respond to changes in the shipping address after a user has launched the Apple Pay modal. This can be done by passing the requestShipping and onShippingAddressChange options when initializing the Apple Pay component. The onShippingAddressChange function should return an object with an updated amount and lineItems array.

1const apple = evervault.ui.applePay(transaction, {
2  requestShipping: true,
3  onShippingAddressChange: async (newAddress) => {
4    const lineItems = getLineItems();
5    const transactionAmount = calculateTransactionAmount(lineItems);
6
7    const shippingAmount = await calculateShipping(newAddress.country);
8    const shipping = {
9      label: "Shipping",
10      amount: shippingAmount,
11    };
12    return {
13      amount: transactionAmount + shippingAmount,
14      lineItems: [...lineItems, shipping],
15    };
16  },
17});

Responding to billing address changes

You can leverage the requestBillingAddress and onPaymentMethodChange options when initializing the Apple Pay component to respond to changes in the billing address.

1const apple = evervault.ui.applePay(transaction, {
2  requestBillingAddress: true,
3  onPaymentMethodChange: async (event) => {
4    const lineItems = getLineItems(1);
5    if (event.billingContact?.country === getCurrentCountry()) {
6      lineItems.push({ label: "National tax", amount: 1000 });
7    } else {
8      lineItems.push({ label: "International tax", amount: 2000 });
9    }
10    const total = lineItems.reduce((acc, item) => acc + item.amount, 0);
11    return {
12      amount: total,
13      lineItems,
14    };
15  },
16});

Updating a transaction when Apple Pay is triggered

In some scenarios, you might want to perform an action before presenting the Apple Pay modal to the user, e.g., offering a discount code. You can do this by passing the prepareTransaction option when initializing the Apple Pay component. The prepareTransaction function should return a promise that resolves to an object with an updated amount and lineItems array.

1const apple = evervault.ui.applePay(transaction, {
2  prepareTransaction: async () => {
3    const updatedTransaction = await offerDiscount();
4    return {
5      amount: updatedTransaction.amount,
6      lineItems: updatedTransaction.lineItems,
7    };
8  },
9});

Content security policy (CSP)

If you are using a Content Security Policy (CSP), you will need to add the following directives to allow the Evervault SDK to function correctly.

1script-src https://js.evervault.com;
2connect-src https://keys.evervault.com https://api.evervault.com;
3frame-src https://ui-components.evervault.com;

Notes

• The Apple Pay UI Component is currently not supported on devices in Mainland China.
• The Apple Pay UI Component requires a secure context (HTTPS) to function correctly.