---
title: "Using Apple Pay (API)"
description: "Step-by-step implementation guide for integrating Apple Pay via the direct KOMOJU Payments API, including merchant validation and payment authorization."
url: "https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/apple-pay/using-apple-pay-api"
source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/apple-pay/using-apple-pay-api.md"
language: en
last_modified: "2026-01-14"
---

# Introduction

Apple Pay can be easily integrated using KOMOJU Hosted Pages or Hosted Fields. However, integrating Apple Pay via the **KOMOJU API** requires additional setup to comply with Apple Pay’s merchant validation and security requirements.

This document describes the Apple Pay integration flow and provides step-by-step instructions for implementing Apple Pay using the KOMOJU API.

# Integration Overview

To integrate Apple Pay using the KOMOJU API, complete the following steps:

1. Register all domains and subdomains that will be used for Apple Pay, following the same procedure described on [the Hosted Fields page](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/apple-pay/using-apple-pay.md#hosted-fields).
2. Add the Apple Pay button to your checkout page.
3. Perform merchant validation by calling **KOMOJU’s Validate Merchant API** from your backend.
4. Create a payment by calling the **KOMOJU Payments API** with the Apple Pay payment token.

## Sequence Overview

The following sequence diagram illustrates the Apple Pay integration flow using the KOMOJU API.

![Apple Pay API Integration Sequence Diagram](https://docs.priv.staging.komoju-dev.tools/apple-pay_using-apple-pay-api_1.png)

---

# Implementation Guide

## Frontend Integration

### 1. Add the Apple Pay button

Use Apple’s JavaScript library to render the Apple Pay button.
For information about button customization and implementation details, refer to Apple’s official demo:
[Apple Pay on the Web Interactive Demo](https://applepaydemo.apple.com/)

### 2. Perform merchant validation

When an Apple Pay session is created, Apple invokes the `onvalidatemerchant` callback and provides a `validationURL`.

To proceed, the merchant must perform merchant validation by calling **KOMOJU’s Validate Merchant API** from the backend.

> ⚠️ **Warning:** Merchant validation requires a secret key and must not be performed directly from the frontend.

**Example:**

```javascript
const applePaySessionRequest = {
  countryCode: "JP",
  currencyCode: "JPY",
  merchantCapabilities: ["supports3DS"],
  supportedNetworks: ["visa", "masterCard"],
  total: {
    label: "Apple Pay Demo",
    amount
  }
};

const session = new ApplePaySession(1, applePaySessionRequest);

session.onvalidatemerchant = async event => {
  try {
    const response = await fetch("/api/validate_merchant", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        validation_url: event.validationURL
      })
    });

    if (!response.ok) {
      throw new Error("Merchant validation failed");
    }

    const merchantSession = await response.json();
    session.completeMerchantValidation(merchantSession);
  } catch (error) {
    session.abort();
  }
};

```

### 3. Handle payment authorization

After merchant validation completes successfully, the Apple Pay payment sheet is displayed on the customer’s device.

When the customer authorizes the payment using Face ID, Touch ID, or a device passcode, Apple invokes the `onpaymentauthorized` callback and provides a payment token.

This payment token must be sent to your backend to create a payment using the KOMOJU Payments API.

**Example:**

```javascript
session.onpaymentauthorized = async event => {
  const { token } = event.payment;
  const amount = document.getElementById("amount").value;

  const result = await pay(amount, token);

  session.completePayment({
    status: result
      ? ApplePaySession.STATUS_SUCCESS
      : ApplePaySession.STATUS_FAILURE
  });
};

```

---

## Backend Integration

### 1. Merchant validation endpoint

Create a backend endpoint that:

- Receives the `validation_url` from the frontend
- Calls the **KOMOJU Validate Merchant API** using your secret key
- Returns the **merchant session** to the frontend

**Example:**

```javascript
app.post("/api/validate_merchant", async (req, res) => {
  const { validation_url } = req.body;
  const domain_name = req.headers.host;

  try {
    const komojuResponse = await fetch(
      `${KOMOJU_ENDPOINT}/api/v1/apple_pay/validate_merchant`,
      {
        method: "POST",
        headers: headers(KOMOJU_SECRET_KEY),
        body: JSON.stringify({
          validation_url,
          domain_name
        })
      }
    );

    const komojuData = await komojuResponse.json();

    if (komojuResponse.status !== 200) {
      return res.status(400).json({ error: "Bad Request" });
    }

    return res.json(komojuData);
  } catch (error) {
    return res.status(500).json({ error: "Internal Server Error" });
  }
});

```

### 2. Create a payment

To create an Apple Pay payment, call the KOMOJU Payments API with:

- `payment_details.type` set to `apple_pay`
- `payment_details.token` set to the Apple Pay token received from the frontend

**Example:**

```javascript
app.post("/api/payment", async (req, res) => {
  const { currency, amount, token } = req.body;

  const komojuPaymentRequest = {
    currency,
    amount,
    tax: 0,
    payment_details: {
      type: "apple_pay",
      token
    }
  };

  try {
    const komojuResponse = await fetch(
      `${KOMOJU_ENDPOINT}/api/v1/payments`,
      {
        method: "POST",
        headers: headers(KOMOJU_SECRET_KEY),
        body: JSON.stringify(komojuPaymentRequest)
      }
    );

    const komojuPayment = await komojuResponse.json();

    if (komojuResponse.status !== 200) {
      return res.status(400).json({ error: "Bad Request" });
    }

    return res.json(komojuPayment);
  } catch (error) {
    return res.status(500).json({ error: "Internal Server Error" });
  }
});

```

---

# API Reference: validate_merchant

The specifications of the **KOMOJU Payments API** are as follows.

### Endpoint

```
POST /api/v1/apple_pay/validate_merchant

```

### Request Parameters

| Name | Type | Description |
| --- | --- | --- |
| `validation_url` | string | The `validationURL` value provided in the `onvalidatemerchant` callback of `ApplePaySession`. |
| `domain_name` | string | The domain name of the page that displays the Apple Pay button. This domain must be registered in the KOMOJU dashboard. |

### Response

Returns the merchant session object issued by Apple.