# 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](https://finixsamplestore.com/). All of the code on our sample store is available on GitHub [here](https://github.com/finix-payments/accept-a-payment).

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](https://docs.finix.com/guides/online-payments/digital-wallets/apple-pay) 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](https://docs.finix.com/guides/online-payments/digital-wallets/apple-pay):

1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login) 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

```html
<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`

| Field | Type | Description |
| --- | --- | --- |
| `buttonstyle` | _string_, **optional** | Color of the button. Available values are **black**, **white**, and **white-outline** |
| `type` | _string_, **required** | There are a variety of button types that you can use on your website to initiate the transaction.<br>[Available Button Types](https://developer.apple.com/documentation/applepayontheweb/applepaybuttontype) - `Buy` (default), `Plain`, `Add Money`, `Book`, `Checkout`, `Continue`, `Contribute`, `Donate`, `Order`, `Pay`, `Reload`, `Rent`, `Set Up`, `Subscribe`, `Support`, `Tip`, `Top Up`. |
| `locale` | _string_, **required** | Set the language of the button. |

To demo all of the Apple Pay button styles, see [Apple Pay's interactive demo](https://applepaydemo.apple.com/).

Apple Pay Button

```html
<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

| Field | Type | Description |
| --- | --- | --- |
| `countryCode` | _string_, **optional** | The ISO country code. |
| `currencyCode` | _string_, **required** | The currency code of the locale. |
| `merchantCapabilities` | _string_, **required** | The payment types, such as credit or debit, supported by the merchant. The value **supports3DS** is required. |
| `supportedNetworks` | _string_, **optional** | The payment networks the merchant supports. <br>**Included Networks**: Amex, Discover, JCB, Discover, Mastercard, Visa. |
| `total` | _object_, **required** | The **label** field is a short, localized description of the line item. <br> The **amount** field is the monetary amount of the line item that follows this format: **0.00** |
| `requiredBillingContactFields` | _string_, **optional** | Pass in **postalAddress** to obtain a postal address as well as the buyer's name after the buyer authorizes the transaction. If you do not retrieve the address to pass to Finix, fees will apply. |

Apple Pay Session

```javascript
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](https://finix.payments-dashboard.com/Login).
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

```bash
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

```json
{
  "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](https://docs.finix.com/api/payment-instruments/createapplepaysession). 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

```javascript
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

```javascript
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`](https://docs.finix.com/api/transfers) or an [`authorization`](https://docs.finix.com/api/authorizations/createauthorization) to process transactions.

Example Transfer Request

```bash
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

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