stripe-payments

Stripe Payments Integration

A guide to integrating Stripe payments for game/web app monetization.

Core principles

Must use

• CheckoutSessions API — the foundation of one-time payments + subscriptions
• Stripe Hosted Checkout or Embedded Checkout preferred
• Dynamic payment methods — enable in the Dashboard (do not hardcode payment_method_types)
• Latest API version + SDK use

Absolutely forbidden

• ❌ Charges API (legacy, migrate to PaymentIntents)
• ❌ Card Element / Payment Element card mode (legacy)
• ❌ Sources API (deprecated)
• ❌ Tokens API (use SetupIntents)
• ❌ Hardcoding payment_method_types (use dynamic payment methods)

Applying to our game/app

Selection by scenario

수익화 유형 → 무엇을 파는가?
├─ 일회성 게임 구매 → CheckoutSessions (one-time)
├─ 인앱 구매/아이템 → CheckoutSessions + metadata
├─ 월정액 구독 → Billing API + CheckoutSessions
├─ 기부/후원 → Payment Links (가장 간단)
└─ 마켓플레이스 → Stripe Connect (destination charges)

Basic implementation patterns

// 서버 (Node.js)
const session = await stripe.checkout.sessions.create({
  mode: 'payment',  // 또는 'subscription'
  line_items: [{
    price_data: {
      currency: 'usd',
      product_data: { name: 'Game Premium' },
      unit_amount: 999,  // $9.99 (센트 단위!)
    },
    quantity: 1,
  }],
  success_url: 'https://eastsea.monster/thanks?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://eastsea.monster/games/',
});
// session.url로 리다이렉트

Subscription model (SaaS/game premium)

• Billing API → subscription design guide: docs.stripe.com/billing/subscriptions/designing-integration
• Prioritize the CheckoutSessions + Billing combination
• Detect subscription status changes via webhooks

Platform (multiple game developers) → Connect

• destination charges — we accept liability
• on_behalf_of control merchant of record via parameter
• Do not mix charge types

Security checklist

• Use secret keys only server-side
• Verify webhook signatures
• Do not hardcode amounts/prices on the client (generate on the server)
• Complete the Go-live checklist: docs.stripe.com/get-started/checklist/go-live
• HTTPS required

Reference documentation

• Integration options: docs.stripe.com/payments/payment-methods/integration-options
• API tour: docs.stripe.com/payments-api/tour
• Go-live checklist: docs.stripe.com/get-started/checklist/go-live

Guardrails

• Explicit distinction between test mode vs live mode required — before running code, specify whether the current key is sk_test_ (test) or sk_live_ (live). When working in live mode, always output the [LIVE] tag in the logs.
• Double-confirm when changing amount/currency — unit_amount, currency When modifying the value, confirm the before/after amount with the Master before executing. Be careful of confusion in cents units ($9.99 → 999).
• Never expose the webhook secret — STRIPE_WEBHOOK_SECRET Never output the value in logs, response bodies, or client code. Manage it only via environment variables.
• Master confirmation before executing refund/cancellation operations — stripe.refunds.create(), subscription cancel() and other financially impactful operations require explicit Master approval before execution. Do not run these operations alone in automation scripts.