概要

Apple Pay は、KOMOJU Hosted Page または Hosted Fields を利用することで、比較的簡単に導入できます。一方で、KOMOJU API を使用して Apple Pay を統合する場合は、Apple Pay の加盟店検証およびセキュリティ要件に対応するため、追加の実装が必要となります。

本ドキュメントでは、KOMOJU API 経由での Apple Pay 処理フローの概要と、KOMOJU API を使用して Apple Pay を実装するための手順を段階的に説明します。

セットアップ手順の概要

KOMOJU API 経由で Apple Pay を利用するには、以下の手順のセットアップを実施してください。

Hosted Fields での Apple Pay 設定手順と同じ手順で Apple Pay で使用するすべてのドメインおよびサブドメインを登録します。
チェックアウトページに Apple Pay ボタンを追加します。
バックエンドから KOMOJU の Validate Merchant API を呼び出し、検証を実行します。
Apple Pay の決済トークンを使用して KOMOJU Payments API を呼び出し、決済を実行します。

処理フロー概要

KOMOJU API を使用した Apple Pay は以下の通りに処理されます。

実装ガイド

フロントエンド実装

1. Apple Pay ボタンの設置

Apple が提供する JavaScript ライブラリを利用して Apple Pay ボタンを設置します。ボタンデザインの調整や実装の詳細については、Apple の公式デモを参照してください。
Apple Pay on the Web Interactive Demo

2. 加盟店検証の実行

フロントエンドにて Apple Pay セッションが作成されると Apple の Javascript ライブラリの onvalidatemerchant コールバックを経由して validationURL が提供されます。バックエンドを経由してこの validationURL の値をリクエストにセットし KOMOJU の Validate Merchant API を呼び出し加盟店検証を実行します。

⚠️
Validate Merchant API の呼び出しにはシークレットキーが必要なため、必ずバックエンドから呼び出してください。

コード例:

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. 決済処理

加盟店検証が正常に完了すると、ユーザーのデバイスに Apple Pay の支払いシートが表示されます。

ユーザーが Face ID、Touch ID、またはデバイスのパスコードを使用して支払いを認証すると、 onpaymentauthorized コールバックを経由して、Apple Pay の決済トークンが提供されます。

この決済トークンをバックエンドを経由して KOMOJU Payments API に送信することで決済を実行します。

コード例:

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

バックエンド実装

1. KOMOJU Validate Merchant API の呼び出し

フロントエンドにて onvalidatemerchant コールバックが呼び出された際に実行する、以下の処理をバックエンドに実装します。

フロントエンドから validation_url を受信する
シークレットキーを使用して KOMOJU Validate Merchant API を呼び出す
加盟店セッション（merchant session）をフロントエンドに返却する

コード例:

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. 決済の実行

Apple Pay の決済を実行するには、以下の内容を指定して KOMOJU Payments API を呼び出します。

payment_details.type に apple_pay を指定
payment_details.token にフロントエンドから受け取った Apple Pay の決済トークンを指定

コード例:

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 リファレンス: validate_merchant

KOMOJU Payments API の仕様は以下の通りです。

リクエストパス

POST /api/v1/apple_pay/validate_merchant

リクエストパラメータ

項目名	型	説明
validation_url	string	`ApplePaySession` の `onvalidatemerchan`t コールバックで提供される `validationURL` の値。
domain_name	string	Apple Pay ボタンを表示しているページのドメイン名。このドメインは、あらかじめ KOMOJU ダッシュボードに登録されている必要があります。

レスポンス

Apple によって発行された加盟店セッションオブジェクト（merchant session object）を JSON 形式で返します。