@gj-kit/toss-payments recipes

Each code block reuses a public-contract example already type-checked in the package README.

1. Assemble a confirmation flow with an order store

Parse the server key at boot and make the host order store explicit before confirmation becomes available.

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

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

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.

2. Add billing and webhook boundaries deliberately

Wire only the stores needed by each flow so absent capabilities cannot be used accidentally.

Two mistakes that normally pass review and detonate in production — a half-wired kit and a billing approve with no idempotency key — are both compile errors here.

import { idempotencyKey, orThrow } from '@gj-kit/toss-payments';
import type { BillingKeyStore, BillingOrder, BillingProfile, OrderStore } from '@gj-kit/toss-payments/server';
import { createTossPayments, parseApiSecretKey } from '@gj-kit/toss-payments/server';

declare const apiSecret: string; // app owns
declare const orderStore: OrderStore; // app owns
declare const billingKeyStore: BillingKeyStore; // app owns
declare const profile: BillingProfile; // app owns
declare const order: BillingOrder; // app owns

export const toss = createTossPayments({
  secretKey: orThrow(parseApiSecretKey(apiSecret)),
  orders: orderStore, // omit and `toss.confirm` is not on the type
  billingKeys: billingKeyStore, // omit and `toss.billing` is not on the type
});

// toss.billing.approve(profile, order); -> error TS2554: Expected 3 arguments, but got 2.
export const charged = toss.billing.approve(profile, order, {
  idempotencyKey: orThrow(idempotencyKey(`sub:2026-09:${profile.customerKey}`)),
});

Use the complete API reference for every export and import path.