@k-wallet/sdk

쇼핑몰 FE에서 Wallet 결제창으로 이동시키는 최소 SDK입니다.

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

설치

npm i @k-wallet/sdk

사용법

1) 클라이언트 초기화 + requestPayment

import { createWalletClient } from '@k-wallet/sdk';

const wallet = createWalletClient({
  baseUrl: 'https://wallet.kst-wallet.xyz', // 선택
});

wallet.requestPayment({
  checkoutUrl: 'https://wallet.kst-wallet.xyz/checkout?checkoutSessionId=cs_123',
  appLaunchUrl: 'kwallet://checkout?checkoutSessionId=cs_123',
  strategy: 'APP_FIRST',
  fallbackTimeoutMs: 1200,
  checkoutExpiresAt: '2026-03-19T12:30:00.000Z',
  failUrl: 'https://shop.example.com/pay/fail',
  orderId: 'order-001',
});

2) 함수 직접 호출

import { requestPayment } from '@k-wallet/sdk';

requestPayment(
  {
    checkoutUrl: 'https://wallet.kst-wallet.xyz/checkout?checkoutSessionId=cs_123',
    appLaunchUrl: 'kwallet://checkout?checkoutSessionId=cs_123',
  },
  { baseUrl: 'https://wallet.kst-wallet.xyz' },
);

옵션

• strategy
  • APP_FIRST: 앱 먼저 시도, 실패 시 웹 fallback
  • WEB_ONLY: 웹 checkout 바로 이동
• fallbackTimeoutMs
  • APP_FIRST에서 fallback 대기 시간(ms)
• checkoutExpiresAt
  • 만료 시 failUrl로 SESSION_EXPIRED와 함께 이동
• baseUrl
  • 상대 URL이 들어올 때 기준 URL

로컬 프리뷰

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

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