# MPP 支払い

マシン間支払いには MPP を使用してください。

アプリの[完全なソースコード](https://github.com/stripe-samples/machine-payments)は GitHub で確認できます。

[MPP (Machine Payments Protocol)](https://mpp.dev) は、インターネット決済のプロトコルです。クライアントが有料リソースをリクエストすると、サーバーは決済の詳細を含む HTTP `402` レスポンスを返します。クライアントは支払いを承認し、リクエストを再試行して支払い、有料リソースへのアクセス権と領収書を取得します。

MPP は、次の 2 つの決済手段をサポートしています。

- **暗号資産決済**: 暗号資産入金アドレスを使用する直接的なオンチェーン決済です。ニューヨーク州を除く全州、および 30 カ国以上に物理的な拠点を持つビジネスにご利用いただけます。
- **法定通貨による決済**: カード、ウォレット、および　[Shared Payment Token (SPT)](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens.md) が対応しているその他の決済手段。アメリカに法人を構える事業者が利用できます。

## Before you begin

> 顧客は世界中でステーブルコインを決済に利用できますが、ステーブルコインの決済を受け付けることができるのはアメリカ企業のみです。

ステーブルコイン決済の受け付けを開始するには、以下のようにします:

1. [Stripe アカウントを設定](https://dashboard.stripe.com/register)していることを確認してください。
2. ダッシュボードの[決済手段](https://dashboard.stripe.com/settings/payment_methods)設定に移動し、**ステーブルコインと暗号資産**の決済手段をリクエストします。[機械決済](https://docs.stripe.com/payments/machine.md)のみにステーブルコインまたは暗号資産による決済を受け付ける場合は、マシン決済専用の別の[決済方法設定](https://docs.stripe.com/payments/payment-method-configurations.md)を作成することをお勧めします。
3. Stripe はアクセスリクエストを審査し、必要に応じてさらなる詳細のご提供をお願いする場合があります。リクエストが審査されている間、当該決済手段は **保留中** と表示されます。
4. リクエストが承認されると、ダッシュボードで **ステーブルコインおよび暗号資産** という決済手段が有効になります。

SPT を使用して法定通貨での決済を受け付けるには:

1. Stripe ダッシュボードで [Stripe プロフィールを作成](https://docs.stripe.com/get-started/account/profile.md)する必要があります。
2. プロファイルの `profile_` ID を保存します。この値は、以下の SPT 設定で `networkId` として使用します。プロファイル ID は Stripe ネットワーク上でビジネスを識別するものであり、サーバーの連携に必要です。

## 決済ライフサイクル

このガイドではサーバーを構築します。サーバーは決済が必要であることを示し、決済が正常に完了した後にコンテンツを返します。

#### 暗号資産
クライアント、サーバー、Stripe 間の MPP 暗号資産決済フローを示す図 (See full diagram at https://docs.stripe.com/payments/machine/mpp)
暗号資産決済では、Stripe は入金アドレスを処理し、資金がオンチェーンで確定されるときに [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) を自動的に *キャプチャーします* (Another way to say that you receive payment for a charge is to say that you "capture" the charge. Capturing the charge is often asynchronous and takes place after authorization. The capture is what transfers the money from the customer to you)。

#### SPT
クライアント、サーバー、Stripe 間の MPP SPT 決済フローを示す図 (See full diagram at https://docs.stripe.com/payments/machine/mpp)
[Shared Payment Token (SPT)](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens.md) 決済では、まずクライアントが SPT を作成します。サーバーはそのトークンを使用して `PaymentIntent` を作成し、Stripe の決済ネットワークを通じて決済を完了させます。

## 各方法を使用するタイミング

次の表は、2 つの決済手段を比較したものです。

| 決済方法 | 最適な用途 | 売上処理 |
| --- | --- | --- |
| **暗号資産** | 少額の取引 | オンチェーン売上処理 |
| **SPT** | 従来の決済手段、カード、ウォレット、より幅広い決済手段に対応 | Stripe の決済レール |

## コーディングエージェントを使用する

コーディングエージェントへの単一のプロンプトで、MPP を使用する API を構築できます:

```bash
Read https://docs.stripe.com/payments/machine/mpp.md?lang=node, and monetize my API to use MPP to charge for access using Stripe SPTs for fiat and the Tempo network for crypto.
```

以下のステップバイステップガイドもご参照ください。

## 依存関係をインストール

必要な依存関係をインストールします。

```bash
npm install mppx stripe
```

## エンドポイントを作成する

POST `/paid` エンドポイントを 1 つ追加し、`Mppx.compose` を使用した暗号資産と法定通貨決済の双方を受け付けます。この例では、暗号資産には 0.01 米ドル、法定通貨には 0.50 米ドルを請求します。クライアントが決済手段を選択すると、サーバーは `402` チャレンジ、または領収書付きの決済みリソースを返します。

#### Node.js

```node
import crypto from 'crypto';
import Stripe from 'stripe';
// 'stripe' here is the mppx payment method factory, not the Stripe Node SDK. We alias it to avoid confusion.
import { Mppx, stripe as mppStripe, tempo } from 'mppx/server';

// Tempo testnet token contract address for pathUSD (testnet USDC).
// For mainnet, use the address from the "Run live mode transactions" section below.
const PATH_USD = '0x20c0000000000000000000000000000000000000';

// Secret used to secure payment challenges
// https://mpp.dev/protocol/challenges#challenge-binding
const mppSecretKey = crypto.randomBytes(32).toString('base64');

// Crypto PaymentIntents require API version 2026-03-04.preview or later.
const stripeClient = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2026-03-04.preview',
});

export async function handler(request: Request) {
  const recipientAddress = await createPayToAddress(request);

  const mppx = Mppx.create({
    methods: [
      tempo.charge({
        currency: PATH_USD,
        recipient: recipientAddress,
        testnet: true,
      }),
      mppStripe.charge({
        client: stripeClient,
        networkId: process.env.STRIPE_PROFILE_ID!,
        paymentMethodTypes: ['card', 'link'],
      }),
    ],
    secretKey: mppSecretKey,
  });

  const response = await Mppx.compose(
    mppx.tempo.charge({ amount: '0.01', recipient: recipientAddress }),
    mppx.stripe.charge({ amount: '0.50', currency: 'usd' }),
  )(request);

  if (response.status === 402) return response.challenge;

  return response.withReceipt(Response.json({ data: '...' }));
}
```

## PaymentIntent を作成する

#### 暗号資産

暗号資産決済を処理するには、*`暗号資産`決済手段* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs)を受け付ける [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) を作成します。以下の `createPayToAddress` 関数は、エンドポイントで`受取人`として使用する入金アドレスを生成します。

> #### API バージョン
> 
> この機能には `2026-03-04.preview` API バージョンが必要です。Stripe クライアントの初期化時に `Stripe-Version` ヘッダーを `2026-03-04.preview` に設定します。

#### Node.js

```node
import Stripe from 'stripe';
import { Credential } from 'mppx';
import NodeCache from 'node-cache';

// In-memory cache for deposit addresses (TTL: 5 minutes)
// NOTE: For production, use a distributed cache like Redis instead of node-cache
const paymentCache = new NodeCache({ stdTTL: 300, checkperiod: 60 });

async function createPayToAddress(request: Request): Promise<`0x${string}`> {
  const authHeader = request.headers.get('authorization');
  if (authHeader && Credential.extractPaymentScheme(authHeader)) {
    const credential = Credential.fromRequest(request);
    const toAddress = credential.challenge.request.recipient as `0x${string}`;

    if (!toAddress) {
      throw new Error(
        'PaymentIntent did not return expected crypto deposit details'
      );
    }
    if (!paymentCache.has(toAddress)) {
      throw new Error('Invalid payTo address: not found in server cache');
    }
    return toAddress;
  }

  const decimals = 6;
  const amountInCents = Number(10000) / 10 ** (decimals - 2);

  const paymentIntent = await stripe.paymentIntents.create({
    amount: amountInCents,
    currency: 'usd',
    payment_method_types: ['crypto'],
    payment_method_data: {
      type: 'crypto',
    },
    payment_method_options: {
      crypto: {
        mode: 'deposit',
        deposit_options: {
          networks: ['tempo'],
        },
      } as Stripe.PaymentIntentCreateParams.PaymentMethodOptions.Crypto,
    },
    confirm: true,
  });

  if (
    !paymentIntent.next_action ||
    !('crypto_display_details' in paymentIntent.next_action)
  ) {
    throw new Error(
      'PaymentIntent did not return expected crypto deposit details'
    );
  }

  const depositDetails = paymentIntent.next_action
    .crypto_display_details as unknown as {
    deposit_addresses?: Record<string, { address?: string }>;
  };
  const payToAddress = depositDetails.deposit_addresses?.tempo?.address;

  if (!payToAddress) {
    throw new Error(
      'PaymentIntent did not return expected crypto deposit details'
    );
  }

  console.log(
    `Created PaymentIntent ${paymentIntent.id} for $${(
      amountInCents / 100
    ).toFixed(2)} -> ${payToAddress}`
  );

  paymentCache.set(payToAddress, true);
  return payToAddress as `0x${string}`;
}
```

この関数は、クライアントが受け取り、決済に使用する暗号資産の入金アドレスを返します。

[PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) のレスポンスには、`supported_tokens` で指定された入金アドレスが含まれます。これには、各ネットワークで受け付けられるトークンとそのコントラクトアドレスがリストされています。

```json
{
  "id": "pi_123",
  "amount": 5000,
  "currency": "usd",
  "status": "requires_action",
  "next_action": {
    "type": "crypto_display_details",
    "crypto_display_details": {
      "deposit_addresses": {
        "tempo": {
          "address": "0xtempo_address",
          "supported_tokens": [
            {
              "token_currency": "usdc",
              "token_contract_address": "0x…"
            }
          ]
        }
      }
    }
  }
}
```

> #### 暗号資産 PaymentIntents
> 
> 入金アドレス、決済ライフサイクル、サポート対象のネットワークなど、暗号資産 PaymentIntent の仕組みの詳細については、[入金モードの連携ガイド](https://docs.stripe.com/payments/deposit-mode-stablecoin-payments.md)を参照してください。

#### SPT

> Stripe では、SPT 経由のカード決済の最低請求額は 0.50 米ドル (または相当額) です。

SPT 決済では、サーバーがクライアントから有効な SPT 認証情報を受信すると、PaymentIntent が自動的に作成されます。`stripe.charge` メソッドは、クライアントから提供された SPT を使用して PaymentIntent の作成を処理します。

PaymentIntent には以下が含まれます。

- チャレンジの金額と通貨
- SPT からの決済手段
- `stripe.charge` メソッドで設定されたメタデータ
- Stripe の決済レールによる売上処理

PaymentIntent を別途作成する必要はありません。`stripe.charge` は、認証情報を検証する際に PaymentIntent を作成します。

## エンドポイントをテストする

エンドポイントはマシン決済を受け付ける準備が整いました。決済クレデンシャルなしでリクエストを送信し、実装が正常に動作することを確認してください。サーバーは `402` ステータスコードと決済要件を返す必要があります。

```bash
curl -iv http://localhost:4242/paid
```

レスポンスには、各決済手段に対応する `WWW-Authenticate` ヘッダーが 2 つ含まれます。各ヘッダーは、メソッド名と base64url でエンコードされた決済リクエストのペイロードを含む署名付きチャレンジをエンコードします。

```
< HTTP/1.1 402 Payment Required
< WWW-Authenticate: Payment id="chal_abc123", method="tempo", intent="charge", ...
< WWW-Authenticate: Payment id="chal_def456", method="stripe", intent="charge", ...
< Content-Type: application/problem+json
< Cache-Control: no-store
<
{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "Payment is required.",
  "challengeId": "..."
}
```

クライアントは両方のヘッダーを読み取り、サポートされている決済手段を選択して、`Authorization: Payment ...` 認証情報を付けてリクエストを再試行します。

有効な決済によるリクエストをシミュレーションします。

#### 暗号資産

[mppx](https://www.npmjs.com/package/mppx) を使用してコマンドラインからテストします。

```bash
npx mppx account create
npx mppx account fund --network testnet
npx mppx http://localhost:4242/paid
```

> #### サンドボックスとテストネット
> 
> [サンドボックス](https://docs.stripe.com/sandboxes.md)で作成する [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) は暗号資産テストネットを監視しません。したがって、送信されたテストネット取引は自動的には検出できません。サンドボックス `PaymentIntent` をテストするには [test helper endpoint](https://docs.stripe.com/api/payment_intents/simulate_crypto_deposit.md?api-version=2026-05-27.preview) を使用して暗号資産入金をシミュレーションします。[インテグレーションのテストの詳細を表示](https://docs.stripe.com/payments/deposit-mode-stablecoin-payments.md#test-your-integration)。

ウォレットを接続すると、サーバーがコンテンツを返し、決済を確定できます。[ダッシュボード](https://dashboard.stripe.com)で **Payments** に移動すると、取引を確認できます。

#### SPT

[サンドボックス](https://docs.stripe.com/sandboxes.md)で実装をテストするには、アカウント用の [Stripe プロフィールを作成](https://docs.stripe.com/get-started/account/profile.md)し、その `profile_test_`ID を `networkId` として使用します。テスト用シークレットキーを使用してテスト決済を作成します。

#### Node.js

```node
const mppx = Mppx.create({
  methods: [
    stripe.charge({
      networkId: 'profile_test_...',
      paymentMethodTypes: ['card', 'link'],
      secretKey: process.env.STRIPE_SANDBOX_SECRET_KEY!,
    }),
  ],
  secretKey: mppSecretKey
});
```

[link-cli](https://link.com/agents) を使用して、お客様のアカウントのテスト SPT を発行できます。`link-cli` は、Link アカウントを使用してワンタイムの Shared Payment Token 認証情報をプロビジョニングできるツールです。[link.com/agents](https://link.com/agents) に記載されている手順に従って、`link-cli` スキルをインストールするか、希望するエージェントで MCP サーバーとして登録してください。

`link-cli` を使って手動でテストするには、そのコマンドを直接実行します。

1. 個人用の Link アカウントにログインするか、アカウントがない場合は[登録](https://app.link.com)してください。

```bash
npx @stripe/link-cli auth login
```

1. 使用する決済手段を選択してください。まだお持ちでない場合は、[決済手段を追加](https://app.link.com/wallet)できます。

```bash
npx @stripe/link-cli payment-methods list
```

1. テスト支出リクエストを作成して、1 回限りのテスト SPT を発行します。テスト認証情報を作成するには`--test` を渡し、テスト用の `profile_test_` ID を指定するには`--network-id` を渡します。

```bash
npx @stripe/link-cli spend-request create \
  --payment-method-id csmrpd_xxx \
  --context "Test machine payments integration with Shared Payment Tokens, your test network profile ID, and the link-cli" \
  --amount 100 \
  --credential-type shared_payment_token \
  --network-id profile_test_... \
  --test \
  --request-approval
```

1. 決済を実行します。`--method` フラグと`--data` フラグは、実装形態によって異なります。

```bash
npx @stripe/link-cli mpp pay https://your-endpoint.com/resource \
  --spend-request-id lsrq_xxx \
  --method POST \
  --data '{ ... }'
```

[ダッシュボード](https://dashboard.stripe.com)で **Payments** に移動すると、取引を確認できます。

## メインネットと本番環境のトランザクションを実行する

本番環境に移行するには、次の 2 点を更新します。

- 暗号資産の場合は、Tempo 上の USDC の宛先を `0x20c000000000000000000000b9537d11c60e8b50` に設定し、`testnet: true` を `tempo.charge` から削除します。
- 法定通貨の場合は、[本番環境で Stripe プロフィールを作成](https://docs.stripe.com/get-started/account/profile.md)し、本番ネットワークのプロフィール ID を `networkId` に設定します。

#### Node.js

```node
const TEMPO_USDC = '0x20c000000000000000000000b9537d11c60e8b50';

const mppx = Mppx.create({
  methods: [
    tempo.charge({
      currency: TEMPO_USDC,
      recipient: recipientAddress,
    }),
    stripe.charge({
      client: stripeClient,
      networkId: process.env.STRIPE_PROFILE_ID!,
      paymentMethodTypes: ['card', 'link'],
    }),
  ],
  secretKey: mppSecretKey,
});
```

`profile_` ID を更新したら、`--test` フラグなしで新しい支出リクエストを作成し、本番環境の SPT を発行します:

```bash
npx @stripe/link-cli spend-request create \
  --payment-method-id csmrpd_xxx \
  --context "Use machine payments integration with Shared Payment Tokens in live mode, your live network profile ID, and the link-cli" \
  --amount 100 \
  --credential-type shared_payment_token \
  --network-id profile_... \
  --request-approval
```

次に、本番環境のエンドポイントに対して `mpp pay` コマンドを再実行します:

```bash
npx @stripe/link-cli mpp pay https://your-endpoint.com/resource \
  --spend-request-id lsrq_xxx \
  --method POST \
  --data '{ ... }'
```