connectbase-client 5.2.0 → 5.3.1

package/dist/index.d.mts

@@ -5534,6 +5534,26 @@ interface PreparePaymentRequest {
      * `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;
@@ -5567,6 +5587,11 @@ interface PreparePaymentResponse {
     launch_mode?: "overlay" | "redirect";
 }
 interface CreateCheckoutSessionRequest {
+    /**
+     * 사용할 자격증명 모드 오버라이드(선택). `prepare()` 의 `payment_mode` 와 적용 조건이 같다 —
+     * 서버 시크릿 키(`cb_sk_*`) 호출에서만 적용되고, 브라우저 공개 키 호출에서는 무시된다.
+     */
+    payment_mode?: PaymentMode;
     amount: number;
     currency: string;
     product_name: string;
@@ -5762,6 +5787,14 @@ declare class PaymentAPI {
      * })
      * // 확정 후 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
@@ -5769,6 +5802,11 @@ declare class PaymentAPI {
      *
      * 할인 코드는 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>;
     /**
@@ -7721,6 +7759,20 @@ type SubscriptionStatus = "active" | "paused" | "canceled" | "past_due" | "expir
 interface CreateSubscriptionRequest {
     /** 빌링키 ID (toss/stripe 필수, payapp 미사용 — payurl 모델) */
     billing_key_id?: string;
+    /**
+     * 구독 ID 를 직접 지정한다(선택). 미지정이면 서버가 `sub_<uuid>` 로 생성한다.
+     *
+     * 재시도 시 같은 값을 넘기면 최초 청구 orderID 가 결정적으로 만들어져 이중청구를 막는다 —
+     * 네트워크 실패로 create 를 다시 호출해야 할 때 쓴다.
+     */
+    subscription_id?: string;
+    /**
+     * true 면 구독 생성 즉시 1회차를 청구한다(빌링키 모델). false(기본)면 다음 결제일부터 청구.
+     * `trial_days` 가 있으면 즉시 청구하지 않는다(체험 종료 후 첫 청구).
+     *
+     * MoR(paddle/dodo)은 결제창에서 1회차를 받으므로 이 값을 쓰지 않는다.
+     */
+    start_now?: boolean;
     /** 플랜 이름 */
     plan_name: string;
     /** 플랜 설명 */
@@ -7758,6 +7810,14 @@ interface CreateSubscriptionRequest {
      * `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;
     /** 고객 이름 */

package/dist/index.d.ts

@@ -5534,6 +5534,26 @@ interface PreparePaymentRequest {
      * `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;
@@ -5567,6 +5587,11 @@ interface PreparePaymentResponse {
     launch_mode?: "overlay" | "redirect";
 }
 interface CreateCheckoutSessionRequest {
+    /**
+     * 사용할 자격증명 모드 오버라이드(선택). `prepare()` 의 `payment_mode` 와 적용 조건이 같다 —
+     * 서버 시크릿 키(`cb_sk_*`) 호출에서만 적용되고, 브라우저 공개 키 호출에서는 무시된다.
+     */
+    payment_mode?: PaymentMode;
     amount: number;
     currency: string;
     product_name: string;
@@ -5762,6 +5787,14 @@ declare class PaymentAPI {
      * })
      * // 확정 후 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
@@ -5769,6 +5802,11 @@ declare class PaymentAPI {
      *
      * 할인 코드는 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>;
     /**
@@ -7721,6 +7759,20 @@ type SubscriptionStatus = "active" | "paused" | "canceled" | "past_due" | "expir
 interface CreateSubscriptionRequest {
     /** 빌링키 ID (toss/stripe 필수, payapp 미사용 — payurl 모델) */
     billing_key_id?: string;
+    /**
+     * 구독 ID 를 직접 지정한다(선택). 미지정이면 서버가 `sub_<uuid>` 로 생성한다.
+     *
+     * 재시도 시 같은 값을 넘기면 최초 청구 orderID 가 결정적으로 만들어져 이중청구를 막는다 —
+     * 네트워크 실패로 create 를 다시 호출해야 할 때 쓴다.
+     */
+    subscription_id?: string;
+    /**
+     * true 면 구독 생성 즉시 1회차를 청구한다(빌링키 모델). false(기본)면 다음 결제일부터 청구.
+     * `trial_days` 가 있으면 즉시 청구하지 않는다(체험 종료 후 첫 청구).
+     *
+     * MoR(paddle/dodo)은 결제창에서 1회차를 받으므로 이 값을 쓰지 않는다.
+     */
+    start_now?: boolean;
     /** 플랜 이름 */
     plan_name: string;
     /** 플랜 설명 */
@@ -7758,6 +7810,14 @@ interface CreateSubscriptionRequest {
      * `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;
     /** 고객 이름 */

package/dist/index.js

@@ -6148,6 +6148,14 @@ var PaymentAPI = class {
    * })
    * // 확정 후 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
@@ -6155,6 +6163,11 @@ var PaymentAPI = class {
    *
    * 할인 코드는 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();

package/dist/index.mjs

@@ -6099,6 +6099,14 @@ var PaymentAPI = class {
    * })
    * // 확정 후 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
@@ -6106,6 +6114,11 @@ var PaymentAPI = class {
    *
    * 할인 코드는 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();

package/package.json

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