@gj-kit/toss-payments

Type-safe Toss Payments widget and API v2 flows for TypeScript servers and browsers.

Current npm latest: 0.6.1

Use it when

Use it when payment key boundaries, order-amount verification, webhook trust, and idempotent billing flows must be encoded in types.

Do not use it when

Do not treat it as a complete order system or store raw secrets, audit payloads, and refund policy in its generic layer.

Golden path

Outcome: A server-only payment kit whose available flows match the stores you pass in.

1. Install

pnpm add @gj-kit/toss-payments

2. Keep the app-owned boundary explicit

Parse the API secret at boot and provide your server-owned order store before enabling confirmation.

3. Start with the smallest integration

Copy this first, then replace only the app-owned values named above.

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.

Runtime and peers

Engines: node >=20

Peer	Supported range	Required for
`@tosspayments/tosspayments-sdk`	`^2`	documented optional subpaths only

Public subpaths

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

Safety boundary

Never import server key parsers into browser code or trust a redirect/webhook without the documented verification path. Keep secrets and exact audit bodies encrypted at rest.

API reference

complete API reference contains every public function, class, type, constant, and error contract generated from release declarations. Each item shows its import path, release signature, and package version.

@gj-kit/toss-payments-nestjs, @gj-kit/toss-payments-postgresql

npm · GitHub