# Docenty Pay (dct-pay)

> 온라인에서 파는 모든 것(앱 이용권·후원·과일·상담·참가권·파일)에 결제를 붙이는 플랫폼 — "한국판 Lemon Squeezy". 창작자·판매자는 PG 직접 계약 없이 결제 링크(/u/:handle), 상품 페이지(/u/:handle/p/:id), 청구서(알림톡/이메일), 한 줄 SDK로 카드·간편결제(카카오/네이버/토스)·가상계좌·계좌이체를 받는다. 대금은 수수료(판매 5%+300원, 후원 5%, 결제 시점 스냅샷)를 뺀 빌드 크레딧(BC, 현금 아님·환급 불가)으로 적립되고, 월 1회 현금 출금(개인 3.3% 원천징수/사업자 세금계산서) 또는 서비스 비용 대납(클라우드·LLM·광고·도메인·호스팅·알림톡)에 쓴다.

## 활용 사례 (누구에게, 지금 방식 대비 무엇이 달라지나)
- /cases — 8개 사례 목록
- /cases/app 바이브코더 앱 이용권 · /cases/creator AI 콘텐츠 크리에이터(전자책·프롬프트·템플릿) · /cases/fruit 과일·산지직송 · /cases/class 원데이클래스·학원·예약 · /cases/consult 상담료·코칭 · /cases/interior 인테리어 시공·자재 · /cases/freelance 프리랜서 대금 · /cases/event 예매·행사

## 시작
- 사람: https://pay.docenty.ai/login (이메일 매직링크) → 핸들 → 공개 페이지 또는 앱 등록
- 에이전트(Claude Code): `npx skills add ctb-rebooted/dct-pay-skill` → `/dct-pay pay` | `/dct-pay earn`
- CLI: `node ~/.claude/skills/dct-pay/scripts/dct-pay.mjs login` (디바이스 코드; 키를 채팅에 붙여넣지 않음)

## 자격증명
- `dce_pk_…` 앱 공개 키: 브라우저 SDK / x-app-key 라우트 (checkouts, entitlements, credits/consume, events, apps/ping). CORS는 앱 등록 URL origin + 등록한 dev origin(localhost)만.
- `dce_pk_test_…` 테스트 앱 키: 가짜 결제창(/pay/:id/test), 원장·알림 없음. test/live 앱은 서로 다른 불변 행, 키 접두와 앱 모드가 일치해야 한다.
- 주문 링크 `/o/<token>`: 구매자용 capability (조회·입금 신고·수령 확인·문제 신고·환불 계좌·문의). GET은 상태를 바꾸지 않는다. 회수·재발급은 대시보드.
- `dce_sk_…` 창작자 시크릿: Bearer. 대시보드 설정 또는 CLI 로그인으로만 발급(1회 표시).
- 세션 쿠키: /dashboard.

## 핵심 규칙
- 창작자의 입금 확인(confirm)은 구매자 이용 권한만 준다. BC는 Docenty 입금 검증(verified_at) 또는 포트원 검증 결제에서만 적립된다.
- BC는 pending 7일 후 spendable. 환불 시 pending→reversed, spendable→음수 adjust(잔액 음수 허용, 그동안 사용 신청 불가).
- 상품 kind: one_time(권한), credit_pack(앱 안 크레딧), tip(앱당 1개, 1,000~100,000원), physical(배송·옵션·재고·배송비), service(예약), ticket(참가권), digital_file. 템플릿: fruit(과일)·consulting(상담) — `POST /api/templates/apply`.
- 실물·상담·참가권 BC는 `released_at`(구매자 수령 확인 OR 이행 후 D+7 OR 분쟁 종결)에 spendable로 적립. 발송(ship)은 Docenty 입금 확인 후에만.
- 결제 생성: `variantId`(옵션 상품 필수)·`qty`(1~99)·`fulfillmentData`(결제 전 필수, `POST /checkouts/:id/fulfillment`)·`payMethod`/`easyPayProvider`·선택 `Idempotency-Key`(앱 범위 24h; 다른 본문 409 IDEMPOTENCY_CONFLICT).
- 상태: `status` 외에 `payment/verification/fulfillment/hold` 4상태. `pending_review`(금액 불일치·재고 없음)는 "확인 중"이며 폴링 종료 상태.
- 결제 전이는 `lib/payments/transition.ts` 하나만 PG 상태를 반영한다(webhook/complete/return/reconcile 공통, `payment_attempts` 로 paymentId 매핑). 환불은 라인(qty)·배송비 단위, ops 환불은 client `refundId` 필수 + 포트원 취소 선행.
- 청구서: `POST /api/invoices {appId, to:{phone|email}, productId|amountKrw, note}` → `{invoiceId, checkoutId, orderUrl, deliveryStatus}`; 상태 draft/queued/sent/delivered/failed/noop/viewed/paid/expired — `noop`(알림톡 채널 없음·테스트 앱)은 "발송됨"이 아니다. 리마인드(D+1/D+3)는 구매자가 링크에서 "청구서 확인"을 누른 뒤에만, 최대 2회. 알림톡은 정보성 템플릿만(광고 불가).
- 거래처: `buyer_groups` + 서명 링크 `/u/:handle?g=` (회수 가능, 가격 비공개는 "가격 문의", 0원 표시 금지).
- 출금: `PUT /api/creators/me/kyc` 후 `POST /api/payouts {amountKrw>=30000, idempotencyKey}`; 원장 `reason=payout`; 매월 10일 승인 배치, 송금 결과 불명은 `unknown`(복원 없음), 확정 실패만 BC 1회 복원. 대납: `POST /api/bill-pay {vendor, amountKrw, invoiceRef}` (월 한도, vendor+invoiceRef 유니크).
- NvLand: `POST /api/integrations/nvland/leads` 서명 규격은 sp_002 (X-Earn-Key-Id/Timestamp/Nonce/Signature v1=HMAC(ts\nnonce\nbody)) → 청구서 초안(자동 발송 없음).
- 오류 형식: {error:{code,message,fix,docUrl,retryAfterSec?}}. 500은 고정 문구 + requestId.

## 문서
- https://pay.docenty.ai/docs (퀵스타트 2경로, API 요약, 오류 코드, 자격증명 매트릭스)
- 계약서: docs/ai-gen/gstack/specs/sp_001_dct-earn-v0-contract.md (v1), sp_002_earn-nvland-contract.md (NvLand 서명), 플랜: pl_001 (v1), pl_002_dct-earn-commerce-v2.md (v2 커머스)
- SDK: @docenty/earn-sdk 1.1 (`/sdk/v1/earn.iife.js` 불변, createCheckout 인자 union, waitForCheckout 종료 집합 명시). CLI 1.1: `template list|inspect|apply`, `product add --kind physical|service --variants`, `invoice send|list|get`, `order list|fulfill`, `init`, `--input file.json --dry-run`.