open-index/open-npm huggingface dataset:
npm package: @k-wallet/sdk
Description: 쇼핑몰 FE에서 Wallet 결제창으로 이동시키는 최소 SDK입니다.
Latest version: 0.6.2

# @k-wallet/sdk

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

- 쇼핑몰 도입 가이드: [SHOPPING_MALL_INTEGRATION_GUIDE.md](./SHOPPING_MALL_INTEGRATION_GUIDE.md)

## 설치

```bash
npm i @k-wallet/sdk
```

## 사용법

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

```ts
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) 함수 직접 호출

```ts
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

## 로컬 프리뷰

```bash
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`
npm package: @k-wallet/server
Description: 쇼핑몰 백엔드에서 Wallet 서버를 호출하기 위한 Node.js SDK입니다.
Latest version: 0.1.0

# @k-wallet/server

쇼핑몰 백엔드에서 Wallet 서버를 호출하기 위한 Node.js SDK입니다.

## 설치

```bash
npm i @k-wallet/server
```

## 사용 예시

```ts
import { createWalletServerClient } from '@k-wallet/server';

const wallet = createWalletServerClient(process.env.WALLET_SECRET_KEY!, {
  baseUrl: 'https://api.kst-wallet.xyz',
  timeoutMs: 10000,
});

const prepared = await wallet.prepareCheckout(
  {
    orderId: 'order-20260326-001',
    merchantName: 'my-shop',
    amount: 32000,
    successUrl: 'https://shop.example.com/pay/success',
    failUrl: 'https://shop.example.com/pay/fail',
  },
  { idempotencyKey: 'checkout-order-20260326-001' },
);

const confirmed = await wallet.confirmPayment(
  {
    paymentKey: 'pay_...',
    orderId: 'order-20260326-001',
    amount: 32000,
  },
  { idempotencyKey: 'confirm-order-20260326-001' },
);

if (confirmed.confirmed) {
  // 주문 확정
}
```

## 인증 헤더

- `x-secret-key`: 필수
- `idempotency-key`: 선택 (prepare/confirm 권장)