Merchant が Apple Pay と直接連携する

直接連携では、Apple Pay JS または PassKit で Apple Pay トークンを取得し、Merchant サーバーから Waffo へ送信します。 Merchant は次の項目を管理します。

Apple Developer アカウントと Merchant ID。
Payment Processing Certificate と対応する秘密鍵。
Apple Pay on the Web のドメイン検証。
Apple Pay JS または PassKit のフロントエンド連携。
トークン署名検証、復号、リプレイ防止、機密データのコンプライアンス対応。

開始前に Waffo テクニカルサポートへ連絡し、Merchant と決済手段の設定を確認してください。

現在サポート：復号済みトークンの送信

現在は、Merchant サーバーで Apple Pay トークンを復号し、以下の形式で復号結果を Waffo へ送信する必要があります。

リクエストには token.decryptedPaymentData が必要です。token.paymentData も同時に保持できますが、それだけを送信結果として使用することはできません。

元の暗号化済みトークンの構造

Apple Pay JS または PassKit は、次の元の payment token エンベロープを返します。現在、このオブジェクトは Merchant サーバーで署名検証と復号を行うための入力です。Waffo へ直接送信できる paymentTokenData ではありません。

{
  "billingContact": {
    "countryCode": "US",
    "givenName": "wz",
    "familyName": "w",
    "postalCode": "20001",
    "addressLines": ["dk", "dh"],
    "administrativeArea": "AL",
    "locality": "djj"
  },
  "token": {
    "paymentMethod": {
      "network": "MasterCard",
      "type": "credit",
      "displayName": "MasterCard 4444"
    },
    "transactionIdentifier": "e392617d9e2f7938ca727c6fd063dc7915e42f546bca810ea43f7c2759c52a26",
    "paymentData": {
      "data": "<encrypted_data>",
      "signature": "<signature>",
      "header": {
        "publicKeyHash": "<public_key_hash>",
        "ephemeralPublicKey": "<ephemeral_public_key>",
        "transactionId": "<transaction_id>"
      },
      "version": "EC_v1"
    }
  }
}

フィールド	説明
`token.paymentData`	暗号化された決済データ。現在は Merchant が証明書の秘密鍵で復号します
`token.paymentMethod.network`	`MasterCard` や `Visa` などのカードネットワーク
`billingContact`	Apple Pay JS で `requiredBillingContactFields` を要求した場合に返される請求先連絡先。カード名義人名と請求先住所の取得元です

トークンを復号して検証する

Apple Pay JS または PassKit が返すトークンでは、token.paymentData に暗号化された決済データが含まれます。サーバーで次の処理を行います。

復号鍵を選択する

Payment Processing Certificate に対応する秘密鍵を使用します。

トークンを検証する

Apple の仕様に従って、トークン署名と証明書チェーンを検証します。

決済データを復号する

トークンの version に従って token.paymentData.data を復号し、UTF-8 の結果を JSON として解析します。

取引を検証する

transactionId が未処理であることを確認し、復号結果の通貨と金額を注文と照合します。

Waffo リクエストを組み立てる

復号済み JSON を token.decryptedPaymentData に格納し、Waffo へ送信します。

暗号処理の全手順とフィールド定義については、Apple の Payment token format referenceに従ってください。証明書の設定については、Setting up Apple Payを参照してください。

復号済みデータには、デバイスアカウント番号と決済暗号文が含まれます。ブラウザーで復号しないでください。また、完全なトークン、デバイスアカウント番号、秘密鍵、決済暗号文をログに記録しないでください。

復号後の payload 構造

token.paymentData を復号すると、Apple が定義する payment token payload が得られます。

{
  "applicationPrimaryAccountNumber": "5555555555554444",
  "applicationExpirationDate": "270831",
  "currencyCode": "156",
  "transactionAmount": 10,
  "deviceManufacturerIdentifier": "050110030273",
  "paymentDataType": "3DSecure",
  "paymentData": {
    "onlinePaymentCryptogram": "AORgiMGqVyeCAAt1LKSuAoABFA==",
    "eciIndicator": ""
  }
}

Subscription 決済の MPAN シナリオでは、merchantTokenIdentifier などの Merchant Token 情報も含まれます。

フィールド	説明
`applicationPrimaryAccountNumber`	デバイスアカウント番号（DPAN）
`applicationExpirationDate`	`YYMMDD` 形式の 6 桁のカード有効期限
`paymentData.onlinePaymentCryptogram`	決済検証に使用する 3DS 暗号文。空の場合があります
`paymentDataType`	決済データタイプ：`3DSecure` または `EMV`
その他のフィールド	デバイス識別子、ECI、Merchant Token などの補助情報

送信形式

復号済み payload だけでは不十分です。復号済みデータにはカードネットワークが含まれず、Apple Pay の DPAN の BIN から通常はネットワークを特定できません。billingContact も暗号化データの外側にあり、カード名義人名と請求先住所の唯一の取得元です。Apple Pay が返す外側の構造を保持し、token 内に token.decryptedPaymentData を追加してください。token.paymentData も同時に保持できます。次の JSON は、/api/v1/order/create リクエストの paymentTokenData フィールドに設定する内容です。

{
  "billingContact": {
    "countryCode": "US",
    "givenName": "wz",
    "familyName": "w",
    "postalCode": "20001",
    "addressLines": ["dk", "dh"],
    "administrativeArea": "AL",
    "locality": "djj"
  },
  "token": {
    "paymentMethod": {
      "network": "MasterCard",
      "type": "credit",
      "displayName": "MasterCard 4444"
    },
    "transactionIdentifier": "e392617d9e2f7938ca727c6fd063dc7915e42f546bca810ea43f7c2759c52a26",
    "decryptedPaymentData": {
      "applicationPrimaryAccountNumber": "5555555555554444",
      "applicationExpirationDate": "270831",
      "currencyCode": "156",
      "transactionAmount": 10,
      "deviceManufacturerIdentifier": "050110030273",
      "paymentDataType": "3DSecure",
      "paymentData": {
        "onlinePaymentCryptogram": "AORgiMGqVyeCAAt1LKSuAoABFA==",
        "eciIndicator": ""
      }
    }
  }
}

注文作成 API では、paymentTokenData は String です。リクエストを送信する前に、オブジェクト全体を JSON 文字列へシリアライズしてください。

const paymentTokenData = JSON.stringify(decryptedApplePayPayload);

Waffo は token.decryptedPaymentData を検出すると、復号済みトークンを優先して処理し、プラットフォームでの復号をスキップします。

フィールド要件

フィールド	要件	説明
`token.decryptedPaymentData.applicationPrimaryAccountNumber`	必須	デバイスアカウント番号（DPAN）
`token.decryptedPaymentData.applicationExpirationDate`	必須	`YYMMDD` 形式の 6 桁の数字
`token.paymentMethod.network`	必須	元のトークンの外側の構造から変更せずに送信するカードネットワーク
`billingContact`	推奨	カード名義人名と請求先住所の取得元。Apple Pay が返した場合はオブジェクト全体を送信する
`token.decryptedPaymentData.paymentData.onlinePaymentCryptogram`	任意	3DS 決済暗号文。値がある場合は変更せずに送信する
`token.decryptedPaymentData` 内のその他のフィールド	任意	`paymentDataType`、`deviceManufacturerIdentifier`、`eciIndicator`、`merchantTokenIdentifier` など、値があるフィールドを変更せずに送信する

復号済みトークンの送信に対応しているのは Apple Pay のみです。Google Pay トークンは暗号化形式で送信する必要があります。

はじめに

コアコンセプト

インテグレーション

Webhook

SDK

ツールとリファレンス

Merchant が Apple Pay と直接連携する

現在サポート：復号済みトークンの送信

元の暗号化済みトークンの構造

トークンを復号して検証する

復号後の payload 構造

送信形式

フィールド要件

​現在サポート：復号済みトークンの送信

​元の暗号化済みトークンの構造

​トークンを復号して検証する

​復号後の payload 構造

​送信形式

​フィールド要件

現在サポート：復号済みトークンの送信

元の暗号化済みトークンの構造

トークンを復号して検証する

復号後の payload 構造

送信形式

フィールド要件