@sayren/store-sdk 0.1.0

package/src/schemas/payment.ts

@@ -0,0 +1,582 @@
+import { z } from "zod";
+import { type PageParams, pageSchema } from "./common";
+
+/**
+ * 스토어 결제(PG) 설정과 매출 리포트 계약.
+ *
+ * PG는 셀러가 직접 계약한다. 자격 증명은 스토어별로 저장되고, 비밀 값(시크릿 키·API Secret·
+ * 웹훅 시크릿)은 저장 후 다시 조회할 수 없다. 응답에는 앞 4자리 마스킹만 나온다. 공개 값
+ * (클라이언트 키·Store ID·채널 키)은 원래 브라우저 결제창에 노출되는 값이라 그대로 돌려준다.
+ */
+
+export const pgProviderSchema = z
+  .enum(["tosspayments", "portone"])
+  .describe("PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2)");
+export type PgProvider = z.infer<typeof pgProviderSchema>;
+
+export const pgPaymentMethodSchema = z
+  .enum(["CARD", "BANK_TRANSFER", "VIRTUAL_ACCOUNT", "MOBILE", "EASY_PAY"])
+  .describe("결제수단 (스토어프론트 결제 요청의 `paymentMethod`와 같은 값)");
+export type PgPaymentMethod = z.infer<typeof pgPaymentMethodSchema>;
+
+export const paymentRoutingModeSchema = z
+  .enum(["PRIORITY_DISPLAY", "AUTO_FAILOVER"])
+  .describe(
+    "PG가 둘 이상 사용 중일 때의 라우팅 방식. `PRIORITY_DISPLAY`=결제창에 사용 중인 PG를 모두 보여 주고 1순위를 기본 선택, " +
+      "`AUTO_FAILOVER`=1순위로 결제창을 열고, 결제창을 띄우기 전 장애(PG 준비 실패)일 때만 다음 순위로 자동 전환",
+  );
+export type PaymentRoutingMode = z.infer<typeof paymentRoutingModeSchema>;
+
+export const effectivePaymentRoutingModeSchema = z
+  .enum(["NONE", "SINGLE", "PRIORITY_DISPLAY", "AUTO_FAILOVER"])
+  .describe(
+    "실제로 적용되는 라우팅. 사용 중인 PG가 0개면 `NONE`(결제 불가), 1개면 `SINGLE`, 2개 이상이면 `routingMode` 값",
+  );
+export type EffectivePaymentRoutingMode = z.infer<typeof effectivePaymentRoutingModeSchema>;
+
+export const pgEnvironmentSchema = z
+  .enum(["TEST", "LIVE"])
+  .describe(
+    "PG 결제 환경. `TEST`=PG 샌드박스(테스트 키, 실제로 돈이 오가지 않음), `LIVE`=실결제(운영 키)",
+  );
+export type PgEnvironment = z.infer<typeof pgEnvironmentSchema>;
+
+export const pgVerificationResultSchema = z
+  .enum(["SUCCESS", "FAILED"])
+  .describe("연결 테스트 결과");
+export type PgVerificationResult = z.infer<typeof pgVerificationResultSchema>;
+
+// ─── 자격 증명 입력 ─────────────────────────────────────────
+
+/** 비밀 값 입력 — 저장 후 다시 조회할 수 없다 */
+const secretInput = () => z.string().trim().min(8).max(512);
+
+/**
+ * 토스페이먼츠 결제위젯 키 접두사. 결제창은 API 개별 연동(`*_ck_`·`*_sk_`)만 쓴다. 위젯 키는 결제창 SDK가
+ * `NOT_SUPPORTED_WIDGET_KEY`로, 서버 API가 404 `NOT_FOUND_MERCHANT`로 거부하므로 저장 전에 막는다.
+ * 요청 스키마·api 어댑터·콘솔 폼이 같은 상수를 쓴다(원천). `g` 플래그가 없어 `.test()`가 상태를 갖지 않는다.
+ */
+export const TOSS_WIDGET_CLIENT_KEY_PATTERN = /^(test|live)_gck_/;
+/** 토스페이먼츠 결제위젯 시크릿 키 접두사. {@link TOSS_WIDGET_CLIENT_KEY_PATTERN} 참고 */
+export const TOSS_WIDGET_SECRET_KEY_PATTERN = /^(test|live)_gsk_/;
+/** 결제위젯 키를 거부할 때의 필드 메시지 */
+export const TOSS_WIDGET_KEY_MESSAGE = "결제위젯 키가 아니라 API 개별 연동 키를 입력해주세요";
+
+export const tossPaymentsCredentialsInputSchema = z
+  .object({
+    clientKey: z
+      .string()
+      .trim()
+      .min(8)
+      .max(200)
+      .describe("클라이언트 키 (`test_ck_…`/`live_ck_…`). 공개 값 — 결제창에서 쓰인다"),
+    secretKey: secretInput()
+      .optional()
+      .describe(
+        "시크릿 키 (`test_sk_…`/`live_sk_…`). 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다",
+      ),
+    webhookSecret: secretInput()
+      .nullable()
+      .optional()
+      .describe("웹훅 서명 검증용 보안 키. 비밀 값. 생략하면 기존 값 유지, null이면 삭제"),
+  })
+  .superRefine((value, ctx) => {
+    // 칸마다 따로 짚는다 — 둘 다 위젯 키면 이슈 2개
+    if (TOSS_WIDGET_CLIENT_KEY_PATTERN.test(value.clientKey)) {
+      ctx.addIssue({ code: "custom", path: ["clientKey"], message: TOSS_WIDGET_KEY_MESSAGE });
+    }
+    if (value.secretKey !== undefined && TOSS_WIDGET_SECRET_KEY_PATTERN.test(value.secretKey)) {
+      ctx.addIssue({ code: "custom", path: ["secretKey"], message: TOSS_WIDGET_KEY_MESSAGE });
+    }
+  });
+export type TossPaymentsCredentialsInput = z.infer<typeof tossPaymentsCredentialsInputSchema>;
+
+/** 포트원 채널 목록 최소 개수. 결제수단을 받으려면 채널이 하나는 있어야 한다 */
+export const PORTONE_MIN_CHANNELS = 1;
+/** 포트원 채널 목록 최대 개수 */
+export const PORTONE_MAX_CHANNELS = 20;
+/** 포트원 채널 표시 이름 최대 길이 */
+export const PORTONE_CHANNEL_NAME_MAX_LENGTH = 50;
+
+export const portOneChannelSchema = z.object({
+  channelKey: z
+    .string()
+    .trim()
+    .min(8)
+    .max(200)
+    .describe("포트원 콘솔 [연동 정보] > [채널 관리]의 채널 키. 공개 값"),
+  name: z
+    .string()
+    .trim()
+    .max(PORTONE_CHANNEL_NAME_MAX_LENGTH)
+    .nullable()
+    .optional()
+    .describe("채널 표시 이름 (예: 카드 전용)"),
+  payMethods: z
+    .array(pgPaymentMethodSchema)
+    .min(1)
+    .max(pgPaymentMethodSchema.options.length)
+    .describe("이 채널로 받을 결제수단. 결제수단마다 먼저 나열된 채널이 쓰인다"),
+});
+export type PortOneChannel = z.infer<typeof portOneChannelSchema>;
+
+export const portOneCredentialsInputSchema = z.object({
+  storeId: z.string().trim().min(8).max(200).describe("포트원 Store ID (`store-…`). 공개 값"),
+  channels: z
+    .array(portOneChannelSchema)
+    .min(PORTONE_MIN_CHANNELS)
+    .max(PORTONE_MAX_CHANNELS)
+    .describe(
+      "채널 목록. 포트원 V2는 PG·결제수단별로 채널을 따로 추가하므로 여러 개를 등록할 수 있다",
+    ),
+  apiSecret: secretInput()
+    .optional()
+    .describe("V2 API Secret. 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
+  webhookSecret: secretInput()
+    .nullable()
+    .optional()
+    .describe("웹훅 서명 검증용 시크릿. 비밀 값. 생략하면 기존 값 유지, null이면 삭제"),
+});
+export type PortOneCredentialsInput = z.infer<typeof portOneCredentialsInputSchema>;
+
+const upsertEnvironment = () =>
+  pgEnvironmentSchema.describe(
+    "저장할 자격 증명 세트. PG마다 `TEST`(샌드박스)·`LIVE`(실결제) 세트를 따로 둔다. " +
+      "어느 세트로 결제할지는 이 값이 아니라 샌드박스 스위치(`sandboxMode`)가 정한다",
+  );
+
+export const upsertTossPaymentsProviderRequestSchema = z.object({
+  environment: upsertEnvironment(),
+  credentials: tossPaymentsCredentialsInputSchema,
+});
+export type UpsertTossPaymentsProviderRequest = z.infer<
+  typeof upsertTossPaymentsProviderRequestSchema
+>;
+
+export const upsertPortOneProviderRequestSchema = z.object({
+  environment: upsertEnvironment(),
+  credentials: portOneCredentialsInputSchema,
+});
+export type UpsertPortOneProviderRequest = z.infer<typeof upsertPortOneProviderRequestSchema>;
+
+export const updatePaymentProviderRequestSchema = z
+  .object({
+    enabled: z
+      .boolean()
+      .optional()
+      .describe(
+        "사용 여부. 켜려면 활성 환경(샌드박스면 TEST, 아니면 LIVE) 자격 증명이 모두 저장돼 있어야 한다(`PAYMENT_PROVIDER_INCOMPLETE`)",
+      ),
+    sandboxMode: z
+      .boolean()
+      .optional()
+      .describe(
+        "샌드박스 스위치. `true`면 새 결제에 TEST 세트를 쓴다(항상 허용). `false`(라이브 전환)는 라이브 개방 조건을 " +
+          "모두 충족해야 한다(`LIVE_GATE_NOT_MET`)",
+      ),
+  })
+  .refine((body) => body.enabled !== undefined || body.sandboxMode !== undefined, {
+    message: "enabled 또는 sandboxMode 중 하나는 보내야 해요",
+  });
+export type UpdatePaymentProviderRequest = z.infer<typeof updatePaymentProviderRequestSchema>;
+
+export const verifyPaymentProviderRequestSchema = z.object({
+  environment: pgEnvironmentSchema
+    .optional()
+    .describe("연결 테스트할 자격 증명 세트. 생략하면 활성 환경(샌드박스면 TEST, 아니면 LIVE)"),
+});
+export type VerifyPaymentProviderRequest = z.infer<typeof verifyPaymentProviderRequestSchema>;
+
+export const updatePaymentSettingsRequestSchema = z.object({
+  routingMode: paymentRoutingModeSchema,
+  priority: z
+    .array(pgProviderSchema)
+    .min(1)
+    // PG 개수와 무관한 안전장치 — 거대한 배열이 파싱을 거치지 않게만 막는다. 실제 개수는 서버가 본다
+    .max(50)
+    .describe(
+      "PG 우선순위(앞이 1순위). 연결된 PG 수만큼 **모두 한 번씩** 나열한다(길이 상한 50은 안전장치다). " +
+        "빠지거나 중복되거나 연결되지 않은 PG가 있으면 `INVALID_PRIORITY`",
+    ),
+});
+export type UpdatePaymentSettingsRequest = z.infer<typeof updatePaymentSettingsRequestSchema>;
+
+// ─── 조회 응답 ─────────────────────────────────────────────
+
+export const maskedSecretSchema = z.object({
+  field: z.string().describe("비밀 필드 이름 (`secretKey`·`apiSecret`·`webhookSecret`)"),
+  configured: z.boolean().describe("값이 저장돼 있는가"),
+  masked: z
+    .string()
+    .nullable()
+    .describe("앞 4자리만 남긴 마스킹 값 (예: `test****`). 저장되지 않았으면 null"),
+});
+export type MaskedSecret = z.infer<typeof maskedSecretSchema>;
+
+const publicConfigSchema = z.union([
+  z.object({ clientKey: z.string() }),
+  z.object({ storeId: z.string(), channels: z.array(portOneChannelSchema) }),
+]);
+
+const verificationSchema = z.object({
+  result: pgVerificationResultSchema,
+  message: z.string().nullable(),
+  checkedAt: z.string(),
+});
+
+export const paymentCredentialSetSchema = z.object({
+  environment: pgEnvironmentSchema,
+  publicConfig: publicConfigSchema.describe(
+    "공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`",
+  ),
+  secrets: z
+    .array(maskedSecretSchema)
+    .describe("비밀 값의 저장 여부와 마스킹. 평문은 어떤 응답에도 나오지 않는다"),
+  lastVerification: verificationSchema
+    .nullable()
+    .describe("이 세트의 마지막 연결 테스트 결과. 세트를 바꾸면 초기화된다"),
+  updatedAt: z.string(),
+});
+export type PaymentCredentialSet = z.infer<typeof paymentCredentialSetSchema>;
+
+export const liveGateConditionCodeSchema = z
+  .enum([
+    "TEST_CONNECTION",
+    "SANDBOX_PAYMENT",
+    "SANDBOX_REFUND",
+    "LIVE_CONNECTION",
+    "PLATFORM_LIVE_ENABLED",
+  ])
+  .describe(
+    "라이브 개방 조건. `TEST_CONNECTION`=TEST 세트 연결 테스트 성공, `SANDBOX_PAYMENT`=현재 TEST 세트로 샌드박스 결제 1건 승인, " +
+      "`SANDBOX_REFUND`=그 샌드박스 결제의 환불 1건 성공, `LIVE_CONNECTION`=LIVE 세트 연결 테스트 성공, " +
+      "`PLATFORM_LIVE_ENABLED`=플랫폼이 실결제를 열어 둠",
+  );
+export type LiveGateConditionCode = z.infer<typeof liveGateConditionCodeSchema>;
+
+export const liveGateConditionSchema = z.object({
+  code: liveGateConditionCodeSchema,
+  met: z.boolean().describe("충족 여부"),
+  message: z.string().describe("조건 설명 또는 미충족 사유"),
+});
+export type LiveGateCondition = z.infer<typeof liveGateConditionSchema>;
+
+export const liveGateSchema = z.object({
+  status: z
+    .enum(["LOCKED", "OPEN"])
+    .describe("`OPEN`=조건을 모두 충족해 샌드박스를 끌 수 있다, `LOCKED`=아직 끌 수 없다"),
+  conditions: z.array(liveGateConditionSchema),
+  openedAt: z.string().nullable().describe("마지막으로 라이브로 전환한 시각. 없으면 null"),
+});
+export type LiveGate = z.infer<typeof liveGateSchema>;
+
+/**
+ * 409 `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의 `ApiError.details` 형태.
+ * 응답 파싱용이라 관대하다 — 알 수 없는 키는 버리고, 형태가 다르면 safeParse 실패로 처리한다.
+ */
+export const liveGateErrorDetailsSchema = z.object({
+  conditions: z.array(liveGateConditionSchema).describe("라이브 개방 조건별 충족 여부 (순서 고정)"),
+});
+export type LiveGateErrorDetails = z.infer<typeof liveGateErrorDetailsSchema>;
+
+export const paymentProviderSchema = z.object({
+  provider: pgProviderSchema,
+  displayName: z.string().describe("표시 이름 (토스페이먼츠·포트원)"),
+  connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
+  enabled: z.boolean().describe("결제에 사용 중인가"),
+  priority: z
+    .number()
+    .int()
+    .nullable()
+    .describe("우선순위 (1이 가장 높다). 연결되지 않았으면 null"),
+  environment: pgEnvironmentSchema
+    .nullable()
+    .describe(
+      "새 결제에 쓰는 환경(활성 환경). 샌드박스 스위치가 켜져 있으면 `TEST`, 꺼져 있으면 `LIVE`. 연결되지 않았으면 null",
+    ),
+  publicConfig: publicConfigSchema
+    .nullable()
+    .describe(
+      "활성 환경 세트의 공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`. 활성 세트가 없으면 null",
+    ),
+  secrets: z
+    .array(maskedSecretSchema)
+    .describe("활성 환경 세트의 비밀 값 저장 여부와 마스킹. 평문은 어떤 응답에도 나오지 않는다"),
+  lastVerification: verificationSchema
+    .nullable()
+    .describe("활성 환경 세트의 마지막 연결 테스트 결과. 세트를 바꾸면 초기화된다"),
+  updatedAt: z.string().nullable(),
+  sandboxMode: z
+    .boolean()
+    .describe(
+      "샌드박스 스위치. `true`면 새 결제에 TEST 세트를 쓴다(실제로 돈이 오가지 않는다). 연결되지 않았으면 true",
+    ),
+  credentialSets: z
+    .object({
+      TEST: paymentCredentialSetSchema.nullable(),
+      LIVE: paymentCredentialSetSchema.nullable(),
+    })
+    .describe("환경별 자격 증명 세트. 등록되지 않은 세트는 null"),
+  liveGate: liveGateSchema.describe("라이브 개방 조건. 조건을 모두 충족해야 샌드박스를 끌 수 있다"),
+  retiredCredentialCount: z
+    .number()
+    .int()
+    .describe(
+      "보관된(가맹점 교체·연결 해제로 새 결제에 더 쓰이지 않는) 자격 증명 수. 그 가맹점으로 받은 결제의 환불·대사에 계속 쓰인다",
+    ),
+  routingExclusion: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "지금 새 결제의 후보가 아닌 사유. 후보면 null. 판정 원천은 서버 라우팅이다(콘솔이 다시 계산하지 않는다). " +
+        "후보가 아닌 PG에는 항상 사유 코드를 붙인다(연결 안 된 PG 포함) — 모든 PG는 `candidates`에 있거나 이 값이 null이 아니다. 현재 값: " +
+        "`NOT_CONNECTED`(연결 안 됨) · `DISABLED`(사용 중지) · `CREDENTIAL_MISSING`(활성 환경 자격 증명 없음) · " +
+        "`SANDBOX_IN_LIVE_STORE`(다른 PG가 라이브라 이 샌드박스 PG는 실구매자 결제에 쓰지 않음) · " +
+        "`PLATFORM_BLOCKED`(플랫폼이 실결제를 막음) · `MODE_MISMATCH`(라이브를 연 서버 모드와 현재 모드가 다름). " +
+        "값이 추가될 수 있어 문자열로 받는다 — 모르는 값은 후보 아님으로 다룬다." +
+        " 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(null)으로 읽는다",
+    ),
+});
+export type PaymentProvider = z.infer<typeof paymentProviderSchema>;
+
+/**
+ * `PaymentProvider.routingExclusion`의 현재 값 — 응답 스키마는 서버가 사유를 추가해도 파싱이 깨지지 않게 문자열로 받는다.
+ * 화면 문구 분기는 이 목록으로 하고, 모르는 값은 "후보 아님"으로 다룬다.
+ */
+export const PAYMENT_ROUTING_EXCLUSION_CODES = [
+  "NOT_CONNECTED",
+  "DISABLED",
+  "CREDENTIAL_MISSING",
+  "SANDBOX_IN_LIVE_STORE",
+  "PLATFORM_BLOCKED",
+  "MODE_MISMATCH",
+] as const;
+export type KnownPaymentRoutingExclusion = (typeof PAYMENT_ROUTING_EXCLUSION_CODES)[number];
+
+export const paymentSettingsSchema = z.object({
+  routingMode: paymentRoutingModeSchema.describe(
+    "저장된 라우팅 방식 (기본 `AUTO_FAILOVER`). PG가 하나뿐이면 무시된다",
+  ),
+  effectiveRoutingMode: effectivePaymentRoutingModeSchema,
+  providers: z
+    .array(paymentProviderSchema)
+    .describe("지원하는 모든 PG. 연결된 것은 우선순위순, 연결되지 않은 것은 뒤에 온다"),
+  environment: pgEnvironmentSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "지금 결제를 시작하면 쓰는 결제 환경. 사용 가능한 PG 중 하나라도 라이브면 `LIVE`(샌드박스 PG는 제외), 아니면 `TEST`. " +
+        "사용 가능한 PG가 없으면 null." +
+        " 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(null)으로 읽는다",
+    ),
+  candidates: z
+    .array(z.string())
+    .optional()
+    .default(() => [])
+    .describe(
+      "지금 결제를 시작하면 쓰는 PG, 우선순위순(`tosspayments`·`portone`). 비어 있으면 구매자가 결제할 수 없다. " +
+        "빠진 PG의 사유는 `providers[].routingExclusion` — 후보가 아닌 PG에는 항상 사유 코드를 붙인다." +
+        " 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(빈 배열)으로 읽는다",
+    ),
+});
+export type PaymentSettings = z.infer<typeof paymentSettingsSchema>;
+
+export const paymentProviderVerificationSchema = z.object({
+  provider: pgProviderSchema,
+  environment: pgEnvironmentSchema.describe("연결 테스트한 자격 증명 세트"),
+  result: pgVerificationResultSchema,
+  message: z.string().nullable().describe("실패 사유 또는 참고 메시지"),
+  checkedAt: z.string(),
+});
+export type PaymentProviderVerification = z.infer<typeof paymentProviderVerificationSchema>;
+
+// ─── 매출 리포트 ───────────────────────────────────────────
+
+export const salesReportGroupBySchema = z
+  .enum(["DAY", "PROVIDER", "METHOD", "PROVIDER_METHOD"])
+  .describe("행 집계 기준. 기본 `DAY`");
+export type SalesReportGroupBy = z.infer<typeof salesReportGroupBySchema>;
+
+const reportDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "날짜 형식은 YYYY-MM-DD 입니다");
+
+export const salesReportQuerySchema = z.object({
+  from: reportDate.describe("시작일 (YYYY-MM-DD, Asia/Seoul 기준, 포함)"),
+  to: reportDate.describe("종료일 (YYYY-MM-DD, 포함). from부터 최대 92일"),
+  provider: pgProviderSchema.optional().describe("PG 필터"),
+  method: pgPaymentMethodSchema
+    .optional()
+    .describe(
+      "결제수단 필터 — **실제 결제수단**(PG가 보고한 수단, 모르면 요청 수단) 기준. 결제창에서 결제수단이 바뀔 수 있다(카드 결제창의 간편결제 탭 등). " +
+        "관리 주문 API의 method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다",
+    ),
+  groupBy: salesReportGroupBySchema.optional(),
+  includeTest: z
+    .enum(["true", "false"])
+    .optional()
+    .describe(
+      "테스트 결제(샌드박스 결제) 포함 여부. 기본 `false` — 테스트 결제의 승인·환불은 집계에서 빠진다",
+    ),
+});
+export type SalesReportParams = z.infer<typeof salesReportQuerySchema>;
+
+export const salesTotalsSchema = z.object({
+  paymentCount: z.number().int().describe("승인 건수"),
+  paymentAmount: z.number().int().describe("승인 금액 합계"),
+  refundCount: z.number().int().describe("환불(취소) 건수. 부분 취소도 1건"),
+  refundAmount: z.number().int().describe("환불 금액 합계"),
+  netAmount: z.number().int().describe("순매출 = 승인 금액 - 환불 금액"),
+  pgFeeAmount: z
+    .number()
+    .int()
+    .nullable()
+    .describe("PG 수수료 (참고용). PG에서 확정 값을 받지 못하면 null"),
+});
+export type SalesTotals = z.infer<typeof salesTotalsSchema>;
+
+export const salesReportRowSchema = salesTotalsSchema.extend({
+  date: z.string().nullable().describe("일자 (YYYY-MM-DD, Asia/Seoul). groupBy=DAY일 때만 값"),
+  provider: pgProviderSchema.nullable().describe("PG. groupBy에 PROVIDER가 포함될 때만 값"),
+  method: pgPaymentMethodSchema
+    .nullable()
+    .describe(
+      "실제 결제수단(PG가 보고한 수단, 모르면 요청 수단). groupBy에 METHOD가 포함될 때만 값. " +
+        "관리 주문 API의 method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다",
+    ),
+});
+export type SalesReportRow = z.infer<typeof salesReportRowSchema>;
+
+export const salesReportSchema = z.object({
+  from: z.string(),
+  to: z.string(),
+  timezone: z.literal("Asia/Seoul"),
+  currency: z.literal("KRW"),
+  groupBy: salesReportGroupBySchema,
+  provider: pgProviderSchema.nullable().describe("적용된 PG 필터"),
+  method: pgPaymentMethodSchema.nullable().describe("적용된 결제수단 필터"),
+  includeTest: z.boolean().describe("테스트 결제(샌드박스 결제)를 집계에 포함했는가"),
+  summary: salesTotalsSchema.describe("기간 전체 합계"),
+  rows: z.array(salesReportRowSchema).describe("집계 행. 활동이 없는 날짜·PG는 생략된다"),
+});
+export type SalesReport = z.infer<typeof salesReportSchema>;
+
+/**
+ * 결제 내역 — 결제 건(세션) 단위 공개 상태. 주문 단위 상태와 다르다.
+ * - `APPROVED`: 승인됐고 환불이 없다
+ * - `PARTIALLY_REFUNDED`·`REFUNDED`: 승인 뒤 일부·전액을 환불했다
+ * - `PENDING`: 승인 결과를 아직 확정하지 못했다(대사 잡이 확정한다)
+ * - `FAILED`: 승인되지 않고 끝났다(거절·준비 장애·구매자 취소·만료)
+ */
+export const paymentRecordStatusSchema = z.enum([
+  "APPROVED",
+  "PARTIALLY_REFUNDED",
+  "REFUNDED",
+  "PENDING",
+  "FAILED",
+]);
+export type PaymentRecordStatus = z.infer<typeof paymentRecordStatusSchema>;
+
+export const paymentAttemptStatusSchema = z
+  .string()
+  .describe(
+    "시도 상태 — ready·approving·approved·unknown·declined·prepare_failed·canceled·failed·abandoned·voided. " +
+      "새 값이 추가될 수 있으니 모르는 값은 '진행 중이 아닌 시도'로 다룬다",
+  );
+
+export const paymentRecordSchema = z.object({
+  paymentId: z.string().describe("결제 건 id. 상세 조회 키"),
+  orderId: z.string().nullable().describe("승인돼 만들어진 주문. 승인 전에 끝난 결제는 null"),
+  orderName: z.string().describe("주문명 (예: 무선 이어폰 프로 외 1건)"),
+  customerName: z.string().describe("구매자명"),
+  status: paymentRecordStatusSchema,
+  amount: z.number().int().describe("결제 금액"),
+  refundedAmount: z.number().int().describe("환불 완료 금액 합계. 실패한 환불은 빼고 센다"),
+  provider: pgProviderSchema.nullable().describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
+  method: pgPaymentMethodSchema.nullable().describe("실제 결제수단. 모르면 요청 수단"),
+  environment: pgEnvironmentSchema.nullable().describe("결제 환경"),
+  testPayment: z.boolean().describe("샌드박스 결제인가"),
+  pgTransactionId: z.string().nullable().describe("PG 거래 id (토스 paymentKey, 포트원 txId)"),
+  attemptId: z.string().nullable().describe("PG에 보낸 주문번호 = 시도 id"),
+  attemptCount: z.number().int().describe("시도 횟수"),
+  failCode: z.string().nullable().describe("실패 코드. 실패로 끝난 결제만"),
+  failMessage: z.string().nullable().describe("실패 사유"),
+  paidAt: z.string().nullable().describe("승인 시각 (ISO 8601)"),
+  createdAt: z.string().describe("결제 시작 시각 (ISO 8601)"),
+});
+export type PaymentRecord = z.infer<typeof paymentRecordSchema>;
+
+export const paymentRecordPageSchema = pageSchema(paymentRecordSchema);
+export type PaymentRecordPage = z.infer<typeof paymentRecordPageSchema>;
+
+export const paymentAttemptRecordSchema = z.object({
+  attemptId: z.string(),
+  sequence: z.number().int().describe("결제 건 안에서의 순번 (1부터)"),
+  provider: pgProviderSchema,
+  status: paymentAttemptStatusSchema,
+  method: pgPaymentMethodSchema.describe("주문서에서 고른 결제수단"),
+  approvedMethod: pgPaymentMethodSchema.nullable().describe("PG가 보고한 실제 결제수단"),
+  amount: z.number().int(),
+  environment: pgEnvironmentSchema,
+  pgTransactionId: z.string().nullable(),
+  failCode: z.string().nullable(),
+  failMessage: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type PaymentAttemptRecord = z.infer<typeof paymentAttemptRecordSchema>;
+
+export const paymentRefundRecordSchema = z.object({
+  refundId: z.string(),
+  amount: z.number().int(),
+  reason: z.string().describe("환불 사유 코드"),
+  kind: z
+    .string()
+    .describe("환불 원인 — SELLER_CANCEL·CLAIM·COMPENSATION·DUPLICATE. 새 값이 추가될 수 있다"),
+  status: z.string().describe("SUCCEEDED·FAILED"),
+  failMessage: z.string().nullable(),
+  requestedAt: z.string(),
+  completedAt: z.string().nullable(),
+});
+export type PaymentRefundRecord = z.infer<typeof paymentRefundRecordSchema>;
+
+export const paymentRecordDetailSchema = paymentRecordSchema.extend({
+  refundableAmount: z.number().int().describe("환불 가능 잔액 = 승인 금액 - 환불 완료 금액"),
+  merchantId: z
+    .string()
+    .nullable()
+    .describe("가맹점 식별자 지문 (토스 clientKey, 포트원 Store ID). 비밀 값은 없다"),
+  attempts: z.array(paymentAttemptRecordSchema).describe("시도 이력. 순번 오름차순"),
+  refunds: z.array(paymentRefundRecordSchema).describe("환불 이력. 실패한 요청도 남는다"),
+});
+export type PaymentRecordDetail = z.infer<typeof paymentRecordDetailSchema>;
+
+/** `GET /v1/payments` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+export const paymentListQuerySchema = z.object({
+  from: z.string().optional().describe("조회 시작 시각 (ISO 8601, 포함). 생략하면 최근 30일"),
+  to: z.string().optional().describe("조회 끝 시각 (ISO 8601, 포함). 기간은 최대 92일"),
+  status: z.string().optional().describe("결제 상태 필터 (PaymentRecordStatus)"),
+  provider: z.string().optional().describe("PG 필터"),
+  method: z.string().optional().describe("실제 결제수단 필터"),
+  keyword: z
+    .string()
+    .optional()
+    .describe("결제 id·주문번호·PG 거래 id·시도 id(일치), 구매자명(포함)"),
+  includeTest: z
+    .string()
+    .optional()
+    .describe("테스트 결제 포함 여부 (`true`·`false`. 기본 false — 실결제만)"),
+  page: z.string().optional().describe("페이지 번호 (1부터)"),
+  size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)"),
+});
+
+export interface PaymentListParams extends PageParams {
+  from?: string;
+  to?: string;
+  status?: PaymentRecordStatus;
+  provider?: PgProvider;
+  method?: PgPaymentMethod;
+  keyword?: string;
+  includeTest?: boolean;
+}