Apple Pay on Web

Accept Apple Pay in your website using Finix.

Buyers that use Safari as their browser have the option to use Apple Pay as a payment method when making online purchases. This guide details how to start accepting Apple Pay on your website using Finix.

Apple Pay Demo

You can see a demo of Apple Pay on our sample store. All of the code on our sample store is available on GitHub here.

Log in to the Apple Developer Site

The Apple Pay button will not render in the Finix Sample Store unless the user is logged in on the Apple Developer site.

In this sample store, you can add a few items to your cart and click on Pay with Tokenization Form.

You'll see an express checkout button that will bring up the Apple Pay button. Our sample store uses sandbox credentials so you won't get charged.

Integration Steps

Step 1: Onboard with Apple

Start by familiarizing yourself with the prerequisites for using Apple Pay with Finix.

Step 2: Register on the Finix Dashboard

Before you can begin accepting Apple Pay, you need to first verify and register your domain with Apple. You can complete this step with the Finix Dashboard. After you've registered the domain, download the verification file from the file and host it on your website.

• Application Level
• Merchant Level

To register on the Finix Dashboard on the Application Level:

1. Log in to your Finix Dashboard and click Developer.
2. Click Alt Payment Methods tab.
3. Click Add Web Domain and follow the instructions to host the verification file.

Don't close the modal until you've hosted the verification file.

Do not click Submit on Step 3 in the modal unless you've uploaded the verification file generated by Finix in the steps below.

4. Enter a domain name.

5. Download the verification file.

6. Host the verification file at this location: /.well-known/apple-developer-merchantid-domain-association.

Step 3: Add the Apple Pay Library

After verifying and registering your domains with Apple, you need to add the Apple Pay Library. Including this script in your website allows your site to make calls to the Apple Pay API.

Apple Pay Library Snippet

<script src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>

Step 4: Add the Apple Pay Button

After you have added the Apple Pay Library, add an HTML element and name it apple-pay-button.

Please note that Apple requires the button to be named apple-pay-button

To demo all of the Apple Pay button styles, see Apple Pay's interactive demo.

Apple Pay Button

<style>
  apple-pay-button {
    --apple-pay-button-width: 150px;
    --apple-pay-button-height: 30px;
    --apple-pay-button-border-radius: 3px;
    --apple-pay-button-padding: 0px 0px;
    --apple-pay-button-box-sizing: border-box;
  }
</style>
<apple-pay-button
  buttonstyle="black"
  type="plain"
  locale="en"
></apple-pay-button>

Step 5: Create and Begin Apple Pay Session

Dues and Assessments

We recommend that you pass the address field listed in the steps below. If the address is not passed, you will be charged additional dues and assessments per transaction from the card network.

After adding an Apple Pay button, you need to instantiate the ApplePaySession by invoking the begin function. To collect a billing address from buyers, pass in requiredBillingContactFields.

Begin Apple Pay Session Function Arguments

Apple Pay Session

var createAndStartApplePaySession = function(description, amount) {

var applePaySession = new ApplePaySession(6, {
   "countryCode": "US",
   "currencyCode": "USD",
   "merchantCapabilities": ["supports3DS"],
   "supportedNetworks":  [ "visa", "masterCard", "amex", "discover"],
   "total":  { "label": description, "amount": amount }},
   "requiredBillingContactFields": ["postalAddress"]
 );

applePaySession.begin();
}

Step 6: Use a Buyer Identity

A buyer identity is required before you can proceed with the next steps. You can either create a new buyer identity through the Finix API, or use an existing one you’ve already created.

Buyer Identity Data

All buyer Identity fields are optional. However, Finix recommends including basic information (name, email, address, and phone) to make payment operations easier.

Use an existing buyer

1. Log in to your Finix Dashboard.
2. In the left sidebar, select Data Resources → Identities.
3. Search for the buyer identity you want to use.
   • Confirm the Role is Buyer.
   • Option to use filters to quickly narrow down results.
4. Copy the Buyer Identity (e.g. IDjWktr7BPDGhz4amrPJZoXg)

Create a new buyer

Buyer Identity Request

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/identities \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "entity": {
      "phone": "7145677613",
      "first_name": "John",
      "last_name": "Smith",
      "email": "finix_example@finix.com",
      "personal_address": {
        "city": "San Mateo",
        "country": "USA",
        "region": "CA",
        "line2": "Apartment 7",
        "line1": "741 Douglass St",
        "postal_code": "94114"
      }
    },
    "identity_roles": [
      "BUYER"
    ],
    "tags": {
      "key": "value"
    },
    "type": "PERSONAL"
  }'

Buyer Identity Response

{
  "id": "IDmkDvJfxZWMEK56FDFtbozo",
  "created_at": "2024-08-09T09:34:36.87Z",
  "updated_at": "2024-08-09T09:34:36.87Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "entity": {
    ...
  },
  "identity_roles": [],
  "tags": {
    "key": "value"
  },
  "type": "PERSONAL",
  "_links": {...}
}

Step 7: Validate an Apple Pay Merchant Session

Once you start an Apple Pay session, the next step is to validate and complete an Apple Pay merchant session. After creating a session, your server securely exchanges certificates with Apple’s servers and Finix to complete the setup.

To validate an Apple Pay session, set up the onvalidatemerchant function to capture the validation URL and send it, along with merchant details, to your backend. Your server will process the request with Finix and return Apple’s validation response. Finally, call completeMerchantValidation() with the response to authorize the session.

Sample Javascript

Validate Merchant Session

var validateMerchantSession = function(applePaySession) {
  applePaySession.onvalidatemerchant = function(event) {
    try {
      var validationURL = event.validationURL
      console.log("Validating merchant with url: " + validationURL );

if (validationURL) {
        var request = {
          provider: APPLE_PAY,
          validation_url: validationURL,
          merchant_identifier: merchantIdentity,
          domain_name: "www.finixtestmerchant.com",
          display_name: "Finix Test Merchant"
        }
        fetch(// call to your server which would then call Finix's /apple_pay_sessions {
          method: "POST",
          request,
          headers
        }).then((response) => {
          const sessionDetails = response['session_details']
          var merchantSession = JSON.parse(sessionDetails);
          applePaySession.completeMerchantValidation(merchantSession);
        })
      } else {
        console.log("Merchant validation failed");
      }
    }
    catch(err) {
      console.log(err);
      throw err;
    }
  }
}

Step 8: Create a Payment Instrument

After successful merchant validation, Apple Pay prompts the user for authentication with either Touch ID, Face ID, or device passcode.

When the user authorizes the payment, the onpaymentauthorized function provides an encrypted token, which your app then sends to your backend for processing with Finix. Your backend returns the processing result, which you use to call completePayment() and finalize the Apple Pay session.

Create Payment Token

var processPayment = function (applePaySession) {
  applePaySession.onpaymentauthorized = function (event) {
    try {
      var paymentToken = event.payment;
      if (paymentToken) {
        console.log("Payment token from Apple: " + paymentToken);
        // extract billing details
        ...
        applePaySession.completePayment(applePaySession.STATUS_SUCCESS);
        console.log(
          "Finix processed transaction successfully with token: " +
            paymentToken,
        );
      } else {
        console.log(
          "Payment token from Apple is null - payment failed to process.",
        );
        applePaySession.completePayment(applePaySession.STATUS_FAILURE);
      }
    } catch (err) {
      console.log(err);
      throw err;
    }
  };
};

Step 9: Create a Payment

Similar to other Finix transactions, after the Payment Instrument is created, you can use the instrument and create a transfer or an authorization to process transactions.

Example Transfer Request

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
        "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
        "currency": "USD",
        "amount": 662154,
        "source": "PImE5ZhGZJNFy14DtX8wX6f6",
    }'

Example Transfer Response

{
  "id": "TR29av3LN1TAGPbXscsup1tt",
  "amount": 662154,
  "tags": {},
  "state": "SUCCEEDED",
  "trace_id": "34f40e87-2599-414b-874b-f472790ff521",
  "currency": "USD",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "source": "PImE5ZhGZJNFy14DtX8wX6f6",
  "destination": null,
  ...
}