@sayren/store-sdk 0.30.3 → 0.30.5

package/dist/index.mjs

@@ -92,6 +92,7 @@ const writePreviewSchema = z.object({
 		type: z.string(),
 		id: z.string().nullable()
 	}),
+	targetName: z.string().nullable().optional().describe("대상 이름(상품명·쿠폰명·흐름 이름·구매자 이름 등). 읽을 수 없으면 null"),
 	changes: z.array(z.object({
 		field: z.string().describe("바뀌는 필드"),
 		before: z.unknown().describe("현재 값. 새로 만드는 요청이거나 읽을 수 없으면 null"),
@@ -119,6 +120,7 @@ const approvalRequestSchema = z.object({
 	approvalId: z.string().describe("승인 요청 ID"),
 	status: approvalStatusSchema,
 	operationId: z.string().describe("보류된 오퍼레이션 ID"),
+	operationName: z.string().nullable().optional().describe("작업 이름(예: 흐름 게시, 구매자 적립금 지급·차감). API 문서의 요약과 같다. 모르면 null"),
 	method: z.string().describe("HTTP 메서드"),
 	path: z.string().describe("요청 경로와 쿼리"),
 	body: z.unknown().describe("요청 본문. 승인하면 이 본문 그대로 실행한다. 없으면 null"),
@@ -930,7 +932,8 @@ const approveClaimResultSchema = z.object({
 	couponChargeAmount: z.number().int().optional().default(0).describe("환불액에서 뺀 쿠폰 조건 미달 차감. 남은 주문상품이 쿠폰 조건을 잃었을 때만 0보다 크다. 서버는 항상 싣는다"),
 	couponChargeRefundAmount: z.number().int().optional().default(0).describe("환불액에 더한, 앞선 환불에서 뺀 쿠폰 차감을 되돌린 몫. 서버는 항상 싣는다"),
 	pointRefundAmount: z.number().int().optional().default(0).describe("돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. 차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다"),
-	refundedAt: z.string()
+	refundedAt: z.string(),
+	refundHeld: z.boolean().optional().default(false).describe("결제 환불을 대기로 남겼다(`holdRefund`, #115). 결제 상세에서 환불 처리한다")
 });
 //#endregion
 //#region src/schemas/fulfillment.ts
@@ -1441,7 +1444,7 @@ const POINT_ADJUSTMENT_MAX = 1e7;
 const pointAdjustmentRequestSchema = z.object({
 	amount: z.number().int().min(-1e7).max(POINT_ADJUSTMENT_MAX).refine((value) => value !== 0, "0원은 조정할 수 없습니다").describe("지급은 양수, 차감은 음수(원)"),
 	reason: z.string().trim().min(1).max(200).describe("사유(필수). 구매자에게는 보이지 않는다"),
-	expiresAt: z.iso.datetime({ offset: true }).optional().describe("지급분의 소멸 시각. 생략하면 정책 유효 기간으로 정한다. 차감에는 주지 않는다")
+	expiresAt: z.iso.datetime({ offset: true }).optional().describe("지급분의 소멸 시각. 생략하면 정책 유효 기간(`expiryDays`)으로 정한다. **정책 유효 기간이 없으면 지급에 필수다**(없으면 400 `POINT_EXPIRY_REQUIRED`). 차감에는 주지 않는다")
 }).refine((value) => !(value.amount < 0 && value.expiresAt), {
 	message: "차감에는 소멸 시각을 줄 수 없습니다",
 	path: ["expiresAt"]
@@ -2735,15 +2738,15 @@ const flowPresetSummarySchema = z.object({
 	description: z.string(),
 	availability: z.enum(["AVAILABLE", "BLOCKED"]).describe("BLOCKED면 의존 이슈(dependsOn)가 끝나야 설치할 수 있다"),
 	dependsOn: z.array(z.string()),
-	requires: flowDocumentSchema.describe("프리셋이 쓰는 Core 기능(진행 단위·이행 방식·주문 입력 등)"),
-	variables: z.array(flowDocumentSchema).describe("셀러가 값만 입력하는 변수 정의")
+	requires: flowDocumentSchema.describe("흐름 설정(진행 단위·이행 방식)"),
+	variables: z.array(flowDocumentSchema).describe("늘 빈 목록이다 — 프리셋은 빈 흐름을 편집한 그래프이고 값은 노드 설정 안에 있다(#115)")
 });
 const commerceFlowSummarySchema = z.object({
 	flowId: z.string(),
 	key: z.string().describe("상점 안 유일한 키"),
 	name: z.string(),
-	progression: z.enum(["ITEM", "ORDER_GROUP"]),
-	fulfillmentMethods: z.array(z.string()),
+	progression: z.enum(["ITEM", "ORDER_GROUP"]).describe("진행 단위 — 지금 게시 버전의 값(초안 `definition.requires.progression`을 게시 때 고정한다). 주문상품은 주문 시점 버전의 값을 따른다"),
+	fulfillmentMethods: z.array(z.string()).describe("이행 방식 — 지금 게시 버전의 `definition.requires.fulfillmentMethods`"),
 	presetKey: z.string().nullable().describe("설치한 프리셋(설치 뒤 연결되지 않는다)"),
 	presetVersion: z.number().int().nullable(),
 	activeVersion: z.number().int().nullable().describe("게시된 버전. 새 주문이 따른다"),
@@ -2795,12 +2798,12 @@ const createCommerceFlowRequestSchema = z.object({
 	key: z.string().regex(/^[a-z][a-z0-9-]{1,48}$/).describe("상점 안 유일한 키(소문자·숫자·하이픈)"),
 	name: z.string().min(1).max(60).optional(),
 	presetKey: z.string().optional().describe("설치할 프리셋. 없으면 빈 플로우"),
-	variables: z.record(z.string(), z.unknown()).optional().describe("프리셋 변수 값")
+	variables: z.record(z.string(), z.unknown()).optional().describe("쓰지 않는다(무시). 값은 그래프의 노드 설정 안에 있다(#115)")
 });
 const saveFlowDraftRequestSchema = z.object({
 	graph: flowDocumentSchema,
-	definition: flowDocumentSchema.optional(),
-	variables: z.record(z.string(), z.unknown()).optional()
+	definition: flowDocumentSchema.optional().describe("흐름 설정 `requires`(progression·fulfillmentMethods)와 행동 입력 칸 `actionInputs`"),
+	variables: z.record(z.string(), z.unknown()).optional().describe("쓰지 않는다(무시). 값은 그래프의 노드 설정 안에 있다(#115)")
 });
 const flowIssueSchema = z.object({
 	code: z.string(),
@@ -2923,7 +2926,21 @@ const flowNodeTypesSchema = z.object({
 		version: z.number().int(),
 		effect: z.string().describe("local 같은 트랜잭션 · afterCommit 커밋 뒤 · external 트랜잭션 밖"),
 		configSchema: z.record(z.string(), z.unknown())
-	}))
+	})),
+	platformActions: z.array(z.object({
+		key: z.string(),
+		side: z.enum(["buyer", "seller"]),
+		label: z.string(),
+		mode: z.enum([
+			"INSTANT",
+			"REQUEST",
+			"VIEW"
+		]),
+		subflow: z.string().optional().describe("켜면 붙는 클레임 하위 흐름"),
+		window: z.boolean().describe("기간(within, 단계 진입 뒤 N일)을 둘 수 있다"),
+		fee: z.boolean().describe("수수료(deduct)를 둘 수 있다"),
+		listed: z.boolean().describe("권한 표에 행으로 보인다")
+	})).optional().default([]).describe("노드 권한 표에 켤 수 있는 플랫폼 행동(#115) — 편집기는 이 목록으로 행을 그린다")
 });
 //#endregion
 //#region src/schemas/promotion.ts
@@ -4573,6 +4590,7 @@ const paymentRecordSchema = z.object({
 	status: paymentRecordStatusSchema,
 	amount: z.number().int().describe("결제 금액"),
 	refundedAmount: z.number().int().describe("환불 완료 금액 합계. 실패한 환불은 빼고 센다"),
+	heldRefundAmount: z.number().int().optional().default(0).describe("환불 대기 금액 합계(#115) — 주문만 취소하고 아직 환불하지 않은 몫. 결제 상세에서 환불 처리한다"),
 	provider: pgProviderSchema.nullable().describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
 	method: pgPaymentMethodSchema.nullable().describe("실제 결제수단. 모르면 요청 수단"),
 	easyPayProvider: easyPayProviderResponseSchema.nullable().optional().default(null).describe("간편결제사. `method`가 `EASY_PAY`일 때만 값이 있고, PG가 알려 주지 않았으면 요청한 간편결제사다. 그 밖의 결제수단과 간편결제 이전 결제는 null. 서버는 항상 싣는다. 현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다"),
@@ -4613,7 +4631,7 @@ const paymentRefundRecordSchema = z.object({
 	pointRefundAmount: z.number().int().optional().default(0).describe("같은 환불에서 돌려준 적립금 (#93). 적립금을 쓰지 않은 결제는 0"),
 	reason: z.string().describe("환불 사유 코드"),
 	kind: z.string().describe("환불 원인 — SELLER_CANCEL·CLAIM·COMPENSATION·DUPLICATE. 새 값이 추가될 수 있다"),
-	status: z.string().describe("SUCCEEDED·FAILED"),
+	status: z.string().describe("SUCCEEDED 환불됨 · FAILED 실패 · HELD 환불 대기(주문만 취소, #115) · PROCESSING 처리 중. 합계(`refundedAmount`)는 SUCCEEDED만 센다"),
 	failMessage: z.string().nullable(),
 	requestedAt: z.string(),
 	completedAt: z.string().nullable()
@@ -4634,6 +4652,7 @@ const paymentListQuerySchema = z.object({
 	method: z.string().optional().describe("실제 결제수단 필터"),
 	keyword: z.string().optional().describe("결제 id·주문 id·PG 거래 id·시도 id·PG 주문번호(일치), 구매자명(포함)"),
 	includeTest: z.string().optional().describe("테스트 결제 포함 여부 (`true`·`false`. 기본 false — 실결제만)"),
+	refundHeld: z.string().optional().describe("`true`면 환불 대기가 있는 결제만(#115)"),
 	page: z.string().optional().describe("페이지 번호 (1부터)"),
 	size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)")
 });
@@ -4867,7 +4886,8 @@ const cancelBySellerRequestSchema = z.object({
 		"ETC"
 	]),
 	detail: z.string().max(500).optional(),
-	quantity: z.number().int().min(1).optional().describe("취소할 수량. 생략하면 남은 수량 전체다. 남은 수량보다 크면 400 `INVALID_QUANTITY`. 일부만 취소하면 주문상품은 상태를 유지한 채 `canceledQuantity`가 늘고, 전 수량이 소진되면 `CANCELED`가 된다")
+	quantity: z.number().int().min(1).optional().describe("취소할 수량. 생략하면 남은 수량 전체다. 남은 수량보다 크면 400 `INVALID_QUANTITY`. 일부만 취소하면 주문상품은 상태를 유지한 채 `canceledQuantity`가 늘고, 전 수량이 소진되면 `CANCELED`가 된다"),
+	holdRefund: z.boolean().optional().describe("true면 주문만 취소하고 결제 환불은 대기로 남긴다(#115). 정산·재고·적립금 반환은 그대로 하고, PG 환불은 결제 상세의 `POST /v1/payments/refunds/{refundId}/process`로 따로 한다. 생략하면 취소와 함께 환불한다")
 });
 /**
 * 제공 처리 요청 (이슈 #48) — `POST /v1/order-items/{orderItemId}/fulfill`. 배송 없는 주문상품(`MANUAL`)을
@@ -4890,7 +4910,8 @@ const cancelBySellerResultSchema = z.object({
 	couponChargeAmount: z.number().int().optional().default(0).describe("쿠폰 조건 미달 차감. 판매자 취소는 차감하지 않으므로 늘 0이다. 서버는 항상 싣는다"),
 	couponChargeRefundAmount: z.number().int().optional().default(0).describe("환불액에 더한, 앞선 환불에서 뺀 쿠폰 차감을 되돌린 몫. 서버는 항상 싣는다"),
 	pointRefundAmount: z.number().int().optional().default(0).describe("돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. 차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다"),
-	refundedAt: z.string()
+	refundedAt: z.string().describe("환불을 요청한 시각. `refundHeld`면 취소 시각이고 환불은 아직 하지 않았다"),
+	refundHeld: z.boolean().optional().default(false).describe("결제 환불을 대기로 남겼다(`holdRefund`). 결제 상세에서 환불 처리한다")
 });
 /** `PUT /v1/order-items/{orderItemId}/memo` 응답 — 빈 문자열로 저장하면 메모가 지워져 `null`이다 */
 const orderItemMemoResultSchema = z.object({
@@ -7139,8 +7160,12 @@ function createStoreClient(options) {
 				status: Array.isArray(params?.status) ? params.status.join(",") : params?.status
 			} }),
 			get: (claimId) => storeHttp.request("GET", path`/claims/${claimId}`, claimDetailSchema),
-			approve: (claimId, deductAmount, idempotencyKey) => storeHttp.request("POST", path`/claims/${claimId}/approve`, approveClaimResultSchema, {
-				body: deductAmount !== void 0 ? { deductAmount } : {},
+			/** `holdRefund`(#115)면 승인만 하고 결제 환불은 대기로 남긴다 — `payments.processRefund`로 따로 환불한다 */
+			approve: (claimId, deductAmount, idempotencyKey, options = {}) => storeHttp.request("POST", path`/claims/${claimId}/approve`, approveClaimResultSchema, {
+				body: {
+					...deductAmount !== void 0 ? { deductAmount } : {},
+					...options.holdRefund ? { holdRefund: true } : {}
+				},
 				headers: idempotency(idempotencyKey)
 			}),
 			reject: (claimId, body) => storeHttp.requestVoid("POST", path`/claims/${claimId}/reject`, { body: rejectClaimRequestSchema.parse(body) }),
@@ -7285,7 +7310,9 @@ get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, {
 			*/
 			list: (params = {}) => storeHttp.request("GET", "/payments", paymentRecordPageSchema, { query: params }),
 			/** `GET /v1/payments/{paymentId}` — 시도·환불 이력 포함. 404 `PAYMENT_NOT_FOUND` */
-			get: (paymentId) => storeHttp.request("GET", path`/payments/${paymentId}`, paymentRecordDetailSchema)
+			get: (paymentId) => storeHttp.request("GET", path`/payments/${paymentId}`, paymentRecordDetailSchema),
+			/** `POST /v1/payments/refunds/{refundId}/process` — 대기 환불(`HELD`)을 PG로 환불한다(#115). 409 `REFUND_NOT_HELD` */
+			processRefund: (refundId) => storeHttp.request("POST", path`/payments/refunds/${refundId}/process`, paymentRefundRecordSchema)
 		},
 		/**
 		* 결제(PG) 설정 — **상점 플랫폼 OWNER 전용**. ADMIN·STAFF·PAT·M2M·3rd-party 앱 토큰은 스코프가 있어도

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.30.3",
+  "version": "0.30.5",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -193,6 +193,7 @@ import {
   paymentProviderVerificationSchema,
   paymentRecordDetailSchema,
   paymentRecordPageSchema,
+  paymentRefundRecordSchema,
   paymentSettingsSchema,
   pgEnvironmentSchema,
   pgProviderSchema,
@@ -972,9 +973,18 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       get: (claimId: string) =>
         storeHttp.request("GET", path`/claims/${claimId}`, claimDetailSchema),
-      approve: (claimId: string, deductAmount?: number, idempotencyKey?: string) =>
+      /** `holdRefund`(#115)면 승인만 하고 결제 환불은 대기로 남긴다 — `payments.processRefund`로 따로 환불한다 */
+      approve: (
+        claimId: string,
+        deductAmount?: number,
+        idempotencyKey?: string,
+        options: { holdRefund?: boolean } = {},
+      ) =>
         storeHttp.request("POST", path`/claims/${claimId}/approve`, approveClaimResultSchema, {
-          body: deductAmount !== undefined ? { deductAmount } : {},
+          body: {
+            ...(deductAmount !== undefined ? { deductAmount } : {}),
+            ...(options.holdRefund ? { holdRefund: true } : {}),
+          },
           headers: idempotency(idempotencyKey),
         }),
       reject: (claimId: string, body: RejectClaimRequest) =>
@@ -1289,6 +1299,13 @@ export function createStoreClient(options: StoreClientOptions) {
       /** `GET /v1/payments/{paymentId}` — 시도·환불 이력 포함. 404 `PAYMENT_NOT_FOUND` */
       get: (paymentId: string) =>
         storeHttp.request("GET", path`/payments/${paymentId}`, paymentRecordDetailSchema),
+      /** `POST /v1/payments/refunds/{refundId}/process` — 대기 환불(`HELD`)을 PG로 환불한다(#115). 409 `REFUND_NOT_HELD` */
+      processRefund: (refundId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/payments/refunds/${refundId}/process`,
+          paymentRefundRecordSchema,
+        ),
     },
 
     /**

package/src/schemas/audit.ts

@@ -155,6 +155,11 @@ export const writePreviewSchema = z.object({
   method: z.string(),
   path: z.string(),
   target: z.object({ type: z.string(), id: z.string().nullable() }),
+  targetName: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("대상 이름(상품명·쿠폰명·흐름 이름·구매자 이름 등). 읽을 수 없으면 null"),
   changes: z
     .array(
       z.object({
@@ -195,6 +200,13 @@ export const approvalRequestSchema = z.object({
   approvalId: z.string().describe("승인 요청 ID"),
   status: approvalStatusSchema,
   operationId: z.string().describe("보류된 오퍼레이션 ID"),
+  operationName: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "작업 이름(예: 흐름 게시, 구매자 적립금 지급·차감). API 문서의 요약과 같다. 모르면 null",
+    ),
   method: z.string().describe("HTTP 메서드"),
   path: z.string().describe("요청 경로와 쿼리"),
   body: z.unknown().describe("요청 본문. 승인하면 이 본문 그대로 실행한다. 없으면 null"),

package/src/schemas/claim.ts

@@ -224,6 +224,11 @@ export const approveClaimResultSchema = z.object({
         "차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다",
     ),
   refundedAt: z.string(),
+  refundHeld: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("결제 환불을 대기로 남겼다(`holdRefund`, #115). 결제 상세에서 환불 처리한다"),
 });
 
 export type ApproveClaimResult = z.infer<typeof approveClaimResultSchema>;

package/src/schemas/commerce-flow.ts

@@ -203,10 +203,12 @@ export const flowPresetSummarySchema = z.object({
     .enum(["AVAILABLE", "BLOCKED"])
     .describe("BLOCKED면 의존 이슈(dependsOn)가 끝나야 설치할 수 있다"),
   dependsOn: z.array(z.string()),
-  requires: flowDocumentSchema.describe(
-    "프리셋이 쓰는 Core 기능(진행 단위·이행 방식·주문 입력 등)",
-  ),
-  variables: z.array(flowDocumentSchema).describe("셀러가 값만 입력하는 변수 정의"),
+  requires: flowDocumentSchema.describe("흐름 설정(진행 단위·이행 방식)"),
+  variables: z
+    .array(flowDocumentSchema)
+    .describe(
+      "늘 빈 목록이다 — 프리셋은 빈 흐름을 편집한 그래프이고 값은 노드 설정 안에 있다(#115)",
+    ),
 });
 export type FlowPresetSummary = z.infer<typeof flowPresetSummarySchema>;
 
@@ -214,8 +216,14 @@ export const commerceFlowSummarySchema = z.object({
   flowId: z.string(),
   key: z.string().describe("상점 안 유일한 키"),
   name: z.string(),
-  progression: z.enum(["ITEM", "ORDER_GROUP"]),
-  fulfillmentMethods: z.array(z.string()),
+  progression: z
+    .enum(["ITEM", "ORDER_GROUP"])
+    .describe(
+      "진행 단위 — 지금 게시 버전의 값(초안 `definition.requires.progression`을 게시 때 고정한다). 주문상품은 주문 시점 버전의 값을 따른다",
+    ),
+  fulfillmentMethods: z
+    .array(z.string())
+    .describe("이행 방식 — 지금 게시 버전의 `definition.requires.fulfillmentMethods`"),
   presetKey: z.string().nullable().describe("설치한 프리셋(설치 뒤 연결되지 않는다)"),
   presetVersion: z.number().int().nullable(),
   activeVersion: z.number().int().nullable().describe("게시된 버전. 새 주문이 따른다"),
@@ -290,14 +298,22 @@ export const createCommerceFlowRequestSchema = z.object({
     .describe("상점 안 유일한 키(소문자·숫자·하이픈)"),
   name: z.string().min(1).max(60).optional(),
   presetKey: z.string().optional().describe("설치할 프리셋. 없으면 빈 플로우"),
-  variables: z.record(z.string(), z.unknown()).optional().describe("프리셋 변수 값"),
+  variables: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe("쓰지 않는다(무시). 값은 그래프의 노드 설정 안에 있다(#115)"),
 });
 export type CreateCommerceFlowRequest = z.infer<typeof createCommerceFlowRequestSchema>;
 
 export const saveFlowDraftRequestSchema = z.object({
   graph: flowDocumentSchema,
-  definition: flowDocumentSchema.optional(),
-  variables: z.record(z.string(), z.unknown()).optional(),
+  definition: flowDocumentSchema
+    .optional()
+    .describe("흐름 설정 `requires`(progression·fulfillmentMethods)와 행동 입력 칸 `actionInputs`"),
+  variables: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe("쓰지 않는다(무시). 값은 그래프의 노드 설정 안에 있다(#115)"),
 });
 export type SaveFlowDraftRequest = z.infer<typeof saveFlowDraftRequestSchema>;
 
@@ -497,5 +513,21 @@ export const flowNodeTypesSchema = z.object({
       configSchema: z.record(z.string(), z.unknown()),
     }),
   ),
+  platformActions: z
+    .array(
+      z.object({
+        key: z.string(),
+        side: z.enum(["buyer", "seller"]),
+        label: z.string(),
+        mode: z.enum(["INSTANT", "REQUEST", "VIEW"]),
+        subflow: z.string().optional().describe("켜면 붙는 클레임 하위 흐름"),
+        window: z.boolean().describe("기간(within, 단계 진입 뒤 N일)을 둘 수 있다"),
+        fee: z.boolean().describe("수수료(deduct)를 둘 수 있다"),
+        listed: z.boolean().describe("권한 표에 행으로 보인다"),
+      }),
+    )
+    .optional()
+    .default([])
+    .describe("노드 권한 표에 켤 수 있는 플랫폼 행동(#115) — 편집기는 이 목록으로 행을 그린다"),
 });
 export type FlowNodeTypes = z.infer<typeof flowNodeTypesSchema>;

package/src/schemas/order.ts

@@ -513,6 +513,13 @@ export const cancelBySellerRequestSchema = z.object({
       "취소할 수량. 생략하면 남은 수량 전체다. 남은 수량보다 크면 400 `INVALID_QUANTITY`. " +
         "일부만 취소하면 주문상품은 상태를 유지한 채 `canceledQuantity`가 늘고, 전 수량이 소진되면 `CANCELED`가 된다",
     ),
+  holdRefund: z
+    .boolean()
+    .optional()
+    .describe(
+      "true면 주문만 취소하고 결제 환불은 대기로 남긴다(#115). 정산·재고·적립금 반환은 그대로 하고, PG 환불은 결제 상세의 " +
+        "`POST /v1/payments/refunds/{refundId}/process`로 따로 한다. 생략하면 취소와 함께 환불한다",
+    ),
 });
 
 export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;
@@ -583,7 +590,14 @@ export const cancelBySellerResultSchema = z.object({
       "돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. " +
         "차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다",
     ),
-  refundedAt: z.string(),
+  refundedAt: z
+    .string()
+    .describe("환불을 요청한 시각. `refundHeld`면 취소 시각이고 환불은 아직 하지 않았다"),
+  refundHeld: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("결제 환불을 대기로 남겼다(`holdRefund`). 결제 상세에서 환불 처리한다"),
 });
 
 export type CancelBySellerResult = z.infer<typeof cancelBySellerResultSchema>;

package/src/schemas/payment.ts

@@ -610,6 +610,14 @@ export const paymentRecordSchema = z.object({
   status: paymentRecordStatusSchema,
   amount: z.number().int().describe("결제 금액"),
   refundedAmount: z.number().int().describe("환불 완료 금액 합계. 실패한 환불은 빼고 센다"),
+  heldRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "환불 대기 금액 합계(#115) — 주문만 취소하고 아직 환불하지 않은 몫. 결제 상세에서 환불 처리한다",
+    ),
   provider: pgProviderSchema.nullable().describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
   method: pgPaymentMethodSchema.nullable().describe("실제 결제수단. 모르면 요청 수단"),
   easyPayProvider: easyPayProviderResponseSchema
@@ -707,7 +715,11 @@ export const paymentRefundRecordSchema = z.object({
   kind: z
     .string()
     .describe("환불 원인 — SELLER_CANCEL·CLAIM·COMPENSATION·DUPLICATE. 새 값이 추가될 수 있다"),
-  status: z.string().describe("SUCCEEDED·FAILED"),
+  status: z
+    .string()
+    .describe(
+      "SUCCEEDED 환불됨 · FAILED 실패 · HELD 환불 대기(주문만 취소, #115) · PROCESSING 처리 중. 합계(`refundedAmount`)는 SUCCEEDED만 센다",
+    ),
   failMessage: z.string().nullable(),
   requestedAt: z.string(),
   completedAt: z.string().nullable(),
@@ -745,6 +757,7 @@ export const paymentListQuerySchema = z.object({
     .string()
     .optional()
     .describe("테스트 결제 포함 여부 (`true`·`false`. 기본 false — 실결제만)"),
+  refundHeld: z.string().optional().describe("`true`면 환불 대기가 있는 결제만(#115)"),
   page: z.string().optional().describe("페이지 번호 (1부터)"),
   size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)"),
 });
@@ -757,4 +770,6 @@ export interface PaymentListParams extends PageParams {
   method?: PgPaymentMethod;
   keyword?: string;
   includeTest?: boolean;
+  /** 환불 대기가 있는 결제만(#115) */
+  refundHeld?: boolean;
 }

package/src/schemas/points.ts

@@ -331,7 +331,9 @@ export const pointAdjustmentRequestSchema = z
     expiresAt: z.iso
       .datetime({ offset: true })
       .optional()
-      .describe("지급분의 소멸 시각. 생략하면 정책 유효 기간으로 정한다. 차감에는 주지 않는다"),
+      .describe(
+        "지급분의 소멸 시각. 생략하면 정책 유효 기간(`expiryDays`)으로 정한다. **정책 유효 기간이 없으면 지급에 필수다**(없으면 400 `POINT_EXPIRY_REQUIRED`). 차감에는 주지 않는다",
+      ),
   })
   .refine((value) => !(value.amount < 0 && value.expiresAt), {
     message: "차감에는 소멸 시각을 줄 수 없습니다",