# x402 決済

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

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

[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)します。

## Before you begin

アカウントでマシン決済を有効にする必要があります。

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

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

1. [Stripe アカウントを設定](https://docs.stripe.com/get-started/account/set-up.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)
## コーディングエージェントを使用する

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

```bash
Read https://docs.stripe.com/payments/machine/x402.md?lang=node, and create an API that uses x402 to charge for access using the Base network for crypto.
```

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

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

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

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

適格なクライアントなしでサーバーにリクエストを送信し、`402` ステータスコードが返されることを確認します。レスポンスヘッダーを確認するには、`-iv` を使用します。

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

レスポンスには、base64 でエンコードされた決済要件のペイロードを含む `payment-required` ヘッダーが含まれます。

```
> GET /paid HTTP/1.1
< HTTP/1.1 402 Payment Required
< payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiO...
```

次に、対象となるクライアントでリクエストを作成します。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)をご確認ください。

ウォレットを接続すると、サーバーがコンテンツを返し、決済を確定できます。[ダッシュボード](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 Developer Platform の [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`   |