3분 가이드

설치, 결제창 호출, 리다이렉트 처리, 서버 승인까지 FakeToss 전체 플로우를 한 번에 연결합니다.

1. SDK 설치

브라우저 결제창은 @yjroot/faketoss-sdk 하나로 시작합니다. 테스트 키는 test_ck_yjroot_faketoss_default 입니다.

npm install @yjroot/faketoss-sdk

2. 결제창 호출

amount는 숫자가 아니라 { currency, value } 객체를 받습니다. 실패 테스트는 metadata.scenario에 시나리오 코드를 넣어 재현할 수 있습니다.

"use client";

import { loadTossPayments } from "@yjroot/faketoss-sdk";

const clientKey = "test_ck_yjroot_faketoss_default";

export async function openCheckout() {
  const tossPayments = await loadTossPayments(clientKey);
  const payment = tossPayments.payment({
    customerKey: "ANONYMOUS",
  });

  await payment.requestPayment({
    method: "CARD",
    amount: { currency: "KRW", value: 15000 },
    orderId: "order-" + Date.now(),
    orderName: "FakeToss 티셔츠",
    successUrl: "http://localhost:3000/playground/success",
    failUrl: "http://localhost:3000/playground/fail",
    customerEmail: "dev@faketoss.dev",
    customerName: "홍길동",
    metadata: {
      scenario: "FAILED_PAYMENT_INTERNAL_SYSTEM_PROCESSING",
    },
  });
}

3. 리다이렉트 처리

성공 페이지에서는 쿼리스트링의 paymentKey, orderId, amount를 읽고 바로 서버 승인 API로 넘기면 됩니다.

"use client";

import { useSearchParams } from "next/navigation";

export default function SuccessPage() {
  const searchParams = useSearchParams();
  const paymentKey = searchParams.get("paymentKey");
  const orderId = searchParams.get("orderId");
  const amount = Number(searchParams.get("amount") || 0);

  return <pre>{JSON.stringify({ paymentKey, orderId, amount }, null, 2)}</pre>;
}

4. 서버 승인

서버는 Secret Key로 Basic Auth를 만들고 POST /v1/payments/confirm를 호출합니다. 아래는 curl과 Node.js fetch 예시입니다.

curl -X POST https://faketoss-alpha.yjroot.kr/v1/payments/confirm \
  -H "Authorization: Basic $(printf 'test_sk_yjroot_faketoss_default:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentKey": "pay_123",
    "orderId": "order-1713681548000",
    "amount": 15000
  }'

const secretKey = "test_sk_yjroot_faketoss_default";
const authorization = "Basic " + Buffer.from(secretKey + ":").toString("base64");

const [payment, order] = await Promise.all([
  fetch("https://faketoss-alpha.yjroot.kr/v1/payments/confirm", {
    method: "POST",
    headers: {
      Authorization: authorization,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ paymentKey, orderId, amount }),
  }).then((res) => res.json()),
  fetch("https://faketoss-alpha.yjroot.kr/v1/payments/orders/" + orderId, {
    headers: { Authorization: authorization },
  }).then((res) => res.json()),
]);