# Apple Pay マーチャントトークン

Apple Pay マーチャントトークンを使用して、継続支払い、後払い、自動リロード支払いに対応する方法をご紹介します。

[Apple Pay マーチャントトークン (MPAN)](https://developer.apple.com/apple-pay/merchant-tokens/)は、パーチェシングカード、ビジネス、顧客を結び付け、ウォレットの利用者が Apple Wallet に保存されたカードへのアクセスを管理できるようになります。Apple Pay の最新のガイドラインでは、以下のような理由から、デバイストークン (DPAN) よりもマーチャントトークンが推奨されています。

- 複数のデバイスで情報を継続できる
- デバイスに関係なく継続支払いが可能
- 支払い情報が紛失または盗難されたデバイスから削除された場合でも、新しいデバイスでその情報を有効に維持できる

## マーチャントトークンのタイプ

Apple Pay を使用して、3 つの方法で MPAN をリクエストできます。リクエストの各タイプには、Apple Wallet がユーザーにどのように表示されるかに影響を与えるさまざまなパラメーターがあります。ほぼすべてのリクエストタイプで、`managementURL` を供給するオプションが提供されており、支払い方法を管理するためのウェブページに顧客を転送します。MPAN をリクエストし、カード発行会社が MPAN 生成をサポートしている場合は、MPAN を受け取ります。それ以外の場合は、DPAN を受け取ります。

| MPAN リクエストタイプ                                                                                                               | ユースケース                                                                                                                                                       | サポート                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| 継続 [PKRecurringPaymentRequest](https://developer.apple.com/documentation/passkit/pkrecurringpaymentrequest)                 | サブスクリプションなどの継続支払いで使用する MPAN を発行する                                                                                                                            | - [Web 版 Apple Pay](https://developer.apple.com/documentation/apple_pay_on_the_web)
  - v16.0 以降の iOS                |
| 自動リロード [PKAutomaticReloadPaymentRequest](https://developer.apple.com/documentation/passkit/pkautomaticreloadpaymentrequest) | Store カードのトップアップやプリペイドアカウントで使用する MPAN を発行する。サポート対象のパラメーター:
  - `automaticReloadBilling` は Apple Pay が提示された際に請求の詳細を示します。                                      | - [Web 版 Apple Pay](https://developer.apple.com/documentation/apple_pay_on_the_web)
  - v16.0 以降の iOS                |
| 後払い [PKDeferredPaymentRequest](https://developer.apple.com/documentation/passkit/pkdeferredpaymentrequest)                  | ホテルなどの予約で使用する MPAN を発行する。サポート対象のパラメーター:
  - `freeCancellationDate` は、Apple Pay が提示された際にキャンセルの期限を示します。
  - `billingAgreement` は、Apple Pay が提示された際に利用規約を表示します。 | - [Web 版 Apple Pay](https://developer.apple.com/documentation/apple_pay_on_the_web)
  - Xcode 14.3
  - v16.4 以降の iOS |

## Apple Pay マーチャントトークンを追加する

Express Checkout Element、ウェブ Payment Element、モバイル Payment Element で Apple Pay を提示する際に[マーチャントトークン](https://developer.apple.com/apple-pay/merchant-tokens/)を追加できます。Stripe は、Stripe Checkout の導入時にマーチャントトークンリクエストを自動的に処理します。

#### Express Checkout Element

[支払いリクエストボタン](https://docs.stripe.com/stripe-js/elements/payment-request-button.md) を継続支払いに使用している場合は、[Express Checkout Element に移行して](https://docs.stripe.com/elements/express-checkout-element/migration.md)、機能改善と支払い方法に対応することをお勧めします。

1. [Express Checkout Element の導入](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md)を設定します。
1. MPAN ユースケースに関連する `applePay` を渡します (ドロップダウンから選択して、ユースケースのコードサンプルを確認します)。
1. ユースケースに関連するパラメーターを含めます。

#### MPAN のユースケース - 継続課金

```javascript
elements.create('expressCheckout', {
  applePay: {recurringPaymentRequest: {
      paymentDescription: "Standard Subscription",
      regularBilling: {
        amount: 1000,
        label: "Standard Package",
        recurringPaymentStartDate: new Date("2023-03-31"),
        recurringPaymentEndDate: new Date("2024-03-31"),
        recurringPaymentIntervalUnit: "year",
        recurringPaymentIntervalCount: 1,
      },
      billingAgreement: "billing agreement",
      managementURL: "https://stripe.com",
    },
  },
});
```

#### MPAN のユースケース - 自動の再読み込み

```javascript
elements.create('expressCheckout', {
  applePay: {automaticReloadPaymentRequest: {
      paymentDescription: 'My automatic reload payment',
      managementURL: 'https://example.com/billing',
      automaticReloadBilling: {
        amount: 2500,
        label: 'Automatic Reload',
        automaticReloadPaymentThresholdAmount: 500
      },
    }
  },
  // Other options
});
```

#### MPAN のユースケース - 延べ払い

```javascript
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
elements.create('expressCheckout', {
  applePay: {deferredPaymentRequest: {
      paymentDescription: 'My deferred payment',
      managementURL: 'https://example.com/billing',
      deferredBilling: {
        amount: 2500,
        label: 'Deferred Fee',
        deferredPaymentDate: new Date('2024-01-05')
      }
    }
  }
});
```

#### ウェブ Payment Element

1. [Payment Element](https://docs.stripe.com/payments/payment-element.md) のインスタンスを作成します。
1. MPAN ユースケースに関連する `applePay` を渡します (ドロップダウンから選択して、ユースケースのコードサンプルを確認します)。
1. ユースケースに関連するパラメーターを含めます。

#### MPAN のユースケース - 継続課金

```javascript
const paymentElement = elements.create('payment', {
  applePay: {recurringPaymentRequest: {
      paymentDescription: 'My subscription',
      managementURL: 'https://example.com/billing',
      regularBilling: {
        amount: 2500,
        label: 'Monthly subscription fee',
        recurringPaymentIntervalUnit: 'month',
        recurringPaymentIntervalCount: 1,
      },
    },
  },
  // Other options
});
```

#### MPAN のユースケース - 自動の再読み込み

```javascript
 const paymentElement = elements.create('payment', {
  applePay: {
    automaticReloadPaymentRequest: {
      paymentDescription: 'My subscription',
      managementURL: 'https://example.com/billing',
      regularBilling: {
        amount: 2500,
        label: 'Automatic Reload',
        automaticReloadPaymentThresholdAmount: 500
      },
    },
  },
  // Other options
});
```

#### MPAN のユースケース - 延べ払い

```javascript
const paymentElement = elements.create('payment', {
  applePay: {
    deferredPaymentRequest: {
      paymentDescription: 'My deferred payment',
      managementURL: 'https://example.com/billing',
      deferredBilling: {
        amount: 2500,
        label: 'Deferred Fee',
        deferredPaymentDate: new Date('2024-01-05')
      },
    }
  },
  // Other options
});
```

## マーチャントトークンのオーソリ率の監視

Sigma ユーザーの場合は、`charges` テーブルに含まれている `card_token_type` 列挙フィールドにより、支払いで `mpan` カードまたは `dpan` カードが使用されていることが示されます。次の Sigma クエリの例では、MPAN のオーソリ率を計算しています。

```sql
-- deduplicated MPAN auth rate
select
  100.0 * count(
    case
      when charge_outcome in ('authorized', 'manual_review') then 1
    end
  ) / count(*) as deduplicated_auth_rate_pct,
  count(*) as n_attempts
from
  authentication_report_attempts a
  join charges c on c.id = a.charge_id
where
  c.created >= date('2021-01-01')
  and c.card_tokenization_method = 'apple_pay'
  -- The new field added to charges table.
  and c.card_token_type = 'mpan'
  -- deduplicate multiple manual retries to a single representative charge
  and is_final_attempt
```