> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Merchant が Apple Pay と直接連携する
> Merchant サーバーで Apple Pay トークンを復号し、Waffo 指定の形式で復号結果を送信します。
直接連携では、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`](/docs/api-reference/order-create/create-new-order#body-payment-token-data) ではありません。
```json theme={null}
{
"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": "",
"signature": "",
"header": {
"publicKeyHash": "",
"ephemeralPublicKey": "",
"transactionId": ""
},
"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` が未処理であることを確認し、復号結果の通貨と金額を注文と照合します。
復号済み JSON を `token.decryptedPaymentData` に格納し、Waffo へ送信します。
暗号処理の全手順とフィールド定義については、Apple の [Payment token format reference](https://developer.apple.com/documentation/PassKit/payment-token-format-reference)に従ってください。証明書の設定については、[Setting up Apple Pay](https://developer.apple.com/documentation/PassKit/setting-up-apple-pay)を参照してください。
復号済みデータには、デバイスアカウント番号と決済暗号文が含まれます。ブラウザーで復号しないでください。また、完全なトークン、デバイスアカウント番号、秘密鍵、決済暗号文をログに記録しないでください。
## 復号後の payload 構造
`token.paymentData` を復号すると、Apple が定義する payment token payload が得られます。
```json theme={null}
{
"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`](/docs/api-reference/order-create/create-new-order) リクエストの [`paymentTokenData`](/docs/api-reference/order-create/create-new-order#body-payment-token-data) フィールドに設定する内容です。
```json theme={null}
{
"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`](/docs/api-reference/order-create/create-new-order#body-payment-token-data) は `String` です。リクエストを送信する前に、オブジェクト全体を JSON 文字列へシリアライズしてください。
```typescript theme={null}
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 トークンは暗号化形式で送信する必要があります。