SDK 레퍼런스

@yjroot/faketoss-sdk는 Toss Payments 스타일의 API를 유지하면서 Mock 환경 전용 옵션과 시나리오 기능을 제공합니다.

loadTossPayments

loadTossPayments(clientKey, options?)는 SDK 진입점입니다. 반환값은 TossPayments 인스턴스입니다.

const tossPayments = await loadTossPayments("test_ck_yjroot_faketoss_default");

TossPayments

인스턴스는 payment()와 widgets() 두 진입점을 제공합니다. 즉시 결제와 위젯 렌더링이 여기서 갈라집니다.

const payment = tossPayments.payment({ customerKey: "ANONYMOUS" });
const widgets = tossPayments.widgets({ customerKey: "user-123" });

ANONYMOUS

비회원 결제는 customerKey에 ANONYMOUS를 사용합니다. 회원 결제나 자동결제는 고정된 사용자 식별자를 넣으세요.

const payment = tossPayments.payment({ customerKey: "ANONYMOUS" });

payment()

payment()는 결제창 호출용 객체를 생성합니다. requestPayment와 requestBillingAuth는 이 객체에서 호출합니다.

const payment = tossPayments.payment({ customerKey: "ANONYMOUS" });

widgets()

widgets()는 위젯 방식 통합에서 사용합니다. 결제 금액도 객체 형태 { currency, value }로 설정합니다.

const widgets = tossPayments.widgets({ customerKey: "user-123" });
await widgets.setAmount({ currency: "KRW", value: 15000 });

requestPayment(params)

FakeToss 웹 예제는 아래 타입을 기준으로 결제창을 호출합니다.

type RequestPaymentParams = {
  method: "CARD" | "VIRTUAL_ACCOUNT" | "TRANSFER" | "MOBILE_PHONE" | "EASY_PAY";
  amount: {
    currency: "KRW";
    value: number;
  };
  orderId: string;
  orderName: string;
  successUrl: string;
  failUrl: string;
  customerEmail?: string;
  customerName?: string;
  customerMobilePhone?: string;
  taxFreeAmount?: number;
  metadata?: Record<string, string>;
};

requestBillingAuth(params)

정기결제용 카드 등록은 requestBillingAuth로 시작합니다. customerKey, successUrl, failUrl를 반드시 지정하세요.

await payment.requestBillingAuth({
  customerKey: "550e8400-e29b-41d4-a716-446655440000",
  successUrl: "http://localhost:3000/billing/success",
  failUrl: "http://localhost:3000/billing/fail",
});

LoadOptions

Mock 환경에서는 baseUrl, checkoutUrl, windowTarget를 조정할 수 있습니다. 실제 Toss SDK에는 없는 옵션입니다.

await loadTossPayments("test_ck_yjroot_faketoss_default", {
  baseUrl: "https://faketoss-alpha.yjroot.kr/v1",
  checkoutUrl: "https://faketoss-alpha.yjroot.kr/checkout",
  windowTarget: "self",
});

FakeToss scenario 확장

실패나 특수 상태를 재현하려면 metadata.scenario에 시나리오 코드를 넣습니다.

await payment.requestPayment({
  method: "CARD",
  amount: { currency: "KRW", value: 15000 },
  orderId: "order-scenario-001",
  orderName: "시나리오 테스트",
  successUrl: "http://localhost:3000/playground/success",
  failUrl: "http://localhost:3000/playground/fail",
  metadata: {
    scenario: "INVALID_CARD_NUMBER",
  },
});

에러 코드

code	설명
INVALID_ORDER_ID	orderId 형식이 비어 있거나 길이 제한을 벗어났을 때
INVALID_AMOUNT	amount.value가 0 이하이거나 숫자가 아닐 때
INVALID_SUCCESS_URL	successUrl이 비어 있거나 올바른 URL이 아닐 때
INVALID_FAIL_URL	failUrl이 비어 있거나 올바른 URL이 아닐 때
MISSING_CLIENT_KEY	clientKey 없이 loadTossPayments를 호출했을 때