connectbase-client 5.1.1 → 5.3.0

package/dist/index.d.mts

@@ -5511,6 +5511,49 @@ interface PreparePaymentRequest {
      * 상품별로 세금 카테고리를 달리 할 때만 지정한다. Paddle 은 무시한다.
      */
     provider_price_ref?: string;
+    /**
+     * 이 결제에 미리 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드(Dodo Discounts / Paddle Discounts)에서 발행한다 — ConnectBase 는 코드를
+     * 전달만 하고 발행/한도/유효기간은 PG 설정이 권위다. Paddle 은 API 가 코드 대신 내부 ID 를
+     * 받으므로 서버가 코드를 조회해 해소한다.
+     *
+     * 실패는 조용히 정가로 넘어가지 않고 400 으로 거절된다:
+     * - `discount_code_invalid` — 없거나 만료/비활성 코드
+     * - `discount_code_unsupported` — 할인 코드를 지원하지 않는 프로바이더(toss/stripe/payapp/paypal)
+     *
+     * 할인이 적용되면 확정 응답의 `amount` 는 **실제 청구액**(할인 후)이고 차감분은
+     * `discount_amount` 로 온다.
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 **고객이 직접** 쿠폰을 입력하도록 허용할지(선택).
+     *
+     * 미지정이면 프로바이더 기본값을 따른다. Dodo 는 결제창마다 켜고 끌 수 있다.
+     * Paddle 오버레이는 입력칸을 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
+    /**
+     * 결제를 마친 고객이 돌아올 주소(선택).
+     *
+     * 미지정이면 콘솔 결제 설정의 success_url, 그것도 비어 있으면 **PG 대시보드의 브랜드 주소**로
+     * 돌아갑니다. 그 페이지가 결제 복귀를 처리하지 않으면 "결제는 완료됐는데 권한이 지급되지 않는"
+     * 상태가 됩니다.
+     *
+     * 요청 단위라 QA/프로덕션/미리보기 배포가 각자 자기 호스트로 복귀할 수 있습니다 — 앱 단위
+     * success_url 하나로는 두 환경을 동시에 가리킬 수 없습니다.
+     *
+     * **앱이 소유한 origin 만 허용됩니다**: 웹 스토리지 호스트(production 과 `--qa` 미러),
+     * 연결된 커스텀 도메인, 결제 설정의 success_url/fail_url origin, (로컬 개발을 켠 앱이면)
+     * localhost. 그 외는 400 `return_url_not_allowed`, 형식 오류는 400 `return_url_invalid`.
+     */
+    return_url?: string;
+    /**
+     * 결제 실패/취소 시 복귀 주소(선택). 검증 규칙과 폴백은 `return_url` 과 같습니다
+     * (미지정 시 결제 설정의 fail_url).
+     */
+    fail_url?: string;
     amount: number;
     order_name: string;
     order_id?: string;
@@ -5573,7 +5616,10 @@ interface ConfirmPaymentRequest {
 interface ConfirmPaymentResponse {
     payment_id: string;
     order_id: string;
+    /** **실제 청구된** 금액. 할인이 적용되면 준비 금액보다 작다. */
     amount: number;
+    /** 할인으로 차감된 금액(준비 금액 − 실제 청구액). 할인이 없으면 생략된다. */
+    discount_amount?: number;
     status: PaymentStatus;
     method: string;
     receipt_url?: string;
@@ -5610,6 +5656,13 @@ interface PaymentDetail {
     settlement_currency?: string;
     /** 청구 국가 ISO 3166-1 alpha-2 (MoR 제공 시) */
     country?: string;
+    /** 적용된 할인 코드 (준비 시 지정한 경우). */
+    discount_code?: string;
+    /**
+     * 할인으로 차감된 금액. `amount` 는 이미 할인이 반영된 실제 청구액이므로,
+     * 정가를 표시하려면 `amount + discount_amount` 로 복원한다.
+     */
+    discount_amount?: number;
     status: PaymentStatus;
     payment_provider?: PaymentProvider;
     /** 이 결제가 사용한 자격증명 모드 (test | live). */
@@ -5719,10 +5772,36 @@ declare class PaymentAPI {
      * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
      *   window.location.href = result.payapp_pay_url
      * }
+     *
+     * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+     * const discounted = await cb.payment.prepare({
+     *   amount: 10000,
+     *   order_name: '프리미엄 1개월',
+     *   discount_code: 'LAUNCH50',   // 미리 적용
+     *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+     * })
+     * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+     * // discount_amount 는 차감분이다.
+     *
+     * // 복귀 주소 — 배포마다 자기 호스트로 돌아오게 한다 (QA 가 라이브로 튕기지 않도록)
+     * const withReturn = await cb.payment.prepare({
+     *   amount: 14900,
+     *   order_name: '프리미엄 1개월',
+     *   return_url: `${window.location.origin}/app/premium?paid=1`,
+     *   fail_url: `${window.location.origin}/app/premium?failed=1`,
+     * })
      * ```
      *
      * @remarks
      * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+     *
+     * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+     * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
+     *
+     * `return_url`/`fail_url` 을 생략하면 콘솔 결제 설정의 success_url/fail_url 을 쓰고, 그것도
+     * 비어 있으면 **PG 대시보드의 브랜드 주소**로 복귀합니다 — 그 페이지가 결제 복귀를 처리하지
+     * 않으면 결제는 완료되지만 권한이 지급되지 않습니다. 앱이 소유한 origin 만 허용되며,
+     * 그 외는 400 `return_url_not_allowed` 입니다.
      */
     prepare(data: PreparePaymentRequest): Promise<PreparePaymentResponse>;
     /**
@@ -7687,8 +7766,39 @@ interface CreateSubscriptionRequest {
     billing_cycle: BillingCycle;
     /** 결제일 (monthly: 1-28일, weekly: 0-6 요일) */
     billing_day?: number;
-    /** 트라이얼 기간 (일) */
+    /**
+     * 트라이얼(무료 체험) 기간 (일).
+     *
+     * 빌링키 모델(toss/stripe)에서는 ConnectBase 스케줄러가 체험 종료일에 첫 청구를 건다.
+     * MoR 은 PG 가 정기청구를 소유하므로 결제창 생성 시 체험 일수를 함께 보낸다:
+     * - **Dodo**: 구독마다 지정 가능(0~10000일)
+     * - **Paddle**: 트라이얼이 요금제(price)에 붙는 속성이라 구독마다 지정할 수 없다 →
+     *   400 `trial_days_unsupported`. 체험이 설정된 price 를 Paddle 대시보드에서 따로 만들어 쓴다.
+     */
     trial_days?: number;
+    /**
+     * 첫 결제에 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드에서 발행하며, 몇 주기까지 할인할지도 그쪽 설정이 정한다
+     * (예: Dodo `subscription_cycles` 로 "3개월간 50%"). ConnectBase 는 코드만 전달한다.
+     *
+     * 400 `discount_code_invalid`(없거나 만료) / `discount_code_unsupported`(미지원 프로바이더).
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 고객이 직접 쿠폰을 입력하도록 허용할지(선택).
+     * Paddle 오버레이는 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
+    /**
+     * 결제창을 마친 고객이 돌아올 주소(선택, 리다이렉트형 MoR).
+     *
+     * 미지정이면 결제 설정의 success_url, 그것도 비면 PG 대시보드의 브랜드 주소로 갑니다.
+     * 앱이 소유한 origin 만 허용되며(검증 규칙은 `payment.prepare()` 와 동일),
+     * 그 외는 400 `return_url_not_allowed` 입니다.
+     */
+    return_url?: string;
     /** 고객 이메일 */
     customer_email?: string;
     /** 고객 이름 */
@@ -8124,7 +8234,27 @@ declare class SubscriptionAPI {
      *     billing_day: 15,  // 매월 15일 결제
      *     trial_days: 7     // 7일 무료 체험
      * })
+     *
+     * // MoR(dodo/paddle) 구독 + 할인 코드
+     * const promo = await client.subscription.create({
+     *     plan_name: '프리미엄 플랜',
+     *     amount: 9900,
+     *     billing_cycle: 'monthly',
+     *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+     *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+     *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+     * })
      * ```
+     *
+     * @remarks
+     * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+     * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+     * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+     *   체험은 요금제(price) 속성이라 구독별 지정 불가
+     * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+     *
+     * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+     * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
      */
     create(data: CreateSubscriptionRequest): Promise<SubscriptionResponse>;
     /**

package/dist/index.d.ts

@@ -5511,6 +5511,49 @@ interface PreparePaymentRequest {
      * 상품별로 세금 카테고리를 달리 할 때만 지정한다. Paddle 은 무시한다.
      */
     provider_price_ref?: string;
+    /**
+     * 이 결제에 미리 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드(Dodo Discounts / Paddle Discounts)에서 발행한다 — ConnectBase 는 코드를
+     * 전달만 하고 발행/한도/유효기간은 PG 설정이 권위다. Paddle 은 API 가 코드 대신 내부 ID 를
+     * 받으므로 서버가 코드를 조회해 해소한다.
+     *
+     * 실패는 조용히 정가로 넘어가지 않고 400 으로 거절된다:
+     * - `discount_code_invalid` — 없거나 만료/비활성 코드
+     * - `discount_code_unsupported` — 할인 코드를 지원하지 않는 프로바이더(toss/stripe/payapp/paypal)
+     *
+     * 할인이 적용되면 확정 응답의 `amount` 는 **실제 청구액**(할인 후)이고 차감분은
+     * `discount_amount` 로 온다.
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 **고객이 직접** 쿠폰을 입력하도록 허용할지(선택).
+     *
+     * 미지정이면 프로바이더 기본값을 따른다. Dodo 는 결제창마다 켜고 끌 수 있다.
+     * Paddle 오버레이는 입력칸을 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
+    /**
+     * 결제를 마친 고객이 돌아올 주소(선택).
+     *
+     * 미지정이면 콘솔 결제 설정의 success_url, 그것도 비어 있으면 **PG 대시보드의 브랜드 주소**로
+     * 돌아갑니다. 그 페이지가 결제 복귀를 처리하지 않으면 "결제는 완료됐는데 권한이 지급되지 않는"
+     * 상태가 됩니다.
+     *
+     * 요청 단위라 QA/프로덕션/미리보기 배포가 각자 자기 호스트로 복귀할 수 있습니다 — 앱 단위
+     * success_url 하나로는 두 환경을 동시에 가리킬 수 없습니다.
+     *
+     * **앱이 소유한 origin 만 허용됩니다**: 웹 스토리지 호스트(production 과 `--qa` 미러),
+     * 연결된 커스텀 도메인, 결제 설정의 success_url/fail_url origin, (로컬 개발을 켠 앱이면)
+     * localhost. 그 외는 400 `return_url_not_allowed`, 형식 오류는 400 `return_url_invalid`.
+     */
+    return_url?: string;
+    /**
+     * 결제 실패/취소 시 복귀 주소(선택). 검증 규칙과 폴백은 `return_url` 과 같습니다
+     * (미지정 시 결제 설정의 fail_url).
+     */
+    fail_url?: string;
     amount: number;
     order_name: string;
     order_id?: string;
@@ -5573,7 +5616,10 @@ interface ConfirmPaymentRequest {
 interface ConfirmPaymentResponse {
     payment_id: string;
     order_id: string;
+    /** **실제 청구된** 금액. 할인이 적용되면 준비 금액보다 작다. */
     amount: number;
+    /** 할인으로 차감된 금액(준비 금액 − 실제 청구액). 할인이 없으면 생략된다. */
+    discount_amount?: number;
     status: PaymentStatus;
     method: string;
     receipt_url?: string;
@@ -5610,6 +5656,13 @@ interface PaymentDetail {
     settlement_currency?: string;
     /** 청구 국가 ISO 3166-1 alpha-2 (MoR 제공 시) */
     country?: string;
+    /** 적용된 할인 코드 (준비 시 지정한 경우). */
+    discount_code?: string;
+    /**
+     * 할인으로 차감된 금액. `amount` 는 이미 할인이 반영된 실제 청구액이므로,
+     * 정가를 표시하려면 `amount + discount_amount` 로 복원한다.
+     */
+    discount_amount?: number;
     status: PaymentStatus;
     payment_provider?: PaymentProvider;
     /** 이 결제가 사용한 자격증명 모드 (test | live). */
@@ -5719,10 +5772,36 @@ declare class PaymentAPI {
      * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
      *   window.location.href = result.payapp_pay_url
      * }
+     *
+     * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+     * const discounted = await cb.payment.prepare({
+     *   amount: 10000,
+     *   order_name: '프리미엄 1개월',
+     *   discount_code: 'LAUNCH50',   // 미리 적용
+     *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+     * })
+     * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+     * // discount_amount 는 차감분이다.
+     *
+     * // 복귀 주소 — 배포마다 자기 호스트로 돌아오게 한다 (QA 가 라이브로 튕기지 않도록)
+     * const withReturn = await cb.payment.prepare({
+     *   amount: 14900,
+     *   order_name: '프리미엄 1개월',
+     *   return_url: `${window.location.origin}/app/premium?paid=1`,
+     *   fail_url: `${window.location.origin}/app/premium?failed=1`,
+     * })
      * ```
      *
      * @remarks
      * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+     *
+     * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+     * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
+     *
+     * `return_url`/`fail_url` 을 생략하면 콘솔 결제 설정의 success_url/fail_url 을 쓰고, 그것도
+     * 비어 있으면 **PG 대시보드의 브랜드 주소**로 복귀합니다 — 그 페이지가 결제 복귀를 처리하지
+     * 않으면 결제는 완료되지만 권한이 지급되지 않습니다. 앱이 소유한 origin 만 허용되며,
+     * 그 외는 400 `return_url_not_allowed` 입니다.
      */
     prepare(data: PreparePaymentRequest): Promise<PreparePaymentResponse>;
     /**
@@ -7687,8 +7766,39 @@ interface CreateSubscriptionRequest {
     billing_cycle: BillingCycle;
     /** 결제일 (monthly: 1-28일, weekly: 0-6 요일) */
     billing_day?: number;
-    /** 트라이얼 기간 (일) */
+    /**
+     * 트라이얼(무료 체험) 기간 (일).
+     *
+     * 빌링키 모델(toss/stripe)에서는 ConnectBase 스케줄러가 체험 종료일에 첫 청구를 건다.
+     * MoR 은 PG 가 정기청구를 소유하므로 결제창 생성 시 체험 일수를 함께 보낸다:
+     * - **Dodo**: 구독마다 지정 가능(0~10000일)
+     * - **Paddle**: 트라이얼이 요금제(price)에 붙는 속성이라 구독마다 지정할 수 없다 →
+     *   400 `trial_days_unsupported`. 체험이 설정된 price 를 Paddle 대시보드에서 따로 만들어 쓴다.
+     */
     trial_days?: number;
+    /**
+     * 첫 결제에 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드에서 발행하며, 몇 주기까지 할인할지도 그쪽 설정이 정한다
+     * (예: Dodo `subscription_cycles` 로 "3개월간 50%"). ConnectBase 는 코드만 전달한다.
+     *
+     * 400 `discount_code_invalid`(없거나 만료) / `discount_code_unsupported`(미지원 프로바이더).
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 고객이 직접 쿠폰을 입력하도록 허용할지(선택).
+     * Paddle 오버레이는 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
+    /**
+     * 결제창을 마친 고객이 돌아올 주소(선택, 리다이렉트형 MoR).
+     *
+     * 미지정이면 결제 설정의 success_url, 그것도 비면 PG 대시보드의 브랜드 주소로 갑니다.
+     * 앱이 소유한 origin 만 허용되며(검증 규칙은 `payment.prepare()` 와 동일),
+     * 그 외는 400 `return_url_not_allowed` 입니다.
+     */
+    return_url?: string;
     /** 고객 이메일 */
     customer_email?: string;
     /** 고객 이름 */
@@ -8124,7 +8234,27 @@ declare class SubscriptionAPI {
      *     billing_day: 15,  // 매월 15일 결제
      *     trial_days: 7     // 7일 무료 체험
      * })
+     *
+     * // MoR(dodo/paddle) 구독 + 할인 코드
+     * const promo = await client.subscription.create({
+     *     plan_name: '프리미엄 플랜',
+     *     amount: 9900,
+     *     billing_cycle: 'monthly',
+     *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+     *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+     *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+     * })
      * ```
+     *
+     * @remarks
+     * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+     * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+     * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+     *   체험은 요금제(price) 속성이라 구독별 지정 불가
+     * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+     *
+     * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+     * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
      */
     create(data: CreateSubscriptionRequest): Promise<SubscriptionResponse>;
     /**

package/dist/index.js

@@ -6138,10 +6138,36 @@ var PaymentAPI = class {
    * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
    *   window.location.href = result.payapp_pay_url
    * }
+   *
+   * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+   * const discounted = await cb.payment.prepare({
+   *   amount: 10000,
+   *   order_name: '프리미엄 1개월',
+   *   discount_code: 'LAUNCH50',   // 미리 적용
+   *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+   * })
+   * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+   * // discount_amount 는 차감분이다.
+   *
+   * // 복귀 주소 — 배포마다 자기 호스트로 돌아오게 한다 (QA 가 라이브로 튕기지 않도록)
+   * const withReturn = await cb.payment.prepare({
+   *   amount: 14900,
+   *   order_name: '프리미엄 1개월',
+   *   return_url: `${window.location.origin}/app/premium?paid=1`,
+   *   fail_url: `${window.location.origin}/app/premium?failed=1`,
+   * })
    * ```
    *
    * @remarks
    * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+   *
+   * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+   * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
+   *
+   * `return_url`/`fail_url` 을 생략하면 콘솔 결제 설정의 success_url/fail_url 을 쓰고, 그것도
+   * 비어 있으면 **PG 대시보드의 브랜드 주소**로 복귀합니다 — 그 페이지가 결제 복귀를 처리하지
+   * 않으면 결제는 완료되지만 권한이 지급되지 않습니다. 앱이 소유한 origin 만 허용되며,
+   * 그 외는 400 `return_url_not_allowed` 입니다.
    */
   async prepare(data) {
     const prefix = this.getPublicPrefix();
@@ -9023,7 +9049,27 @@ var SubscriptionAPI = class {
    *     billing_day: 15,  // 매월 15일 결제
    *     trial_days: 7     // 7일 무료 체험
    * })
+   *
+   * // MoR(dodo/paddle) 구독 + 할인 코드
+   * const promo = await client.subscription.create({
+   *     plan_name: '프리미엄 플랜',
+   *     amount: 9900,
+   *     billing_cycle: 'monthly',
+   *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+   *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+   *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+   * })
    * ```
+   *
+   * @remarks
+   * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+   * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+   * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+   *   체험은 요금제(price) 속성이라 구독별 지정 불가
+   * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+   *
+   * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+   * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
    */
   async create(data) {
     const prefix = this.getPublicPrefix();

package/dist/index.mjs

@@ -6089,10 +6089,36 @@ var PaymentAPI = class {
    * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
    *   window.location.href = result.payapp_pay_url
    * }
+   *
+   * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+   * const discounted = await cb.payment.prepare({
+   *   amount: 10000,
+   *   order_name: '프리미엄 1개월',
+   *   discount_code: 'LAUNCH50',   // 미리 적용
+   *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+   * })
+   * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+   * // discount_amount 는 차감분이다.
+   *
+   * // 복귀 주소 — 배포마다 자기 호스트로 돌아오게 한다 (QA 가 라이브로 튕기지 않도록)
+   * const withReturn = await cb.payment.prepare({
+   *   amount: 14900,
+   *   order_name: '프리미엄 1개월',
+   *   return_url: `${window.location.origin}/app/premium?paid=1`,
+   *   fail_url: `${window.location.origin}/app/premium?failed=1`,
+   * })
    * ```
    *
    * @remarks
    * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+   *
+   * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+   * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
+   *
+   * `return_url`/`fail_url` 을 생략하면 콘솔 결제 설정의 success_url/fail_url 을 쓰고, 그것도
+   * 비어 있으면 **PG 대시보드의 브랜드 주소**로 복귀합니다 — 그 페이지가 결제 복귀를 처리하지
+   * 않으면 결제는 완료되지만 권한이 지급되지 않습니다. 앱이 소유한 origin 만 허용되며,
+   * 그 외는 400 `return_url_not_allowed` 입니다.
    */
   async prepare(data) {
     const prefix = this.getPublicPrefix();
@@ -8974,7 +9000,27 @@ var SubscriptionAPI = class {
    *     billing_day: 15,  // 매월 15일 결제
    *     trial_days: 7     // 7일 무료 체험
    * })
+   *
+   * // MoR(dodo/paddle) 구독 + 할인 코드
+   * const promo = await client.subscription.create({
+   *     plan_name: '프리미엄 플랜',
+   *     amount: 9900,
+   *     billing_cycle: 'monthly',
+   *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+   *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+   *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+   * })
    * ```
+   *
+   * @remarks
+   * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+   * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+   * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+   *   체험은 요금제(price) 속성이라 구독별 지정 불가
+   * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+   *
+   * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+   * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
    */
   async create(data) {
     const prefix = this.getPublicPrefix();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "connectbase-client",
-	"version": "5.1.1",
+	"version": "5.3.0",
 	"description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
 	"repository": {
 		"type": "git",