Express.js に Stripe 決済を導入する方法【2026年最新・完全ガイド】

npm install stripe

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2026-02-25.clover',
});

STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxx

ALTER TABLE users ADD COLUMN stripe_customer_id VARCHAR(255) NULL UNIQUE;

CREATE TABLE payments (
  id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  user_id BIGINT UNSIGNED NOT NULL,
  stripe_session_id VARCHAR(255) UNIQUE NOT NULL,
  stripe_payment_intent_id VARCHAR(255) NULL,
  status VARCHAR(50) NOT NULL DEFAULT 'pending',
  amount INT UNSIGNED NOT NULL,
  currency VARCHAR(10) DEFAULT 'jpy',
  description VARCHAR(255) NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id)
);

import { Router, Request, Response } from 'express'
import Stripe from 'stripe'
import { AppDataSource } from '../datasource'
import { User } from '../entities/User'
import { Payment } from '../entities/Payment'
import { authMiddleware } from '../middleware/auth'

const router = Router()

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2026-02-25.clover' as any, // バージョンを固定しないと、SDK アップデート時に挙動が変わるリスクがある
})

async function getOrCreateStripeCustomer(user: User): Promise<string> {
  // すでに Stripe Customer が作成済みであればその ID をそのまま返す（重複作成を防ぐ）
  if (user.stripeCustomerId) {
    return user.stripeCustomerId
  }

  /**
   * Stripe API に新しい Customer オブジェクトを作成するメソッド。
   * 作成に成功すると Customer オブジェクトが返され、customer.id に
   * "cus_xxxxxxxxxx" 形式の一意な顧客 ID が格納される。
   */
  const customer = await stripe.customers.create({
    email: user.email,
    name: user.name,
    metadata: { userId: String(user.id) },
  })

  const userRepo = AppDataSource.getRepository(User)
  user.stripeCustomerId = customer.id
  await userRepo.save(user)

  return customer.id
}

router.post('/checkout', authMiddleware, async (req: Request, res: Response) => {
  try {
    const { priceId, quantity = 1 } = req.body

    if (!priceId) {
      res.status(400).json({ error: 'priceId は必須です' })
      return
    }

    const userRepo = AppDataSource.getRepository(User)
    const user = await userRepo.findOne({ where: { id: req.user!.userId } })

    if (!user) {
      res.status(404).json({ error: 'ユーザーが見つかりません' })
      return
    }

    const customerId = await getOrCreateStripeCustomer(user)

    const session = await stripe.checkout.sessions.create({
      customer: customerId,
      payment_method_types: ['card'],
      line_items: [
        {
          price: priceId,
          quantity,
        },
      ],
      mode: 'payment',
      success_url: `${process.env.FRONTEND_URL}/payment/success?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${process.env.FRONTEND_URL}/payment/cancel`,
      metadata: {
        userId: String(user.id),
      },
    })

    const paymentRepo = AppDataSource.getRepository(Payment)
    const payment = paymentRepo.create({
      userId: user.id,
      stripeSessionId: session.id,
      status: 'pending',
      amount: 0,
      currency: 'jpy',
    })
    await paymentRepo.save(payment)

    res.json({ url: session.url, sessionId: session.id })
  } catch (error) {
    console.error('Checkout error:', error)
    res.status(500).json({ error: '決済セッションの作成に失敗しました' })
  }
})

router.post('/subscription', authMiddleware, async (req: Request, res: Response) => {
  try {
    const { priceId } = req.body

    if (!priceId) {
      res.status(400).json({ error: 'priceId は必須です' })
      return
    }

    const userRepo = AppDataSource.getRepository(User)
    const user = await userRepo.findOne({ where: { id: req.user!.userId } })

    if (!user) {
      res.status(404).json({ error: 'ユーザーが見つかりません' })
      return
    }

    const customerId = await getOrCreateStripeCustomer(user)

    const session = await stripe.checkout.sessions.create({
      customer: customerId,
      payment_method_types: ['card'],
      line_items: [
        {
          price: priceId,
          quantity: 1,
        },
      ],
      mode: 'subscription',
      success_url: `${process.env.FRONTEND_URL}/payment/success?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${process.env.FRONTEND_URL}/payment/cancel`,
      metadata: {
        userId: String(user.id),
      },
    })

    const paymentRepo = AppDataSource.getRepository(Payment)
    const payment = paymentRepo.create({
      userId: user.id,
      stripeSessionId: session.id,
      status: 'pending',
      amount: 0,
      currency: 'jpy',
      description: 'subscription',
    })
    await paymentRepo.save(payment)

    res.json({ url: session.url, sessionId: session.id })
  } catch (error) {
    console.error('Subscription error:', error)
    res.status(500).json({ error: 'サブスクリプションセッションの作成に失敗しました' })
  }
})

router.post('/portal', authMiddleware, async (req: Request, res: Response) => {
  try {
    const userRepo = AppDataSource.getRepository(User)
    const user = await userRepo.findOne({ where: { id: req.user!.userId } })

    if (!user) {
      res.status(404).json({ error: 'ユーザーが見つかりません' })
      return
    }

    if (!user.stripeCustomerId) {
      res.status(400).json({ error: 'Stripe顧客情報が見つかりません' })
      return
    }

    const session = await stripe.billingPortal.sessions.create({
      customer: user.stripeCustomerId,
      return_url: `${process.env.FRONTEND_URL}/payment`,
    })

    res.json({ url: session.url })
  } catch (error) {
    console.error('Portal error:', error)
    res.status(500).json({ error: 'ポータルセッションの作成に失敗しました' })
  }
})

router.get('/history', authMiddleware, async (req: Request, res: Response) => {
  try {
    const page = Math.max(1, parseInt(req.query.page as string) || 1)
    const limit = Math.min(100, Math.max(1, parseInt(req.query.limit as string) || 20))
    const skip = (page - 1) * limit

    const paymentRepo = AppDataSource.getRepository(Payment)
    const [payments, total] = await paymentRepo.findAndCount({
      where: { userId: req.user!.userId },
      order: { createdAt: 'DESC' },
      skip,
      take: limit,
    })

    res.json({
      payments,
      pagination: {
        page,
        limit,
        total,
        totalPages: Math.ceil(total / limit),
      },
    })
  } catch (error) {
    console.error('Payment history error:', error)
    res.status(500).json({ error: '決済履歴の取得に失敗しました' })
  }
})

router.get('/status/:sessionId', authMiddleware, async (req: Request, res: Response) => {
  try {
    const { sessionId } = req.params as { sessionId: string }
    const paymentRepo = AppDataSource.getRepository(Payment)
    const payment = await paymentRepo.findOne({
      where: {
        stripeSessionId: sessionId,
        userId: req.user!.userId,
      },
    })

    if (!payment) {
      res.status(404).json({ error: '決済情報が見つかりません' })
      return
    }

    res.json({ payment })
  } catch (error) {
    console.error('Payment status error:', error)
    res.status(500).json({ error: '決済ステータスの取得に失敗しました' })
  }
})

export default router

import { Router, Request, Response } from 'express'
import Stripe from 'stripe'
import { AppDataSource } from '../datasource'
import { Payment } from '../entities/Payment'
import { User } from '../entities/User'

const router = Router()

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2026-02-25.clover' as any,
})

router.post('/stripe', async (req: Request, res: Response) => {
  const sig = req.headers['stripe-signature'] as string

  let event: Stripe.Event

  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    )
  } catch (err) {
    console.error('Webhook signature verification failed:', err)
    res.status(400).json({ error: 'Webhook署名の検証に失敗しました' })
    return
  }

  const paymentRepo = AppDataSource.getRepository(Payment)

  switch (event.type) {
    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session

      const payment = await paymentRepo.findOne({
        where: { stripeSessionId: session.id },
      })

      if (payment) {
        payment.status = 'completed'
        payment.amount = session.amount_total ?? 0
        payment.currency = session.currency ?? 'jpy'
        payment.stripePaymentIntentId = (session.payment_intent as string) ?? undefined
        await paymentRepo.save(payment)
      }

      console.log(`Payment completed: session=${session.id}`)
      break
    }

    case 'checkout.session.expired': {
      const session = event.data.object as Stripe.Checkout.Session

      const payment = await paymentRepo.findOne({
        where: { stripeSessionId: session.id },
      })

      if (payment) {
        payment.status = 'expired'
        await paymentRepo.save(payment)
      }

      console.log(`Payment expired: session=${session.id}`)
      break
    }

    case 'payment_intent.payment_failed': {
      const paymentIntent = event.data.object as Stripe.PaymentIntent

      const payment = await paymentRepo.findOne({
        where: { stripePaymentIntentId: paymentIntent.id },
      })

      if (payment) {
        payment.status = 'failed'
        await paymentRepo.save(payment)
      }

      console.log(`Payment failed: intent=${paymentIntent.id}`)
      break
    }

    case 'customer.subscription.deleted': {
      const subscription = event.data.object as Stripe.Subscription
      console.log(`Subscription cancelled: ${subscription.id}`)
      break
    }

    case 'invoice.payment_succeeded': {
      const invoice = event.data.object as Stripe.Invoice

      // 初回請求（checkout.session.completed で処理済み）はスキップ
      if (invoice.billing_reason === 'subscription_create') {
        console.log(`Initial invoice skipped: ${invoice.id}`)
        break
      }

      // 2回目以降の定期課金を Payment に記録
      // Stripe API 2026-02-25.clover 以降、invoice.subscription は廃止された。
      // サブスクリプション ID は invoice.parent.subscription_details.subscription に移動している。
      const subscriptionId = invoice.parent?.subscription_details?.subscription
      if (subscriptionId && invoice.customer) {
        const userRepo = AppDataSource.getRepository(User)
        const user = await userRepo.findOne({
          where: { stripeCustomerId: invoice.customer as string },
        })

        if (user) {
          // Stripe API 2026-02-25.clover 以降、invoice.payment_intent は廃止された。
          // PaymentIntent ID は confirmation_secret.client_secret の "_secret_" より前の部分から取得できる。
          // 例: "pi_abc123_secret_xyz" → "pi_abc123"
          const clientSecret = invoice.confirmation_secret?.client_secret
          const paymentIntentId = clientSecret?.split('_secret_')[0]

          const payment = paymentRepo.create({
            userId: user.id,
            stripeSessionId: `inv_${invoice.id}`,
            ...(paymentIntentId ? { stripePaymentIntentId: paymentIntentId } : {}),
            status: 'completed',
            amount: invoice.amount_paid ?? 0,
            currency: invoice.currency ?? 'jpy',
            description: 'subscription_renewal',
          })
          await paymentRepo.save(payment)
        }
      }

      console.log(`Invoice paid: ${invoice.id}`)
      break
    }

    case 'invoice.payment_failed': {
      const invoice = event.data.object as Stripe.Invoice
      console.log(`Invoice payment failed: ${invoice.id}`)
      break
    }

    default:
      console.log(`Unhandled event type: ${event.type}`)
  }

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

export default router

# インストール（macOS）
brew install stripe/stripe-cli/stripe

# ログイン
stripe login

# ローカルサーバーに転送
stripe listen --forward-to localhost:8888/api/webhook/stripe

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

フロントエンド          バックエンド (Express)          Stripe
    |                        |                          |
    |-- POST /checkout ----->|                          |
    |                        |-- Customer 取得/作成 --->|
    |                        |<-------------------------|
    |                        |-- Session 作成 --------->|
    |                        |<-------------------------|
    |                        |-- Payment を pending で保存
    |<-- { url } ------------|                          |
    |                        |                          |
    |-- url にリダイレクト --------------------------->|
    |                        |                   決済処理|
    |<-- success_url にリダイレクト ------------------|
    |                        |<-- Webhook 通知 ---------|
    |                        |-- Payment を completed に更新
    |                        |-- { received: true } --->|