@sayren/store-sdk 0.32.0 → 0.33.0

package/src/schemas/payment.ts

@@ -10,12 +10,21 @@ import { type PageParams, pageSchema } from "./common";
  */
 
 export const pgProviderSchema = z
-  .enum(["tosspayments", "portone", "kakaopay", "naverpay"])
+  .enum(["tosspayments", "portone", "kakaopay", "naverpay", "paypal"])
   .describe(
-    "PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2), `kakaopay`=카카오페이(직접 연동), `naverpay`=네이버페이 결제형(직접 연동)",
+    "PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2), `kakaopay`=카카오페이(직접 연동), `naverpay`=네이버페이 결제형(직접 연동), `paypal`=PayPal(직접 연동, 외화)",
   );
 export type PgProvider = z.infer<typeof pgProviderSchema>;
 
+/**
+ * 응답에 실리는 PG — 서버가 PG를 추가해도 응답 파싱이 깨지지 않게 문자열로 받는다(`easyPayProviderResponseSchema`와 같은 방식, 이슈 #131 CD2).
+ * 요청(우선순위·리포트 필터·경로)은 값을 골라 보내는 자리라 `pgProviderSchema` enum 그대로다. 현재 값은 `pgProviderSchema`의 값이고
+ * 화면은 모르는 값을 원문 그대로 보여 준다
+ */
+export const pgProviderResponseSchema = z
+  .string()
+  .describe("PG 식별자(`pgProviderSchema`의 값). 모르는 값이 와도 응답 파싱이 깨지지 않는다");
+
 /**
  * 간편결제 전용 PG — 결제수단이 간편결제 하나이고 간편결제사가 PG 자신이다(`kakaopay` → `KAKAOPAY`).
  * 이 PG는 `easyPayProviders` 설정 없이 결제 옵션이 하나(`EASY_PAY` + 그 간편결제사) 나온다
@@ -23,6 +32,7 @@ export type PgProvider = z.infer<typeof pgProviderSchema>;
 export const DEDICATED_EASY_PAY_PROVIDER = {
   kakaopay: "KAKAOPAY",
   naverpay: "NAVERPAY",
+  paypal: "PAYPAL",
 } as const satisfies Partial<Record<PgProvider, string>>;
 
 export const pgPaymentMethodSchema = z
@@ -34,7 +44,7 @@ export type PgPaymentMethod = z.infer<typeof pgPaymentMethodSchema>;
  * 간편결제사 — 결제 옵션(스토어프론트 `paymentOptions`)과 PG 설정의 `easyPayProviders`에 쓴다.
  * `@sayren/storefront-sdk`의 `easyPayProviderSchema`와 같은 값이다(api 계약 테스트가 고정한다)
  */
-export const easyPayProviderSchema = z.enum(["NAVERPAY", "KAKAOPAY", "TOSSPAY", "PAYCO"]);
+export const easyPayProviderSchema = z.enum(["NAVERPAY", "KAKAOPAY", "TOSSPAY", "PAYCO", "PAYPAL"]);
 export type EasyPayProvider = z.infer<typeof easyPayProviderSchema>;
 
 /**
@@ -188,6 +198,55 @@ export const naverPayCredentialsInputSchema = z.object({
 });
 export type NaverPayCredentialsInput = z.infer<typeof naverPayCredentialsInputSchema>;
 
+/**
+ * PayPal이 받는 통화 중 sayren이 여는 것(이슈 #131 설계 §3b) — PayPal 통화 코드(https://developer.paypal.com/api/rest/reference/currency-codes/) ∩ 통화표
+ * − 원화(PayPal이 받지 않는다) − CNY·MYR(현지 계정 전용) − TWD(부분 환불 소수 문제, 설계 Q4)
+ */
+export const PAYPAL_CURRENCIES = [
+  "USD",
+  "EUR",
+  "JPY",
+  "GBP",
+  "HKD",
+  "SGD",
+  "AUD",
+  "CAD",
+  "THB",
+  "PHP",
+  "NZD",
+  "CHF",
+] as const;
+
+export const payPalCredentialsInputSchema = z.object({
+  clientId: z
+    .string()
+    .trim()
+    .min(10)
+    .max(200)
+    .describe("PayPal REST 앱의 Client ID(테스트 세트는 샌드박스 앱). 공개 값"),
+  currencies: z
+    .array(z.enum(PAYPAL_CURRENCIES))
+    .min(1)
+    .max(PAYPAL_CURRENCIES.length)
+    .describe(
+      "받는 통화 — PayPal 계정에 열어 둔 통화를 고른다. 결제 세션 통화가 여기 있는 주문서에만 PayPal 옵션이 나온다(원화는 받지 않는다)",
+    ),
+  webhookId: z
+    .string()
+    .trim()
+    .min(1)
+    .max(100)
+    .nullable()
+    .optional()
+    .describe(
+      "PayPal 앱에 등록한 웹훅의 ID(선택). 주면 서버 통지의 서명을 검증해 결제 확인을 앞당긴다. 생략·null이면 통지를 받지 않고 주기 확인만 한다",
+    ),
+  clientSecret: secretInput()
+    .optional()
+    .describe("Secret. 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
+});
+export type PayPalCredentialsInput = z.infer<typeof payPalCredentialsInputSchema>;
+
 const upsertEnvironment = () =>
   pgEnvironmentSchema.describe(
     "저장할 자격 증명 세트. PG마다 `TEST`(샌드박스)·`LIVE`(실결제) 세트를 따로 둔다. " +
@@ -220,6 +279,12 @@ export const upsertNaverPayProviderRequestSchema = z.object({
 });
 export type UpsertNaverPayProviderRequest = z.infer<typeof upsertNaverPayProviderRequestSchema>;
 
+export const upsertPayPalProviderRequestSchema = z.object({
+  environment: upsertEnvironment(),
+  credentials: payPalCredentialsInputSchema,
+});
+export type UpsertPayPalProviderRequest = z.infer<typeof upsertPayPalProviderRequestSchema>;
+
 export const updatePaymentProviderRequestSchema = z
   .object({
     enabled: z
@@ -304,6 +369,11 @@ const publicConfigSchema = z.union([
   z.object({ storeId: z.string(), channels: z.array(portOneChannelSchema) }),
   z.object({ cid: z.string() }),
   z.object({ clientId: z.string(), chainId: z.string() }),
+  z.object({
+    clientId: z.string(),
+    currencies: z.array(z.string()),
+    webhookId: z.string().nullable(),
+  }),
 ]);
 
 const verificationSchema = z.object({
@@ -315,7 +385,7 @@ const verificationSchema = z.object({
 export const paymentCredentialSetSchema = z.object({
   environment: pgEnvironmentSchema,
   publicConfig: publicConfigSchema.describe(
-    "공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`, 카카오페이는 `{cid}`, 네이버페이는 `{clientId, chainId}`",
+    "공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`, 카카오페이는 `{cid}`, 네이버페이는 `{clientId, chainId}`, PayPal은 `{clientId, currencies, webhookId}`",
   ),
   secrets: z
     .array(maskedSecretSchema)
@@ -371,7 +441,7 @@ export const liveGateErrorDetailsSchema = z.object({
 export type LiveGateErrorDetails = z.infer<typeof liveGateErrorDetailsSchema>;
 
 export const paymentProviderSchema = z.object({
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   displayName: z.string().describe("표시 이름 (토스페이먼츠·포트원)"),
   connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
   enabled: z.boolean().describe("결제에 사용 중인가"),
@@ -499,7 +569,7 @@ export const paymentSettingsSchema = z.object({
   providers: z
     .array(paymentProviderSchema)
     .describe(
-      "연결된 PG(우선순위순)와 연결되지 않은 토스페이먼츠·포트원. 카카오페이·네이버페이는 연결했을 때만 여기에 온다" +
+      "연결된 PG(우선순위순)와 연결되지 않은 토스페이먼츠·포트원. 그 밖의 PG(카카오페이·네이버페이 등)는 연결했을 때만 여기에 온다" +
         "(이 PG를 모르는 이전 SDK가 응답을 읽을 수 있게). 연결할 수 있는 PG 전체는 `connectableProviders`다",
     ),
   connectableProviders: z
@@ -539,7 +609,7 @@ export const paymentSettingsSchema = z.object({
 export type PaymentSettings = z.infer<typeof paymentSettingsSchema>;
 
 export const paymentProviderVerificationSchema = z.object({
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   environment: pgEnvironmentSchema.describe("연결 테스트한 자격 증명 세트"),
   result: pgVerificationResultSchema,
   message: z.string().nullable().describe("실패 사유 또는 참고 메시지"),
@@ -592,7 +662,7 @@ 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가 포함될 때만 값"),
+  provider: pgProviderResponseSchema.nullable().describe("PG. groupBy에 PROVIDER가 포함될 때만 값"),
   method: pgPaymentMethodSchema
     .nullable()
     .describe(
@@ -602,17 +672,36 @@ export const salesReportRowSchema = salesTotalsSchema.extend({
 });
 export type SalesReportRow = z.infer<typeof salesReportRowSchema>;
 
+/** 통화별 매출(이슈 #130) — 환산하지 않는다. 금액은 그 통화의 최소 단위다 */
+export const salesReportCurrencySchema = z.object({
+  currency: z.string().describe("결제 통화(ISO 4217)"),
+  summary: salesTotalsSchema.describe("이 통화의 기간 전체 합계"),
+  rows: z.array(salesReportRowSchema).describe("이 통화의 집계 행(`groupBy` 기준)"),
+});
+export type SalesReportCurrency = z.infer<typeof salesReportCurrencySchema>;
+
 export const salesReportSchema = z.object({
   from: z.string(),
   to: z.string(),
   timezone: z.literal("Asia/Seoul"),
-  currency: z.literal("KRW"),
+  currency: z
+    .literal("KRW")
+    .describe(
+      "`summary`·`rows`의 통화. 기본 통화(원화) 결제만 집계한다. 외화 결제는 `byCurrency`에 있다",
+    ),
   groupBy: salesReportGroupBySchema,
-  provider: pgProviderSchema.nullable().describe("적용된 PG 필터"),
+  provider: pgProviderResponseSchema.nullable().describe("적용된 PG 필터"),
   method: pgPaymentMethodSchema.nullable().describe("적용된 결제수단 필터"),
   includeTest: z.boolean().describe("테스트 결제(샌드박스 결제)를 집계에 포함했는가"),
   summary: salesTotalsSchema.describe("기간 전체 합계"),
   rows: z.array(salesReportRowSchema).describe("집계 행. 활동이 없는 날짜·PG는 생략된다"),
+  byCurrency: z
+    .array(salesReportCurrencySchema)
+    .optional()
+    .default([])
+    .describe(
+      "통화별 매출(이슈 #130) — 활동이 있는 통화마다 한 항목이고 기본 통화(KRW)도 포함한다. 통화 사이는 환산하지 않는다. 옛 서버 응답은 빈 목록",
+    ),
 });
 export type SalesReport = z.infer<typeof salesReportSchema>;
 
@@ -677,7 +766,9 @@ export const cashReceiptSchema = z.object({
     .int()
     .describe("발급해야 할 금액 = 결제 금액 − 환불 완료 금액. 승인 전에는 결제 금액"),
   issuedAmount: z.number().int().describe("PG에 현재 발급돼 있는 금액. 취소됐거나 발급 전이면 0"),
-  provider: pgProviderSchema.nullable().describe("발급 PG — 결제를 승인한 PG. 승인 전에는 null"),
+  provider: pgProviderResponseSchema
+    .nullable()
+    .describe("발급 PG — 결제를 승인한 PG. 승인 전에는 null"),
   issueNumber: z.string().nullable().describe("현금영수증 승인 번호"),
   receiptUrl: z.string().nullable().describe("현금영수증 확인 주소"),
   issuedAt: z.string().nullable().describe("최근 발급 시각 (ISO 8601)"),
@@ -708,7 +799,9 @@ export const paymentRecordSchema = z.object({
     .describe(
       "환불 대기 금액 합계(#115) — 주문만 취소하고 아직 환불하지 않은 몫. 결제 상세에서 환불 처리한다",
     ),
-  provider: pgProviderSchema.nullable().describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
+  provider: pgProviderResponseSchema
+    .nullable()
+    .describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
   method: pgPaymentMethodSchema.nullable().describe("실제 결제수단. 모르면 요청 수단"),
   easyPayProvider: easyPayProviderResponseSchema
     .nullable()
@@ -764,7 +857,7 @@ export const paymentAttemptRecordSchema = z.object({
       "PG에 보낸 주문번호(이슈 #107) — 토스페이먼츠 orderId·포트원 paymentId. 새 시도는 `{주문번호}-{시도 순번 2자리}`이고, 번호 체계 이전 시도는 시도 id(`attemptId`)와 같습니다. PG 관리자 화면에서 결제를 찾을 때 씁니다",
     ),
   sequence: z.number().int().describe("결제 건 안에서의 순번 (1부터)"),
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   status: paymentAttemptStatusSchema,
   method: pgPaymentMethodSchema.describe("주문서에서 고른 결제수단"),
   easyPayProvider: easyPayProviderResponseSchema
@@ -876,7 +969,7 @@ export type SetPlatformTestKeysRequest = z.infer<typeof setPlatformTestKeysReque
 
 /** 결제 상태 PG 한 줄 — 비밀 값·공개 키 없이 연결·사용·환경·테스트모드 키만 */
 export const paymentStatusProviderSchema = z.object({
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   displayName: z.string(),
   connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
   enabled: z.boolean().describe("결제에 사용 중인가"),

package/src/schemas/product.ts

@@ -1,5 +1,12 @@
 import { z } from "zod";
 import { type PageParams, pageQueryShape } from "./common";
+import { BASE_CURRENCY, CURRENCIES } from "./currency";
+import {
+  additionalCurrencyPricesSchema,
+  productCurrencyPricesSchema,
+  storedAdditionalCurrencyPriceSchema,
+  storedProductCurrencyPriceSchema,
+} from "./currency-prices";
 import {
   fulfillmentTypeResponseSchema,
   productFulfillmentCreateSchema,
@@ -95,6 +102,10 @@ export const productVariantSchema = z.object({
   /** 값 이름을 " / "로 이은 파생 표시명. 옵션 없으면 "" */
   name: z.string(),
   additionalPrice: z.number().int(),
+  prices: z
+    .array(storedAdditionalCurrencyPriceSchema)
+    .optional()
+    .describe("외화 추가금(이슈 #130, 관리 API만). 기본 통화 값은 `additionalPrice`다"),
   stockQuantity: z.number().int(),
   sku: z.string().nullable(),
   barcode: z.string().nullable(),
@@ -154,6 +165,10 @@ export const addonValueSchema = z.object({
   name: z.string(),
   sortOrder: z.number().int(),
   additionalPrice: z.number().int().describe("이 값을 고르면 단가에 더하는 금액(원, 0 이상)"),
+  prices: z
+    .array(storedAdditionalCurrencyPriceSchema)
+    .optional()
+    .describe("외화 추가금(이슈 #130, 관리 API만). 기본 통화 값은 `additionalPrice`다"),
   usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않고 고를 수 없다"),
 });
 
@@ -272,6 +287,7 @@ export const addonValueRequestSchema = z.object({
   valueId: z.string().optional(),
   name: optionNameSchema,
   additionalPrice: z.number().int().min(0).default(0).describe("추가금(원, 0 이상)"),
+  prices: additionalCurrencyPricesSchema.optional(),
   usable: z.boolean().default(true),
 });
 
@@ -350,6 +366,10 @@ export const discountSchema = z.object({
 export type Discount = z.infer<typeof discountSchema>;
 
 export const productSchema = productSummarySchema.extend({
+  prices: z
+    .array(storedProductCurrencyPriceSchema)
+    .optional()
+    .describe("외화 판매가(이슈 #130). 기본 통화 값은 `salePrice`·`originalPrice`다"),
   description: z.string().optional(),
   /**
    * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
@@ -516,6 +536,7 @@ export const productVariantRequestSchema = z.object({
   /** optionGroups 순서대로 각 축에서 고른 값 이름. 서버가 이름 → valueId를 해석한다 */
   valueNames: z.array(z.string()).default([]),
   additionalPrice: z.number().int().default(0),
+  prices: additionalCurrencyPricesSchema.optional(),
   /**
    * 생략 = 기존 재고 유지 (신규 variant는 0).
    * 구조 교체(PUT)가 폼 로드 시점의 재고를 되쓰지 않게 하는 옵트인 필드다 —
@@ -627,14 +648,20 @@ const productImagesRequestSchema = z.array(productImageUrlSchema).min(1).max(MAX
  * 최상위가 `strictObject`다. 모르는 필드는 400이다 — 이슈 #57 이전의 평면 필드(`deliveryFee`·`fulfillmentType`·`returnFee` 등)를
  * 보낸 요청이 조용히 무시되지 않게 한다. 옛 필드는 `fulfillment.{유형}.…`과 `refundPolicy`로 옮겼다.
  */
+/**
+ * 기본 통화 판매가 단위 — 통화표가 원천이다(이슈 #130). zod `multipleOf`로 두어 OpenAPI에 그대로 드러난다.
+ * 외화 판매가(`prices[]`)는 통화마다 `isSaleUnitPrice`로 검사한다
+ */
+const BASE_SALE_UNIT = CURRENCIES[BASE_CURRENCY].saleUnit;
+
 const productWriteShape = {
   name: z.string().min(1).max(100),
   categoryId: z.string().min(1, "카테고리를 선택해주십시오"),
   salePrice: z
     .number()
     .int()
-    .min(10)
-    .multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)")
+    .min(BASE_SALE_UNIT)
+    .multipleOf(BASE_SALE_UNIT, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)")
     .describe("판매가. 원(KRW) 단위 정수, 최소 10원, 10원 단위"),
   originalPrice: z
     .number()
@@ -650,6 +677,7 @@ const productWriteShape = {
     .describe(
       "구매 적립률 덮어쓰기(만분율, 100 = 1%, 0~3000, 이슈 #93). null이면 상점 기본 적립률, 0이면 이 상품은 적립하지 않는다. 결제 확정 시점 값이 주문상품에 남는다. 전체 수정(PUT)에서 생략하면 지금 값을 유지한다",
     ),
+  prices: productCurrencyPricesSchema.optional(),
   description: z.string().optional(),
   /**
    * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
@@ -717,7 +745,7 @@ export type ProductReplaceRequestInput = z.input<typeof productReplaceRequestSch
 export const productPatchRequestSchema = z
   .strictObject({
     name: z.string().max(100).optional(),
-    salePrice: z.number().int().multipleOf(10).optional(),
+    salePrice: z.number().int().multipleOf(BASE_SALE_UNIT).optional(),
     status: productStatusSchema.optional(),
     flowId: z
       .string()
@@ -732,6 +760,7 @@ export const productPatchRequestSchema = z
         "상품 이미지 주소 목록. 주면 통째로 바꾼다(현재 목록과 병합하지 않는다). 첫 장이 대표 이미지(썸네일)다. 생략하면 바꾸지 않는다",
       ),
     fulfillment: productFulfillmentUpdateSchema.optional().describe(fulfillmentUpdateDescription),
+    prices: productCurrencyPricesSchema.optional(),
     refundPolicy: productRefundPolicyPatchSchema
       .nullable()
       .optional()

package/src/schemas/promotion.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { CURRENCIES, KRW_MONEY_RULES, type MoneyRules } from "./currency";
 import { proratedRefundBase } from "./refund-policy";
 
 /**
@@ -172,7 +173,7 @@ export const couponRejectReasonSchema = z
 export type CouponRejectReason = z.infer<typeof couponRejectReasonSchema>;
 
 /** 쿠폰 적용 뒤 결제 금액의 하한 — 0원 결제 경로가 없어 이보다 작으면 결제를 시작하지 않는다(400 `PAYMENT_AMOUNT_TOO_LOW`) */
-export const MIN_PAYMENT_AMOUNT = 100;
+export const MIN_PAYMENT_AMOUNT = CURRENCIES.KRW.minPayment;
 
 // ─── 계산 ─────────────────────────────────────────────
 
@@ -259,6 +260,11 @@ export interface PricingInput {
    * 것처럼 보이고, 탈퇴한 회원의 반품이 회원 전용 조건에 떨어진다. 대상과 최소 금액만 본다.
    */
   ignoreEligibility?: boolean;
+  /**
+   * 주문 통화의 규칙 값(이슈 #130) — 정률 할인 내림 단위(판매가 단위)와 적립금 사용 뒤 남길 최소 결제액. 생략하면 KRW 규칙이다.
+   * 금액 입력은 모두 이 통화의 최소 단위다
+   */
+  moneyRules?: MoneyRules;
 }
 
 /** 줄 하나에 들어간 쿠폰별 할인 */
@@ -325,15 +331,22 @@ export interface PricingResult {
 }
 
 /**
- * 할인액 — 정률은 10원 단위 내림, 최대 할인액과 기준 금액을 넘지 않는다. 기준 금액이 0 이하면 0이다.
+ * 할인액 — 정률은 판매가 단위(`rules.saleUnit`, KRW 10원) 내림, 최대 할인액과 기준 금액을 넘지 않는다. 기준 금액이 0 이하면 0이다.
  *
- * 곱셈을 먼저 하고 나눈다. `base × 율 ÷ 1000`을 내려 10을 곱하면 `floor(base × 율 / 100 / 10) × 10`과 같고
- * 부동소수 오차가 끼지 않는다.
+ * 곱셈을 먼저 하고 나눈다. `base × 율 ÷ (100 × 단위)`를 내려 단위를 곱하면 `floor(base × 율 / 100 / 단위) × 단위`와 같고
+ * 부동소수 오차가 끼지 않는다(KRW는 지금의 `÷ 1000 × 10` 그대로).
  */
-export function couponDiscountOf(benefit: CouponBenefit, base: number): number {
+export function couponDiscountOf(
+  benefit: CouponBenefit,
+  base: number,
+  rules: MoneyRules = KRW_MONEY_RULES,
+): number {
   if (base <= 0) return 0;
+  const unit = rules.saleUnit;
   let raw =
-    benefit.type === "RATE" ? Math.floor((base * benefit.value) / 1000) * 10 : benefit.value;
+    benefit.type === "RATE"
+      ? Math.floor((base * benefit.value) / (100 * unit)) * unit
+      : benefit.value;
   if (benefit.type === "RATE" && benefit.maxDiscountAmount !== null) {
     raw = Math.min(raw, benefit.maxDiscountAmount);
   }
@@ -422,6 +435,7 @@ function periodRejectOf(coupon: PricingCoupon, now: Date): CouponRejectReason |
  * 사본 중 앞 장이 만료됐으면 뒤 장이 쓰인다. 결과의 `coupons`는 입력 순서 그대로다. 입력이 같으면 결과도 같다.
  */
 export function quotePricing(input: PricingInput): PricingResult {
+  const rules = input.moneyRules ?? KRW_MONEY_RULES;
   const lines = input.lines.map((line) => ({
     line,
     productDiscount: 0,
@@ -516,14 +530,14 @@ export function quotePricing(input: PricingInput): PricingResult {
         continue;
       }
       chosen = coupon.lineId;
-      best = couponDiscountOf(coupon.rule.benefit, lineOf(chosen)?.line.amount ?? 0);
+      best = couponDiscountOf(coupon.rule.benefit, lineOf(chosen)?.line.amount ?? 0, rules);
     } else {
       if (candidates.length === 0) {
         result.rejectReason = "STACK_LIMIT";
         continue;
       }
       for (const id of candidates) {
-        const discount = couponDiscountOf(coupon.rule.benefit, lineOf(id)?.line.amount ?? 0);
+        const discount = couponDiscountOf(coupon.rule.benefit, lineOf(id)?.line.amount ?? 0, rules);
         if (chosen === null || discount > best) {
           chosen = id;
           best = discount;
@@ -557,7 +571,7 @@ export function quotePricing(input: PricingInput): PricingResult {
       .filter((entry): entry is (typeof lines)[number] => entry !== undefined);
     const weights = targets.map((entry) => Math.max(0, entry.line.amount - entry.productDiscount));
     const base = weights.reduce((sum, w) => sum + w, 0);
-    const discount = couponDiscountOf(coupon.rule.benefit, base);
+    const discount = couponDiscountOf(coupon.rule.benefit, base, rules);
     if (discount <= 0) {
       result.rejectReason = "NO_DISCOUNT";
       continue;
@@ -591,7 +605,7 @@ export function quotePricing(input: PricingInput): PricingResult {
     }
     const weights = deliveryBundles.map((bundle) => Math.max(0, bundle.fee));
     const base = weights.reduce((sum, w) => sum + w, 0);
-    const discount = couponDiscountOf(coupon.rule.benefit, base);
+    const discount = couponDiscountOf(coupon.rule.benefit, base, rules);
     if (discount <= 0) {
       result.rejectReason = "NO_DISCOUNT";
       continue;
@@ -625,11 +639,15 @@ export function quotePricing(input: PricingInput): PricingResult {
   const bundleWeights = deliveryBundles.map((bundle, index) =>
     Math.max(0, bundle.fee + bundle.remoteSurcharge - (bundles[index]?.couponDiscount ?? 0)),
   );
-  const points = pointUseOf(input.points ?? null, {
-    productPaid: productWeights.reduce((sum, w) => sum + w, 0),
-    deliveryPaid: bundleWeights.reduce((sum, w) => sum + w, 0),
-    total: beforePoints,
-  });
+  const points = pointUseOf(
+    input.points ?? null,
+    {
+      productPaid: productWeights.reduce((sum, w) => sum + w, 0),
+      deliveryPaid: bundleWeights.reduce((sum, w) => sum + w, 0),
+      total: beforePoints,
+    },
+    rules,
+  );
   if (points.amount > 0) {
     const productPaid = productWeights.reduce((sum, w) => sum + w, 0);
     const toLines = Math.min(points.amount, productPaid);
@@ -670,6 +688,7 @@ export function quotePricing(input: PricingInput): PricingResult {
 export function pointUseOf(
   points: PricingPoints | null,
   amounts: { productPaid: number; deliveryPaid: number; total: number },
+  moneyRules: MoneyRules = KRW_MONEY_RULES,
 ): {
   amount: number;
   maxUsable: number;
@@ -690,8 +709,8 @@ export function pointUseOf(
     if (total > 0 && cap >= total) return { amount: total, adjusted: false };
     const amount = floorUnit(Math.min(cap, total));
     const remaining = total - amount;
-    if (remaining > 0 && remaining < MIN_PAYMENT_AMOUNT) {
-      return { amount: floorUnit(total - MIN_PAYMENT_AMOUNT), adjusted: true };
+    if (remaining > 0 && remaining < moneyRules.minPayment) {
+      return { amount: floorUnit(total - moneyRules.minPayment), adjusted: true };
     }
     return { amount, adjusted: false };
   };

package/src/schemas/refund-policy.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { BASE_CURRENCY, currencyCodeSchema } from "./currency";
 
 /**
  * 환불 정책 (이슈 #25) — 취소·반품·교환에서 **배송비를 누가 부담하는지**를 정한다.
@@ -28,8 +29,26 @@ const descriptions = {
   couponShortfallCharge:
     "쿠폰 조건 미달 차감. 일부 취소·반품으로 남은 주문상품이 쿠폰 조건(최소 주문 금액 등)을 잃으면 남은 주문상품이 받던 쿠폰 할인을 환불액에서 뺀다. " +
     "판매자 귀책(셀러 직권취소, 불량·오배송 반품)은 빼지 않는다. false면 차감 없이 실결제 금액만 나눠 환불한다. 기본 true",
+  currencies:
+    "외화별 반품 배송비·교환 배송비(이슈 #130). 키는 판매 통화 코드이고 기본 통화(KRW)는 넣지 않는다. 금액은 그 통화의 최소 단위다. " +
+    "상품이 정한 통화 값이 상점 값보다 앞선다. 정하지 않은 외화로는 배송 상품을 팔지 않는다. 주면 맵 전체를 바꾼다",
 } as const;
 
+/** 외화 한 통화의 반품·교환 배송비 */
+export const currencyRefundFeesSchema = z.strictObject({
+  returnDeliveryFee: z.number().int().min(0).describe("이 통화의 반품 배송비. 통화의 최소 단위"),
+  exchangeDeliveryFee: z.number().int().min(0).describe("이 통화의 교환 배송비. 통화의 최소 단위"),
+});
+
+export type CurrencyRefundFees = z.infer<typeof currencyRefundFeesSchema>;
+
+const currencyRefundMapSchema = z
+  .partialRecord(currencyCodeSchema, currencyRefundFeesSchema)
+  .refine((map) => !(BASE_CURRENCY in map), {
+    message: "기본 통화는 currencies에 넣지 않습니다",
+  })
+  .describe(descriptions.currencies);
+
 /** 유효 환불 정책 — 상점 기본 + 상품별 덮어쓰기를 합친 결과 */
 export const refundPolicySchema = z.object({
   preShipmentDeliveryFeeRefund: z.boolean().describe(descriptions.preShipmentDeliveryFeeRefund),
@@ -44,6 +63,7 @@ export const refundPolicySchema = z.object({
     .describe(
       `${descriptions.couponShortfallCharge}. 이 필드가 없는 이전 서버 응답은 true로 읽는다`,
     ),
+  currencies: currencyRefundMapSchema.optional(),
 });
 
 export type RefundPolicy = z.infer<typeof refundPolicySchema>;
@@ -87,6 +107,7 @@ export const refundPolicyPatchSchema = z.strictObject({
     .optional()
     .describe(descriptions.conditionalFreeShortfallCharge),
   couponShortfallCharge: z.boolean().optional().describe(descriptions.couponShortfallCharge),
+  currencies: currencyRefundMapSchema.optional(),
 });
 
 export type RefundPolicyPatch = z.infer<typeof refundPolicyPatchSchema>;
@@ -114,9 +135,41 @@ export interface RefundPolicyProductInput {
 export function resolveRefundPolicy(
   storePolicy?: RefundPolicyPatch | null,
   product?: RefundPolicyProductInput | null,
-): RefundPolicy {
+): RefundPolicy;
+/**
+ * 통화의 유효 정책(이슈 #130) — 기본 통화는 위와 같다. 외화는 반품·교환 배송비를 상품 `currencies[통화]` → 상점 `currencies[통화]` 순으로 찾고
+ * (부담 규칙 boolean은 통화와 무관하다), 둘 다 없으면 null이다 — 그 통화로 배송 상품을 팔지 않는다(`NO_REFUND_FEE`).
+ * 결과의 `currencies`는 지우고 금액 필드가 그 통화 값이다. 통화별 반품비 해석은 이 함수 하나다
+ */
+export function resolveRefundPolicy(
+  storePolicy: RefundPolicyPatch | null | undefined,
+  product: RefundPolicyProductInput | null | undefined,
+  currency: string,
+): RefundPolicy | null;
+export function resolveRefundPolicy(
+  storePolicy?: RefundPolicyPatch | null,
+  product?: RefundPolicyProductInput | null,
+  currency: string = BASE_CURRENCY,
+): RefundPolicy | null {
   const store = { ...REFUND_POLICY_DEFAULTS, ...dropUndefined(storePolicy) };
-  return { ...store, ...(productRefundPolicyOverride(product) ?? {}) };
+  const override = productRefundPolicyOverride(product) ?? {};
+  const merged: RefundPolicy = { ...store, ...override };
+  if (currency === BASE_CURRENCY) {
+    // 상품 덮어쓰기의 currencies가 상점 맵을 통째로 덮지 않게 통화마다 합친다
+    if (store.currencies || override.currencies) {
+      merged.currencies = { ...store.currencies, ...override.currencies };
+    }
+    return merged;
+  }
+  const code = currency as keyof NonNullable<RefundPolicy["currencies"]>;
+  const fees = override.currencies?.[code] ?? store.currencies?.[code];
+  if (!fees) return null;
+  const { currencies: _byCurrency, ...rest } = merged;
+  return {
+    ...rest,
+    returnDeliveryFee: fees.returnDeliveryFee,
+    exchangeDeliveryFee: fees.exchangeDeliveryFee,
+  };
 }
 
 /**

package/src/schemas/shipping-policy.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { BASE_CURRENCY, currencyCodeSchema } from "./currency";
 import { type DeliveryType, type FulfillmentType, requiresShipping } from "./fulfillment";
 
 /**
@@ -32,14 +33,38 @@ const descriptions = {
     "null이면 전체 무료배송을 쓰지 않는다(상품별 조건부 무료는 그대로 동작한다). 기본 null",
   jejuSurcharge: "제주 지역 추가 배송비. 원 단위. **배송 묶음마다** 더한다. 기본 0",
   isolatedSurcharge: "도서산간 지역 추가 배송비. 원 단위. **배송 묶음마다** 더한다. 기본 0",
+  currencies:
+    "외화별 기본 배송비·전체 무료배송 기준액(이슈 #130). 키는 판매 통화 코드이고 기본 통화(KRW)는 넣지 않는다. 금액은 그 통화의 최소 단위다. " +
+    "정하지 않은 외화로는 배송 상품을 팔지 않는다. 지역 추가 배송비는 국내(기본 통화) 값만 있다. 주면 맵 전체를 바꾼다",
 } as const;
 
+/** 외화 한 통화의 상점 배송 값 */
+export const currencyShippingPolicySchema = z.strictObject({
+  baseDeliveryFee: z.number().int().min(0).describe("이 통화의 기본 배송비. 통화의 최소 단위"),
+  freeThreshold: z
+    .number()
+    .int()
+    .min(1)
+    .nullable()
+    .describe("이 통화의 전체 무료배송 기준액. null이면 쓰지 않는다"),
+});
+
+export type CurrencyShippingPolicy = z.infer<typeof currencyShippingPolicySchema>;
+
+const currencyShippingMapSchema = z
+  .partialRecord(currencyCodeSchema, currencyShippingPolicySchema)
+  .refine((map) => !(BASE_CURRENCY in map), {
+    message: "기본 통화는 currencies에 넣지 않습니다",
+  })
+  .describe(descriptions.currencies);
+
 /** 유효 배송비 정책 — 상점이 정하지 않은 항목은 `SHIPPING_POLICY_DEFAULTS`로 채운 값이다 */
 export const shippingPolicySchema = z.object({
   baseDeliveryFee: z.number().int().min(0).describe(descriptions.baseDeliveryFee),
   freeThreshold: z.number().int().min(1).nullable().describe(descriptions.freeThreshold),
   jejuSurcharge: z.number().int().min(0).describe(descriptions.jejuSurcharge),
   isolatedSurcharge: z.number().int().min(0).describe(descriptions.isolatedSurcharge),
+  currencies: currencyShippingMapSchema.optional(),
 });
 
 export type ShippingPolicy = z.infer<typeof shippingPolicySchema>;
@@ -68,17 +93,41 @@ export const shippingPolicyPatchSchema = z.strictObject({
   freeThreshold: z.number().int().min(1).nullable().optional().describe(descriptions.freeThreshold),
   jejuSurcharge: z.number().int().min(0).optional().describe(descriptions.jejuSurcharge),
   isolatedSurcharge: z.number().int().min(0).optional().describe(descriptions.isolatedSurcharge),
+  currencies: currencyShippingMapSchema.optional(),
 });
 
 export type ShippingPolicyPatch = z.infer<typeof shippingPolicyPatchSchema>;
 
-/** 유효 정책 해석 — 상점이 정한 항목 + `SHIPPING_POLICY_DEFAULTS` */
-export function resolveShippingPolicy(patch?: ShippingPolicyPatch | null): ShippingPolicy {
-  if (!patch) return { ...SHIPPING_POLICY_DEFAULTS };
-  const given = Object.fromEntries(
-    Object.entries(patch).filter(([, value]) => value !== undefined),
-  ) as ShippingPolicyPatch;
-  return { ...SHIPPING_POLICY_DEFAULTS, ...given };
+/**
+ * 유효 정책 해석 — 상점이 정한 항목 + `SHIPPING_POLICY_DEFAULTS`.
+ *
+ * `currency`(이슈 #130)를 주면 그 통화의 정책이다. 기본 통화는 지금과 같고, 외화는 `currencies[통화]`의 기본 배송비·무료 기준액에
+ * 지역 추가 배송비 0이다(할증 구간은 국내 값). 외화 값이 없으면 null — 그 통화로 배송 상품을 팔지 않는다. 통화별 값 해석은 이 함수 하나다.
+ */
+export function resolveShippingPolicy(patch?: ShippingPolicyPatch | null): ShippingPolicy;
+export function resolveShippingPolicy(
+  patch: ShippingPolicyPatch | null | undefined,
+  currency: string,
+): ShippingPolicy | null;
+export function resolveShippingPolicy(
+  patch?: ShippingPolicyPatch | null,
+  currency: string = BASE_CURRENCY,
+): ShippingPolicy | null {
+  const given = patch
+    ? (Object.fromEntries(
+        Object.entries(patch).filter(([, value]) => value !== undefined),
+      ) as ShippingPolicyPatch)
+    : {};
+  const base: ShippingPolicy = { ...SHIPPING_POLICY_DEFAULTS, ...given };
+  if (currency === BASE_CURRENCY) return base;
+  const foreign = base.currencies?.[currency as keyof typeof base.currencies];
+  if (!foreign) return null;
+  return {
+    baseDeliveryFee: foreign.baseDeliveryFee,
+    freeThreshold: foreign.freeThreshold,
+    jejuSurcharge: 0,
+    isolatedSurcharge: 0,
+  };
 }
 
 // ─── 지역 추가 배송비 ─────────────────────────────────────