@k-stable/sdk

쇼핑몰 FE에서 Wallet 결제창을 호출하기 위한 SDK입니다.

• 쇼핑몰 도입 가이드: SHOPPING_MALL_INTEGRATION_GUIDE.md

설치

npm i @k-stable/sdk

핵심 API (Toss-style)

import { loadKStablePay, ANONYMOUS } from '@k-stable/sdk';

const kStable = await loadKStablePay('YOUR_CLIENT_KEY');

const widget = kStable.wallet(ANONYMOUS); // 회원이면 customer UUID

widget.setInfo({
  customerName: '홍길동',
  customerPhone: '01012345678',
  productName: '멤버십 구독권',
  amount: 12000,
  checkoutExpiresAt: '2026-03-19T12:30:00.000Z',
});

widget.renderWallet('#wallet-widget');

widget.requestPayment({
  orderId: 'order-001',
  customerId: 'uuid-...',
  customerName: '홍길동',
  customerPhone: '01012345678',
  productName: '멤버십 구독권',
  amount: 12000,
  successUrl: 'https://shop.example.com/pay/success',
  failUrl: 'https://shop.example.com/pay/fail',
  checkoutExpiresAt: '2026-03-19T12:30:00.000Z',
});

• 회원 결제: customerKey = 회원 UUID
• 비회원 결제: customerKey = ANONYMOUS
• SDK 초기화는 clientKey로만 수행합니다.

고급 옵션이 필요한 경우:

await loadKStablePay('YOUR_CLIENT_KEY', {
  checkoutOrigin: 'https://wallet.example.com',
  checkoutPath: '/checkout',
  appDeepLinkBaseUrl: 'kwallet://checkout',
  defaultOpenStrategy: 'APP_FIRST',
  fallbackTimeoutMs: 1200,
});

결제 전략

• APP_FIRST
  • Wallet 앱 열기 시도
  • 앱 미설치/취소/실패 시 웹 checkout으로 fallback
• WEB_ONLY
  • 바로 웹 checkout 이동

checkoutExpiresAt이 지난 상태에서 결제 요청 시 SDK가 SESSION_EXPIRED로 failUrl 이동 처리합니다.

결과 파싱

import { initWalletSdk, assertSuccessResult } from '@k-stable/sdk';

const sdk = initWalletSdk({
  checkoutOrigin: 'https://wallet.example.com',
  merchantId: 'mrc_demo_001',
});

const result = sdk.parseRedirectResult(window.location.href);
if (result.type === 'SUCCESS') {
  assertSuccessResult(result, { orderId: 'order-001', amount: 12000 });
}

Legacy API (호환)

기존 initWalletSdk().requestPaymentRedirect(...)도 계속 사용 가능합니다.

UI preview (local)

cd /Users/moonyaeyoon/k-stable-pay/wallet/open-sdk
npm run build
python3 -m http.server 5500

• http://localhost:5500/examples/preview/merchant.html