api-contract.yaml

openapi: 3.1.0
info:
  title: 3ds2-demo Payment API
  version: 0.1.0
  description: |
    EMV 3-D Secure 2.x 統合学習デモの Payment API 契約定義。
    Stripe Payment Intents API をベースに、3DS2 challenge フローを
    明示的にハンドリングする backend の REST 仕様。

    ## 関連ドキュメント
    - 3DS2 仕様概観: `docs/3ds2-overview-ja.md`
    - State Machine 詳細: `docs/architecture.md`

  contact:
    name: 3ds2-demo
    url: https://github.com/izdev0000/3ds2-demo
  license:
    name: MIT
    url: https://github.com/izdev0000/3ds2-demo/blob/main/LICENSE

servers:
  - url: http://localhost:8000
    description: ローカル開発環境（docker compose）

tags:
  - name: orders
    description: 注文（業務単位）の作成・取得
  - name: payments
    description: Payment Intent の作成・確認・状態取得
  - name: webhooks
    description: PSP からの webhook 受信
  - name: debug
    description: 学習デモ用の補助 endpoint (本番化時は無効化推奨)

paths:
  /api/orders:
    post:
      tags: [orders]
      summary: 仮注文を作成
      description: |
        決済前段階の Order を `pending` 状態で作成する。
        Order は業務上の注文単位であり、決済（Transaction）は 1 Order に対し N 件
        紐づく（失敗で別カード再決済するケースに対応）。

        Order.status は webhook 経由でのみ `paid` に遷移する。
        frontend からの confirm 成功 response や return_url 到達では遷移しない
        （docs/design/error-handling.md §8.4 参照）。
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              single_item:
                summary: 商品 1 点の注文
                value:
                  currency: jpy
                  items:
                    - name: T-shirt (S)
                      quantity: 1
                      unit_price: 1000
              multi_item:
                summary: 商品複数点の注文
                value:
                  currency: jpy
                  items:
                    - name: T-shirt (S)
                      quantity: 2
                      unit_price: 1000
                    - name: Sticker pack
                      quantity: 1
                      unit_price: 500
      responses:
        '201':
          description: 作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /api/orders/{id}:
    get:
      tags: [orders]
      summary: Order の現在状態を取得
      description: |
        内部 ID から Order の現在状態と明細を返す。`status` は業務状態
        (pending / paid / canceled / refunded)。webhook 経由でのみ paid に
        遷移するため、決済直後でも未反映の場合は pending のままになる
        (詳細は docs/design/order-lifecycle.md §2)。
      operationId: getOrder
      parameters:
        - $ref: '#/components/parameters/OrderIdPath'
      responses:
        '200':
          description: 取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/payments:
    post:
      tags: [payments]
      summary: PaymentIntent を作成
      description: |
        新規の Payment Intent を作成する。Stripe 側でも対応する PaymentIntent が
        生成され、`request_three_d_secure: 'any'` を付与して
        frictionless / challenge どちらの経路でも 3DS2 を経由するよう要求する。

        EMVCo 3DS2 メッセージフローでは AReq に相当するタイミング。
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
            examples:
              jpy_basic:
                summary: 既存 Order に対する決済（フリクションレス想定）
                value:
                  order_id: ord_01HYZ800
              jpy_with_return:
                summary: redirect 経路用に return_url 付き
                value:
                  order_id: ord_01HYZ800
                  return_url: http://localhost:5173/payments/return
      responses:
        '201':
          description: 作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/payments/{id}:
    get:
      tags: [payments]
      summary: PaymentIntent の状態を取得
      description: |
        内部 ID から PaymentIntent の現在状態と Stripe 側の最新ステータスを返す。
        本 endpoint は client が webhook 反映後の最終状態を確認するために使う。
      operationId: getPayment
      parameters:
        - $ref: '#/components/parameters/PaymentIdPath'
      responses:
        '200':
          description: 取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/payments/{id}/confirm:
    post:
      tags: [payments]
      summary: PaymentIntent を confirm
      description: |
        Stripe.js の Stripe Elements で生成した payment_method_id を渡して
        PaymentIntent を confirm する。

        3DS2 が必要な場合は `status = requires_action` が返り、`next_action` に
        challenge 情報が入る。frontend はその type に応じて：
        - `use_stripe_sdk`: inline challenge → `stripe.handleNextAction(client_secret)` 呼び出し
        - `redirect_to_url`: 別ページへ遷移

        EMVCo 3DS2 メッセージフローでは ARes / CReq の判定に相当する。
      operationId: confirmPayment
      parameters:
        - $ref: '#/components/parameters/PaymentIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmPaymentRequest'
            examples:
              frictionless:
                summary: フリクションレスで通る想定（テストカード 4000008400001629）
                value:
                  payment_method_id: pm_card_visa
              challenge_required:
                summary: 3DS2 challenge を発火させる（テストカード 4000002760003184）
                value:
                  payment_method_id: pm_card_threeDSecureRequired
      responses:
        '200':
          description: confirm 完了またはアクション要求
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                requires_action:
                  summary: 3DS2 challenge が必要な場合
                  value:
                    id: txn_01HYZ800
                    order_id: ord_01HYZ800
                    psp_payment_intent_id: pi_3RT...
                    client_secret: pi_3RT..._secret_xyz
                    status: requires_action
                    amount: 1000
                    currency: jpy
                    next_action:
                      type: use_stripe_sdk
                      use_stripe_sdk:
                        type: three_d_secure_redirect
                    created_at: '2026-05-10T19:00:00Z'
                    updated_at: '2026-05-10T19:00:01Z'
                succeeded:
                  summary: フリクションレスで成功した場合
                  value:
                    id: txn_01HYZ801
                    order_id: ord_01HYZ800
                    psp_payment_intent_id: pi_3RT...
                    client_secret: pi_3RT..._secret_xyz
                    status: succeeded
                    amount: 1000
                    currency: jpy
                    next_action: null
                    created_at: '2026-05-10T19:00:00Z'
                    updated_at: '2026-05-10T19:00:01Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /api/payments/{id}/events:
    get:
      tags: [payments]
      summary: PaymentIntent に紐づく webhook イベント履歴
      description: |
        State Machine の遷移を可視化するため、当該 PaymentIntent に対応する
        webhook イベントを時系列（古い順）で返す。
      operationId: listPaymentEvents
      parameters:
        - $ref: '#/components/parameters/PaymentIdPath'
      responses:
        '200':
          description: イベント一覧
          content:
            application/json:
              schema:
                type: object
                required: [events]
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentEvent'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/_debug/recent-rows:
    get:
      tags: [debug]
      summary: 各テーブルの直近 5 行を返す (デモ可視化用)
      description: |
        orders / transactions / order_items / webhook_events の最新 5 行を
        まとめて返す。frontend がポーリングしてデータフローを観察できる
        ようにするための補助 endpoint。

        本デモは TEST 環境専用のため認証なし。本番化する場合は middleware で
        local 限定にすること。
      operationId: getDebugRecentRows
      responses:
        '200':
          description: 最新 5 行
          content:
            application/json:
              schema:
                type: object
                required: [orders, transactions, order_items, webhook_events]
                properties:
                  orders:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  transactions:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  order_items:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  webhook_events:
                    type: array
                    items:
                      type: object
                      additionalProperties: true

  /api/webhooks/stripe:
    post:
      tags: [webhooks]
      summary: Stripe webhook 受信
      description: |
        Stripe から送られてくる webhook イベントを受け取る endpoint。
        `Stripe-Signature` ヘッダで HMAC-SHA256 署名を検証し、検証成功時のみ
        State Machine の遷移と DB 反映を行う。

        本 endpoint は frontend からは呼ばれない。ローカル開発では Stripe CLI で
        forward する：
        ```
        stripe listen --forward-to localhost:8000/api/webhooks/stripe
        ```
      operationId: receiveStripeWebhook
      parameters:
        - in: header
          name: Stripe-Signature
          required: true
          schema:
            type: string
          description: Stripe による HMAC-SHA256 署名（`t=…,v1=…` 形式）
          example: t=1234567890,v1=abc...
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StripeWebhookEvent'
      responses:
        '204':
          description: 受信成功（処理は idempotent）
        '400':
          description: 署名検証失敗 / リクエスト形式不正
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  parameters:
    PaymentIdPath:
      in: path
      name: id
      required: true
      schema:
        type: string
        pattern: '^txn_[A-Za-z0-9]+$'
      description: 内部 transaction ID（`txn_` プレフィックス + ULID 等）
      example: txn_01HYZ800
    OrderIdPath:
      in: path
      name: id
      required: true
      schema:
        type: string
        pattern: '^ord_[A-Za-z0-9]+$'
      description: 内部 order ID（`ord_` プレフィックス + ULID 等）
      example: ord_01HYZ800

  schemas:
    CreateOrderRequest:
      type: object
      required: [currency, items]
      properties:
        currency:
          type: string
          minLength: 3
          maxLength: 3
          pattern: '^[a-z]{3}$'
          description: ISO 4217 通貨コード（小文字）
          example: jpy
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderItemInput'
        metadata:
          type: object
          additionalProperties: true
          description: 任意の業務メタデータ

    OrderItemInput:
      type: object
      required: [name, quantity, unit_price]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          example: T-shirt (S)
        quantity:
          type: integer
          minimum: 1
          example: 1
        unit_price:
          type: integer
          minimum: 0
          description: 通貨の最小単位（JPY なら円、USD ならセント）
          example: 1000

    OrderResponse:
      type: object
      required: [id, status, amount, currency, items, created_at, updated_at]
      properties:
        id:
          type: string
          description: 内部 order ID
          example: ord_01HYZ800
        status:
          $ref: '#/components/schemas/OrderStatus'
        amount:
          type: integer
          description: items の合計金額（quantity * unit_price の総和）
          example: 1000
        currency:
          type: string
          example: jpy
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        metadata:
          type:
            - object
            - 'null'
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    OrderItem:
      allOf:
        - $ref: '#/components/schemas/OrderItemInput'
        - type: object
          required: [id, subtotal]
          properties:
            id:
              type: string
              description: 内部 order item ID
              example: oit_01HYZ800
            subtotal:
              type: integer
              description: quantity * unit_price
              example: 1000

    OrderStatus:
      type: string
      description: |
        Order の業務状態。webhook 経由でのみ `paid` に遷移する。
        | status | 意味 |
        | --- | --- |
        | pending | 仮注文（決済未確定） |
        | paid | 決済成功・注文確定 |
        | canceled | 注文キャンセル（決済前 or 全 Transaction が canceled） |
        | refunded | 返金済み |
      enum:
        - pending
        - paid
        - canceled
        - refunded

    CreatePaymentRequest:
      type: object
      required: [order_id]
      properties:
        order_id:
          type: string
          pattern: '^ord_[A-Za-z0-9]+$'
          description: |
            紐づく Order の内部 ID。amount / currency は Order から導出するため
            request では指定しない（client 側で改竄できないようにする）。
          example: ord_01HYZ800
        return_url:
          type: string
          format: uri
          description: |
            redirect 経路の 3DS2 challenge 後に遷移する URL。
            inline challenge の場合は不要。
          example: http://localhost:5173/payments/return

    ConfirmPaymentRequest:
      type: object
      required: [payment_method_id]
      properties:
        payment_method_id:
          type: string
          description: |
            Stripe Elements 等で生成した PaymentMethod ID（`pm_…`）。
            テスト時は `pm_card_visa` 等のテスト用エイリアスも受け付ける。
          example: pm_card_visa
        flow:
          type: string
          enum: [client_sdk, server_redirect]
          default: client_sdk
          description: |
            confirmation 経路の指定。詳細は `docs/design/confirmation-flow.md` 参照。
            - `client_sdk`: frontend SDK が iframe で 3DS2 challenge を扱う
              (Stripe デフォルト)。`return_url` は任意。
            - `server_redirect`: backend が confirm 後、redirect URL を返却して
              issuer ページへ画面遷移する (国内 PSP で主流のパターン)。
              `return_url` 必須。
        return_url:
          type: string
          format: uri
          description: |
            3DS2 challenge 完了後の戻り URL。`flow=server_redirect` の場合は必須、
            `flow=client_sdk` の場合は任意。

    PaymentResponse:
      type: object
      required:
        - id
        - order_id
        - status
        - amount
        - currency
        - client_secret
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: 内部 transaction ID
          example: txn_01HYZ800
        order_id:
          type: string
          description: 紐づく Order の内部 ID
          example: ord_01HYZ800
        psp_payment_intent_id:
          type: string
          description: PSP 側の PaymentIntent ID (Stripe なら pi_..., Adyen なら pspReference 相当)
          example: pi_3RT0...
        client_secret:
          type: string
          description: |
            frontend が Stripe.js で 3DS2 challenge を完了させるために使う
            client_secret。エンドユーザーに露出してよいが秘密鍵 (sk_…) とは別物。
          example: pi_3RT0..._secret_xyz
        status:
          $ref: '#/components/schemas/PaymentStatus'
        amount:
          type: integer
          example: 1000
        currency:
          type: string
          example: jpy
        next_action:
          $ref: '#/components/schemas/NextAction'
        created_at:
          type: string
          format: date-time
          example: '2026-05-10T19:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-05-10T19:00:01Z'

    PaymentStatus:
      type: string
      description: |
        Stripe Payment Intent の状態。EMVCo 3DS2 メッセージフロー
        (AReq → ARes → CReq → CRes) との対応マッピングは `docs/architecture.md` 参照。

        | Stripe status              | EMVCo フェーズ      |
        | -------------------------- | ------------------- |
        | requires_payment_method    | 未送信              |
        | requires_confirmation      | AReq 直前           |
        | requires_action            | ARes / CReq         |
        | processing                 | CRes 後の processing |
        | succeeded                  | 認証成功 + 売上確定 |
        | requires_capture           | 認証成功 (manual capture 時) |
        | canceled                   | キャンセル          |
      enum:
        - requires_payment_method
        - requires_confirmation
        - requires_action
        - processing
        - requires_capture
        - canceled
        - succeeded

    NextAction:
      type:
        - object
        - 'null'
      description: |
        3DS2 challenge 等、frontend で追加処理が必要な場合に含まれる。
        Stripe の next_action オブジェクト構造に準拠（必要最小限のフィールドのみ抽出）。
      properties:
        type:
          type: string
          enum:
            - use_stripe_sdk
            - redirect_to_url
        use_stripe_sdk:
          type: object
          description: |
            inline challenge の場合に Stripe.js が解釈する詳細情報。
            構造は Stripe API 仕様に準拠（バージョン依存があるため透過）。
          additionalProperties: true
        redirect_to_url:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: redirect 先 URL（Stripe ホスト or PSP）
            return_url:
              type: string
              format: uri
              description: challenge 完了後の戻り URL

    PaymentEvent:
      type: object
      required: [id, event_type, received_at]
      properties:
        id:
          type: string
          description: 内部 event ID
          example: evt_01HYZ900
        psp_event_id:
          type: string
          description: PSP 側の event ID (idempotency 検証に使う)
          example: evt_3RT0...
        event_type:
          type: string
          description: PSP の event type (Stripe なら payment_intent.succeeded 等)
          example: payment_intent.succeeded
        payment_intent_id:
          type: string
          description: 紐づく PaymentIntent の内部 ID
          example: txn_01HYZ800
        received_at:
          type: string
          format: date-time
        processed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: 処理完了時刻。null は未処理を意味する

    StripeWebhookEvent:
      type: object
      description: |
        Stripe から送信される webhook payload。完全な仕様は Stripe API ドキュメント参照。
        ここでは検証に必要な最小限のフィールドのみ宣言する。
      required: [id, type]
      properties:
        id:
          type: string
          example: evt_3RT0...
        type:
          type: string
          example: payment_intent.succeeded
        data:
          type: object
          additionalProperties: true
          description: イベント本体（type に依存）
        created:
          type: integer
          description: Unix timestamp
      additionalProperties: true

    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: アプリケーション固有のエラーコード
          enum:
            - invalid_amount
            - invalid_currency
            - invalid_payment_method
            - validation_failed
            - payment_not_found
            - payment_already_confirmed
            - order_not_found
            - order_already_paid
            - order_already_canceled
            - signature_verification_failed
            - stripe_api_error
            - internal_error
          example: invalid_amount
        message:
          type: string
          description: 人間可読なエラーメッセージ
          example: amount must be at least 50
        details:
          type: object
          additionalProperties: true
          description: エラー固有の追加情報

  responses:
    BadRequest:
      description: 不正なリクエスト
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: リソースが存在しない
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: リクエストは valid だが状態的に処理できない
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: サーバ内部エラー（Stripe API 障害含む）
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'