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: "Estimated tax",
17      amount: 100,
18      // Hide the amount on the sheet until it's final
19      type: "pending",
20    }
21  ],
22});

Pending line items

Line items default to a final amount. For estimates such as tax or shipping that aren't final yet, set type: "pending" on the line item. The Apple Pay sheet shows the line as pending instead of displaying the amount. You can also return pending line items from onShippingAddressChange, onPaymentMethodChange, onCouponCodeChange, and prepareTransaction.

1const transaction = evervault.transactions.create({
2  amount: 1000,
3  currency: "USD",
4  country: "US",
5  merchantId: "merchant_8f3dc605aa5d",
6  lineItems: [
7    { label: "Item", amount: 900 },
8    { label: "Estimated tax", amount: 100, type: "pending" },
9  ],
10});

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  "paymentDataType": "3DSecure",
28  "transactionType": "oneOff",
29  "transactionId": "5ee9e294a2e79032ca7529b2050c2a878187c54a54f07559cff8281fb9b4716c",
30
31  "billingContact": {
32    "familyName": "Doe",
33    "givenName": "John",
34    "phoneticFamilyName": null,
35    "phoneticGivenName": null,
36    "emailAddress": "john.doe@example.com",
37    "phoneNumber": "1234567890",
38    "address": {
39      "addressLines": ["123 Main St", "Apt 4B"],
40      "administrativeArea": "State",
41      "country": "Country",
42      "countryCode": "XX",
43      "locality": "City",
44      "postalCode": "12345",
45      "subAdministrativeArea": "",
46      "subLocality": ""
47    }
48  },
49  "shippingContact": {
50    "familyName": "Doe",
51    "givenName": "John",
52    "phoneticFamilyName": null,
53    "phoneticGivenName": null,
54    "emailAddress": "john.doe@example.com",
55    "phoneNumber": "1234567890"
56  },
57  "shippingMethod": {
58    "id": "standard",
59    "label": "Standard Shipping",
60    "amount": 299,
61    "detail": "3-5 business days"
62  }
63}

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.

• paymentDataType reflects the Apple token format from the credentials API (for example 3DSecure).
• transactionType indicates the transaction category (oneOff, recurring, or disbursement) based on how you created the transaction.
• transactionId is Apple's identifier for the token, and comes from the PKPaymentToken header. Some payment gateways require it to be passed through, though it isn't used to authorize the transaction itself.
• billingContact and shippingContact are only populated when the transaction requested those contact fields.
• shippingMethod is populated when you configured shippingMethods and the customer selected one.
• phoneticFamilyName and phoneticGivenName are populated when the customer's Apple Wallet contact card includes a phonetic reading of their name (common in locales like Japan). If there's no phonetic reading, then these two values are null.

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

Restrict cards by issuer country

To limit payments to cards issued in specific countries, pass supportedCountries when initializing the Apple Pay component. Use ISO 3166 country codes. This maps to Apple Pay's supportedCountries field.

1const apple = evervault.ui.applePay(transaction, {
2  supportedCountries: ["US", "CA"],
3  ...
4});

Pass application data

You can attach opaque merchant data to the Apple Pay request with applicationData. The value must be a Base64-encoded string. Apple includes a hash of this data in the payment token so you can verify it server-side. See Apple's applicationData documentation.

1const apple = evervault.ui.applePay(transaction, {
2  applicationData: btoa(JSON.stringify({ orderId: "order_123" })),
3  ...
4});

Apple merchant identifier

By default, Evervault uses merchant.com.evervault.{merchantId} as the Apple Pay merchant identifier. This works with Evervault's domain verification and merchant-session API.

You can pass a custom appleMerchantId when initializing the component to match the iOS SDK surface:

1const apple = evervault.ui.applePay(transaction, {
2  appleMerchantId: "merchant.com.example.store",
3  process: async (paymentMethod) => {
4    // ...
5  },
6});

A custom identifier is only used by the browser to open the Apple Pay sheet. It doesn't change merchant validation — that still uses Evervault's registered identifier unless the custom ID is separately registered with Apple for your domain.

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

Offering shipping methods

For one-off payment transactions, you can pass shippingType and a shippingMethods list so the Apple Pay sheet lets the customer choose how their order is fulfilled. Amounts use the same smallest-currency-unit convention as line items (for example, cents). Mark one method with selected: true when the transaction amount already includes that method's cost. If none are marked selected, the first method is selected by default.

shippingMethods are only supported on one-off payment transactions — recurring and disbursement transactions reject them. Providing shippingMethods enables shipping on the sheet (requestShipping).

1const apple = evervault.ui.applePay(transaction, {
2  shippingType: "shipping", // "shipping" | "delivery" | "storePickup" | "servicePickup"
3  shippingMethods: [
4    {
5      id: "standard",
6      label: "Standard Shipping",
7      amount: 299,
8      detail: "3-5 business days",
9      selected: true,
10    },
11    {
12      id: "express",
13      label: "Express Shipping",
14      amount: 999,
15      detail: "1-2 business days",
16    },
17  ],
18  process: async (paymentMethod) => {
19    console.log(paymentMethod.shippingMethod);
20    // { id: "express", label: "Express Shipping", amount: 999, detail: "..." }
21  },
22});

When the customer selects a method, the sheet total is updated. Without a merchant callback, the SDK adjusts the total using the selected method's amount (treating the transaction amount as already including the initially selected method). To control totals yourself — for example when shipping cost depends on tax or address — use onShippingMethodSelected.

When relying on the internal recompute, your initial lineItems must include an entry whose label matches the selected method's label, or the shipping line won't be replaced correctly — use onShippingMethodSelected for full control.

Responding to shipping method changes

Pass onShippingMethodSelected to recompute the amount and line items when the customer picks a different shipping method. Return an updated amount and optional lineItems, the same shape as onShippingAddressChange.

1const apple = evervault.ui.applePay(transaction, {
2  shippingType: "shipping",
3  shippingMethods: [
4    {
5      id: "standard",
6      label: "Standard Shipping",
7      amount: 299,
8      detail: "3-5 business days",
9      selected: true,
10    },
11    {
12      id: "express",
13      label: "Express Shipping",
14      amount: 999,
15      detail: "1-2 business days",
16    },
17  ],
18  onShippingMethodSelected: async (method) => {
19    const lineItems = getLineItems(); // goods only
20    return {
21      amount: calculateTransactionAmount(lineItems) + method.amount,
22      lineItems: [...lineItems, { label: method.label, amount: method.amount }],
23    };
24  },
25});

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

Prefilling billing and shipping contact

If you know the customer's billing or shipping details (for example, from a logged-in checkout), you can prefill them on the Apple Pay sheet with billingContact and shippingContact. Set requestBillingAddress: true and requestShipping: true so the postal address fields appear on the sheet.

These options apply to payment and recurring transactions only. Disbursement transactions use requiredRecipientDetails on the transaction instead.

1const apple = evervault.ui.applePay(transaction, {
2  requestBillingAddress: true,
3  requestShipping: true,
4  billingContact: {
5    givenName: "Jane",
6    familyName: "Doe",
7    addressLines: ["123 Main St"],
8    locality: "San Francisco",
9    administrativeArea: "CA",
10    postalCode: "94105",
11    countryCode: "US",
12    country: "United States",
13  },
14  shippingContact: {
15    givenName: "Jane",
16    familyName: "Doe",
17    emailAddress: "jane.doe@example.com",
18    phoneNumber: "+14155550100",
19    addressLines: ["123 Main St"],
20    locality: "San Francisco",
21    administrativeArea: "CA",
22    postalCode: "94105",
23    countryCode: "US",
24    country: "United States",
25  },
26  process: async (paymentMethod) => {
27    // ...
28  },
29});

Responding to coupon code changes

To show a coupon field on the Apple Pay sheet, set supportsCouponCode: true. Optionally pass an initial couponCode. When the customer changes the code, onCouponCodeChange runs — return an updated amount and lineItems. To reject a code, return error with code set to couponCodeInvalid or couponCodeExpired.

1const apple = evervault.ui.applePay(transaction, {
2  supportsCouponCode: true,
3  couponCode: "",
4  onCouponCodeChange: async (code) => {
5    const normalized = code.trim().toUpperCase();
6
7    if (normalized === "SAVE20") {
8      return {
9        amount: 800,
10        lineItems: [
11          { label: "Item", amount: 1000 },
12          { label: "Coupon SAVE20", amount: -200 },
13        ],
14      };
15    }
16
17    if (normalized === "") {
18      return {
19        amount: 1000,
20        lineItems: [{ label: "Item", amount: 1000 }],
21      };
22    }
23
24    return {
25      amount: 1000,
26      lineItems: [{ label: "Item", amount: 1000 }],
27      error: {
28        code: "couponCodeInvalid",
29        message: "Unknown coupon code",
30      },
31    };
32  },
33  process: async (paymentMethod) => {
34    // ...
35  },
36});

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 customer (e.g., applying a discount collected on your own checkout page). You can do this by passing the prepareTransaction option when initializing the Apple Pay component. The prepareTransaction function returns a promise that resolves to an object with an updated amount and lineItems array.

To let customers enter a coupon on the Apple Pay sheet itself, use supportsCouponCode instead.

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.