Skip to content

Billing API

Status: Active / Owner: Backend / Last Updated: 2026-05-05 (세션 103)

Overview

Toss Payments 결제 / 정기 구독 / 환불 / Trial 발급.

Endpoints

POST /api/billing/subscribe

정기 구독 신청 (Toss Billing API).

Request:

{
  "workspace_id": "ws_xxx",
  "plan": "pro_monthly",
  "billing_key": "billing_xxx"
}

Response:

{
  "success": true,
  "data": {
    "subscription_id": "sub_xxx",
    "next_billing_at": "2026-06-05T00:00:00+09:00"
  }
}

POST /api/billing/cancel

구독 취소 (다음 결제일 직전 실행).

POST /api/billing/refund

환불 요청 (Toss Refund API + DB 트랜잭션).

GET /api/billing/invoices

청구서 목록 조회.

POST /api/billing/trial

Trial 발급 (1회/계정, A04 STRENGTHENED 영속).

POST /api/billing/webhook

Toss webhook 수신 (HMAC 검증 영속).

Security

  • HMAC-SHA256 webhook 검증 영속 (A02 12중)
  • Idempotent key: Idempotency-Key 헤더 영속 (재시도 안전)
  • A09 PII 0: card 번호/billingKey 로그 출력 0 (sanitize 4 stage)
  • ADR-0131 (git autostash 표준)
  • services/toss_payments.py
  • ADR-0113 (env-only Toss key 영속)