# x402 決済

マシン間決済に x402 を使用します。

[x402](https://x402.org) は、インターネット決済のプロトコルです。クライアントが有料リソースをリクエストすると、サーバーは決済の詳細を含む HTTP 402 レスポンスを返します。クライアントは決済を行い、オーソリでリクエストを再試行します。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)します。

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

## Before you begin

アカウントで機械決済を有効にする必要があります。[登録するフォーム](https://docs.stripe.com/payments/machine.md#sign-up)を使用して機械支払いへのアクセスをリクエストしてください。

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

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

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

## 決済ライフサイクル

このガイドではサーバーを構築します。サーバーは支払いが必要であることを示し、支払いが成功した後にコンテンツを返します。支払いを完了するために、Stripe およびファシリテーターと連携します。
クライアント、サーバー、Stripe、ファシリテーター間の x402 決済フローを示す図 (See full diagram at https://docs.stripe.com/payments/machine/x402)
## エンドポイントを作成する

エンドポイントに決済ミドルウェアを追加して、決済を要求します。

の例では、`/paid` へのリクエストごとに、USDC 建てで 0.01 米ドル相当の決済が必要です。

#### Node.js

```node
import { paymentMiddleware } from "@x402/hono";
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

app.use(
  paymentMiddleware(
    {
      "GET /paid": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.01",
            network: "eip155:84532",
            payTo: createPayToAddress,
          }
        ],
        description: "Data retrieval endpoint",
        mimeType: "application/json",
      }
    },
    new x402ResourceServer(facilitatorClient).register(
      "eip155:84532",
      new ExactEvmScheme()
    )
  )
)
```

## PaymentIntent を作成する

決済を処理するには、`crypto` *決済手段* (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) を作成します。前述の `payTo` メソッドを使用します。

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

#### Node.js

```node
import Stripe from "stripe";
import NodeCache from 'node-cache';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2026-03-04.preview",
});

// 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(context) {
  // If a payment header exists, extract the destination address from it
  if (context.paymentHeader) {
    const decoded = JSON.parse(
      Buffer.from(context.paymentHeader, "base64").toString()
    );
    const toAddress = decoded.payload?.authorization?.to;

    if (toAddress && typeof toAddress === "string") {
      if (!paymentCache.has(toAddress)) {
        throw new Error("Invalid payTo address: not found in server cache");
      }
      return toAddress;
    }

    throw new Error(
      "PaymentIntent did not return expected crypto deposit details"
    );
  }

  // Create a new PaymentIntent to get a fresh crypto deposit address
  const decimals = 6; // USDC has 6 decimals
  const amountInCents = Number(10000) / Math.pow(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: ["base"],
        },
      },
    },
    confirm: true,
  });

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

  // Extract the Base network deposit address from the PaymentIntent
  const depositDetails = paymentIntent.next_action
    .crypto_display_details;
  const payToAddress = depositDetails.deposit_addresses["base"].address;

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

  paymentCache.set(payToAddress, true);
  return payToAddress;
}
```

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

[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": {
        "base": {
          "address": "0xbase_address",
          "supported_tokens": [
            {
              "token_currency": "usdc",
              "token_contract_address": "0x…"
            }
          ]
        }
      }
    }
  }
}
```

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

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

支払い資格のないクライアントでサーバーにリクエストを行い、`402` ステータスコードが返されることを確認します。

```bash
curl http://localhost:3000/paid
```

`402` ステータスコードが表示されます。

次に、対象となるクライアントでリクエストを作成します。Stripe の[purl](https://github.com/stripe/purl) を使用して、コマンドラインでテストしてください。

```bash
purl http://localhost:3000/paid
```

> #### サンドボックスとテストネット
> 
> [サンドボックス](https://docs.stripe.com/sandboxes.md)で作成する[PaymentIntents](https://docs.stripe.com/api/payment_intents/object.md)は暗号資産テストネットを監視しないため、送信されたテストネット取引を自動的に検出できません。サンドボックス `PaymentIntents` をテストするには、[テストヘルパーエンドポイント](https://docs.stripe.com/api/payment_intents/simulate_crypto_deposit.md?api-version=2026-03-04.preview)を使用して暗号資産の入金をシミュレーションします。[インテグレーションのテストの詳細](https://docs.stripe.com/payments/deposit-mode-stablecoin-payments.md#test-your-integration)をご確認ください。

ウォレットを接続した場合、サーバーはコンテンツを返し、決済を確認できます。[Stripe ダッシュボードの Payments](https://dashboard.stripe.com/payments) ページにアクセスして取引を確認してください。

または、curl を使用して Stripe API から最新の決済を取得できます。

```bash
curl https://api.stripe.com/v1/payment_intents?limit=10 \
  -u <<YOUR_SECRET_KEY>>:
```

## mainnet 取引を実行する

mainnet 取引を実行するには、mainnet をサポートする x402 ファシリテーターを導入します。

Coinbase 開発者プラットフォームガイドで [CDP Facilitator の使用](https://docs.cdp.coinbase.com/x402/quickstart-for-sellers#running-on-mainnet) を参照してください。

## トークンとネットワークサポート

`暗号資産`の決済手段と `mode: deposit` を使用した `PaymentIntents` は、次のネットワークで USDC に対応しています。

| Network | トークン | トークンコントラクトアドレス                                   |
| ------- | ---- | ------------------------------------------------ |
| Tempo   | USDC | `0x20c0000000000000000000000000b9537d11c60e8b50` |
| Base    | USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`     |
| Solana  | USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`   |