@gj-kit/toss-payments

TypeScript 서버와 브라우저를 위한 타입 안전 Toss Payments 위젯 및 API v2 흐름입니다.

현재 npm 최신판: 0.6.1

사용할 때

결제 키 경계, 주문 금액 검증, 웹훅 신뢰도, 멱등 빌링 흐름을 타입으로 강제해야 할 때 사용합니다.

사용하지 않을 때

완전한 주문 시스템으로 취급하거나 raw secret, audit payload, 환불 정책을 범용 계층에 저장하지 마세요.

Golden path

완료 상태: 전달한 store에 맞는 결제 흐름만 노출하는 서버 전용 payment kit을 만듭니다.

1. 설치

pnpm add @gj-kit/toss-payments

2. 앱이 소유할 경계를 정합니다

부팅 시 API secret을 파싱하고, 승인을 활성화하기 전에 서버 소유 order store를 제공합니다.

3. 최소 연결부터 시작합니다

먼저 아래 코드를 복사한 뒤, 위에서 언급한 앱 소유 값만 교체하세요.

import { orThrow } from '@gj-kit/toss-payments';
import { createTossPayments, parseApiSecretKey } from '@gj-kit/toss-payments/server';

declare const apiSecretFromEnv: string; // Read this once from your server environment.

export const toss = createTossPayments({
  secretKey: orThrow(parseApiSecretKey(apiSecretFromEnv)),
});

// Add your OrderStore to enable toss.confirm; the type exposes only wired flows.

환경과 peer

엔진: node >=20

Peer	지원 범위	필요한 위치
`@tosspayments/tosspayments-sdk`	`^2`	문서화된 optional subpath에서만

공개 subpath

Entry	Exported symbols
`Root entry`	155
`./browser`	14
`./server`	257
`./testing`	9
`./webhook`	40

안전 경계

server 키 parser를 브라우저 코드에 import하거나 문서화된 검증 경로 없이 redirect/웹훅을 신뢰하지 마세요. secret과 정확한 audit body는 저장 시 암호화하세요.

API reference

전체 API reference에는 선언 파일에서 생성한 모든 공개 함수, 클래스, 타입, 상수, 오류 계약이 있습니다. 각 항목은 import path, release signature, package version을 표시합니다.