stripe-integration

Stripe の統合

概要

Stripe は、EC プラットフォームで最も幅広くサポートされている決済プロセッサーです。Shopify では、Shopify Payments の基盤としてネイティブに利用されています。WooCommerce と BigCommerce では、公式プラグインを使うことで、最小限の設定で Stripe Checkout をすべて利用できます。カスタムコードが必要なのはヘッドレスストアフロントだけです。それでも、Stripe がホストする Checkout ページと Elements コンポーネントにより、複雑さの大半を解消できます。

このスキルを使用する場面

• 既存のストアに決済プロセッサーとして Stripe を追加する場合
• 新しい WooCommerce または BigCommerce ストアで Stripe を設定する場合
• 欧州の顧客向けに SCA 準拠のチェックアウトを実装する場合
• 注文処理を自動化するための Webhook ハンドラーを設定する場合
• Stripe による決済処理が必要なカスタムストアフロントまたはヘッドレスストアフロントを構築する場合

基本手順

ステップ 1：Stripe アカウントを作成して設定する

1. stripe.com で登録します。事業者確認には 1～3 営業日かかります
2. Stripe Dashboard → Activate account を完了し、実際の決済を受け付けられるようにします
3. Settings → Public details で Statement descriptor（顧客の銀行明細に表示される名称）を設定します
4. Stripe に税額計算を自動で処理させる場合は、Dashboard → Tax で Stripe Tax を設定します

ステップ 2：プラットフォームに Stripe をインストールする

---

Shopify

Shopify Payments は Stripe を基盤としています。最も簡単に Stripe を統合できます。

1. Settings → Payments → Shopify Payments → Complete account setup に移動します
2. 事業者情報と銀行情報を確認します
3. Shopify Payments は、カード決済、Apple Pay、Google Pay、Shop Pay、および（設定により）Klarna と Afterpay を自動で処理します
4. 追加のプラグインや API キーは不要です。Shopify Payments がすべて処理します

Stripe を直接利用する必要がある場合（例：Shopify Payments が対応していない機能を使う場合）：

1. Settings → Payments → Add payment methods → Stripe で Stripe 決済プロバイダーをインストールします
2. 注意：Shopify では、サードパーティの決済プロバイダーを利用すると追加の取引手数料（0.5%～2%）が発生します。Shopify Payments では発生しません

Shopify 用に Stripe Webhook を設定する： Shopify Payments の場合、Webhook の処理は Shopify が内部で行います。Stripe を直接利用する場合は、Stripe Dashboard → Developers → Webhooks で Webhook エンドポイントを登録します。

WooCommerce

1. WooCommerce Stripe Payment Gateway プラグインをインストールします（無料。WordPress.org から入手できます。WooCommerce 提供）
2. WooCommerce → Settings → Payments → Stripe に移動し、Enable をクリックします
3. Stripe Dashboard → Developers → API Keys にある Publishable key と Secret key を入力します
4. Payment Request Buttons（Apple Pay、Google Pay）を有効にします。商品ページとチェックアウトに自動で表示されます

追加の決済方法を有効にする：

• WooCommerce → Settings → Payments → Stripe に移動し、次の項目を有効にします：
  • Express Checkout（Apple Pay、Google Pay、Link）
  • SEPA Direct Debit（欧州の顧客向け）
  • iDEAL（オランダ）、Bancontact（ベルギー）、Sofort（ドイツ／オーストリア）
  • Klarna と Afterpay（利用資格がある場合）

Webhook を設定する：

1. Stripe プラグインの設定で Configure webhooks をクリックします
2. プラグインが必要な Webhook エンドポイントを Stripe に自動で登録します
3. Stripe Dashboard → Developers → Webhooks で Webhook が有効になっていることを確認します

Stripe Radar（不正防止）を有効にする： Stripe Radar はデフォルトで有効になっています。リスクの高い取引をブロックまたは確認対象にするルールを、Stripe Dashboard → Radar → Rules で設定します

BigCommerce

1. Settings → Payment Methods → Online Payment Methodsに移動します
2. Stripeを見つけて、Set Upをクリックします
3. Stripe ダッシュボードからStripe APIキー（PublishableとSecret）を入力します
4. Stripe設定パネルで、提供する支払い方法を有効にします
5. BigCommerceが必要なStripeウェブフックを自動的に登録します

Stripe Link（保存済みカード）を有効にする： BigCommerceのStripe設定でStripe Linkを有効にすると、再訪した顧客は保存済みの支払い情報を使ってワンクリックで支払えるようになります。

---

Custom / Headless

Stripe SDKをインストールする：

npm install stripe @stripe/stripe-js @stripe/react-stripe-js

オプションA：Stripe Checkout（ホスト型ページ — 最も簡単）

決済フォームを作成せずに、最もすばやく連携するには：

// Server: create a Checkout Session
const session = await stripe.checkout.sessions.create({
  line_items: [{
    price_data: {
      currency: 'usd',
      product_data: { name: 'Order #' + orderNumber },
      unit_amount: Math.round(orderTotal * 100), // cents
    },
    quantity: 1,
  }],
  mode: 'payment',
  success_url: `${YOUR_DOMAIN}/orders/{CHECKOUT_SESSION_ID}/confirmation`,
  cancel_url: `${YOUR_DOMAIN}/cart`,
  metadata: { order_id: orderId },
});

// Redirect customer to session.url
res.redirect(session.url);

オプションB：Stripe Elementsを使ったPayment Intents（カスタム決済フォーム）

// Server: create a Payment Intent
const paymentIntent = await stripe.paymentIntents.create({
  amount: Math.round(orderTotal * 100), // cents
  currency: 'usd',
  automatic_payment_methods: { enabled: true }, // Enables all eligible methods
  metadata: { order_id: orderId, customer_email: customerEmail },
});
res.json({ clientSecret: paymentIntent.client_secret });

// Client: render the payment form using Stripe Elements
import { Elements, PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';
import { loadStripe } from '@stripe/stripe-js';

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY);

function CheckoutForm({ onSuccess }) {
  const stripe = useStripe();
  const elements = useElements();

  async function handleSubmit(e) {
    e.preventDefault();
    const { error } = await stripe.confirmPayment({
      elements,
      confirmParams: { return_url: `${window.location.origin}/orders/confirmation` },
    });
    if (error) showError(error.message);
    // On success, Stripe redirects to return_url automatically
  }

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button type="submit" disabled={!stripe}>Pay Now</button>
    </form>
  );
}

export function PaymentPage({ clientSecret }) {
  return (
    <Elements stripe={stripePromise} options={{ clientSecret }}>
      <CheckoutForm />
    </Elements>
  );
}

注文処理のためのウェブフックを処理する：

// POST /api/webhooks/stripe
// IMPORTANT: use raw body parser — do not parse as JSON
export async function handleStripeWebhook(req, res) {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(
      req.rawBody,   // raw buffer — not JSON.parse'd
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  switch (event.type) {
    case 'payment_intent.succeeded':
      await fulfillOrder(event.data.object);
      break;
    case 'payment_intent.payment_failed':
      await handlePaymentFailed(event.data.object);
      break;
    case 'charge.refunded':
      await handleRefund(event.data.object);
      break;
    case 'charge.dispute.created':
      await handleDispute(event.data.object);
      break;
  }

  res.json({ received: true });
}

// Always check if already fulfilled — webhooks can arrive multiple times
async function fulfillOrder(paymentIntent) {
  const orderId = paymentIntent.metadata.order_id;
  const order = await db.orders.findUnique({ where: { id: orderId } });
  if (order.status !== 'pending') return; // Idempotency check

  await db.orders.update({ where: { id: orderId }, data: { status: 'confirmed', paidAt: new Date() } });
  await sendOrderConfirmationEmail(orderId);
}

ローカルでウェブフックをテストする：

# Install Stripe CLI and forward events to your local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe
# Copy the webhook signing secret printed by the CLI into your .env

ステップ3：PCIコンプライアンスとSCA

PCI DSSの適用範囲： Stripe ElementsまたはStripe Checkoutを使うと、PCI DSSコンプライアンスの負担を大幅に軽減できます。

• SAQ A（22項目）：Stripe Checkout（ホスト型ページ）を使う場合に該当します。カード情報がサーバーにもページにも一切触れません
• SAQ A-EP（191項目）：決済ページが独自ドメインから配信され、Stripe.jsがブラウザー内でカード情報をトークン化する場合に該当します

WooCommerce StripeプラグインとBigCommerceのStripe連携はいずれもStripe.jsを使ってトークン化するため、ほとんどの加盟店がSAQ A-EPの対象となります。

欧州の顧客向けSCA（強力な顧客認証）： Payment Intentsでautomatic_payment_methods: { enabled: true }を使うと、顧客の銀行が要求した場合に3Dセキュア認証を自動的に処理します。追加設定は不要です。

ベストプラクティス

• 必ずPayment Intentsを使用してください — 従来のCharges APIはSCAに対応していないため、新しい連携には推奨されません
• カード番号の生データを記録または保存しないでください — PCIの適用範囲外にとどまるため、Stripe ElementsまたはCheckoutを使用します
• 注文処理にはウェブフックイベントを使用してください — クライアント側のリダイレクトだけに頼らないでください。顧客がブラウザーウィンドウを閉じる可能性があります
• すべてのウェブフックハンドラーを冪等にしてください — Stripeは同じイベントを複数回配信することがあります。処理前に必ず現在の注文ステータスを確認してください
• すべてのPayment Intentのメタデータにorder_idを追加してください — 照合と異議申し立ての管理に役立ちます
• 複数の地域で販売する場合はStripe Taxを使用してください — 税額計算を独自に実装せず、Stripeダッシュボード → Taxで設定します

よくある問題

問題	解決策
ウェブフックの署名検証に失敗する	constructEventに生のリクエスト本文（JSONとして解析していないもの）を渡します。ウェブフックのルートではJSON解析をスキップするよう、フレームワークを設定してください
3DS認証が開始されない	支払い方法の種類を手動で列挙する代わりに、automatic_payment_methods: { enabled: true }を使用します
WooCommerce Stripeプラグインの決済フォームが空白になる	JavaScriptコンソールのエラーを確認します。多くの場合、CSP（コンテンツセキュリティポリシー）がStripe.jsをブロックしていることが原因です。CSPの許可リストにjs.stripe.comを追加してください
Stripeの支払いは成功と表示されるが、注文が確定しない	ウェブフックが正式な通知です。ウェブフックハンドラーでエラーが発生すると、注文は確定しません。Stripeダッシュボード → Developers → Webhooks → [Event]でウェブフックのログを確認してください
テストモードの請求が本番データに表示される	本番環境で本番用APIキーを使用していることを確認します。Stripeダッシュボードには本番／テストを切り替える別のトグルがあります。正しいモードになっていることを確認してください
通貨の金額が正しくない	Stripeでは通貨の最小単位を使います。$20.00は2000セント、JPY ¥3,000は3000です（乗算は不要です）

関連スキル

• @checkout-flow-optimization
• @subscription-billing
• @paypal-integration
• @order-processing-pipeline
• @buy-now-pay-later