토스페이먼츠 완전 가이드: 1인 개발자를 위한 국내 결제 연동의 유력한 선택지

국내에서 결제를 붙여야 하는 순간이 온다.

랜딩페이지를 만들었고, 유저가 들어오기 시작했고, "얼마에요?"라는 DM이 처음으로 날아왔다.

이때 대부분의 1인 개발자가 겪는 일이 있다.

PG사 사이트를 열면 "영업팀 문의"가 먼저 나오고, 가입 신청서는 팩스 서류 느낌이고, 테스트 환경 세팅하다가 반나절이 날아간다.

토스페이먼츠는 그 경험을 완전히 다르게 만들었다.

토스페이먼츠가 뭔가

토스페이먼츠는 토스(비바리퍼블리카) 계열의 직영 PG(Payment Gateway)사다.

2021년에 독립 법인으로 출범해서, 지금은 국내 PG 시장에서 KG이니시스, NHN KCP와 함께 주요 3사 중 하나로 자리잡았다. 카카오페이, 네이버페이, 삼성페이, 신용카드, 계좌이체, 가상계좌까지 한 번의 계약으로 전부 커버된다.

기존 PG사들이 레거시 API + 복잡한 서류 절차 + 느린 정산으로 개발자들에게 악명이 높았다면, 토스페이먼츠는 상대적으로 개발자 경험(DX)을 강하게 밀어온 편이다.

---

1인 개발자에게 왜 좋은가

결제 연동은 사실 귀찮은 작업이다.

유저가 실제로 돈을 내는 순간을 처리하는 코드라 실수 허용 범위가 제로에 가깝고, 테스트도 꼼꼼하게 해야 하고, 문서가 불친절하면 반나절이 날아간다.

토스페이먼츠가 1인 개발자에게 맞는 이유 세 가지:

1. 샌드박스 가입이 필요 없다 대부분의 PG사는 테스트 환경(샌드박스)에 별도 신청 → 승인 → 키 발급 프로세스가 있다. 토스페이먼츠는 그냥 계정 만들면 테스트 키가 바로 생긴다. 오늘 계정 만들고 오늘 결제 플로우 테스트 가능하다.

2. 공개 fee page 기준 정산이 빠른 편이다 공식 fee page는 평균 정산이 5일 이내라고 안내한다. 계약 조건과 결제수단에 따라 실제 정산 주기는 달라질 수 있지만, 문서와 파트너센터 흐름이 비교적 명확한 편이다.

3. 문서가 실제로 잘 되어 있다 docs.tosspayments.com에 들어가면 코드 예제가 JavaScript, TypeScript, Java, Python, PHP, Ruby로 정리돼 있다. "연동 가이드 → 실제 동작하는 코드"까지의 거리가 짧은 편이다.

4. MCP/LLM 연동을 공식적으로 밀고 있다 공식 개발자센터에는 LLMs로 결제 연동하기 가이드가 있고, Cursor, Windsurf, Claude Desktop 같은 도구를 활용한 연동 흐름을 직접 안내한다. 또 토스페이먼츠 공식 블로그는 2025년 6월 PG 업계 최초 AI 연동 MCP 서버 도입을 발표했다.

---

핵심 기능 4가지

1. 결제창 (Payment Widget)

토스페이먼츠의 핵심 제품이다. 카드, 계좌이체, 가상계좌, 간편결제(토스, 카카오페이, 네이버페이, 삼성페이) 전부를 하나의 위젯으로 처리한다.

React, Next.js, Vue 환경 모두 지원하고, 설치부터 첫 결제 테스트까지 빠르게 시작할 수 있다.

npm install @tosspayments/tosspayments-sdk

import { loadTossPayments } from "@tosspayments/tosspayments-sdk";

const tossPayments = await loadTossPayments("test_ck_...");
const payment = tossPayments.payment({ customerKey: "user-uuid" });

await payment.requestPayment({
  method: "CARD",
  amount: { currency: "KRW", value: 9900 },
  orderId: "order-uuid",
  orderName: "월정액 구독",
  successUrl: `${window.location.origin}/payment/success`,
  failUrl: `${window.location.origin}/payment/fail`,
});

결제 완료 후 successUrl로 리다이렉트되면 서버에서 paymentKey로 승인 API를 호출해서 결제를 확정한다. 이 2단계 플로우(요청 → 승인)가 보안의 핵심이다.

2. 빌링(정기결제)

구독 서비스를 만든다면 빌링키 기반 정기결제가 필요하다.

유저가 첫 결제 시 카드를 등록하면 빌링키가 발급되고, 이후에는 서버에서 빌링키만 있으면 유저 개입 없이 자동으로 결제할 수 있다. SaaS, 구독 콘텐츠, 멤버십 서비스에 필수다.

단, 빌링 기능은 별도 계약과 리스크 심사가 필요하다. 심사 절차가 부담스럽다면 정기결제에 특화된 페이플도 고려해볼 수 있다. 사업자등록 후 토스페이먼츠 파트너센터에서 신청하면 심사 후 활성화된다. 처음 신청할 때 서비스 설명, 평균 결제금액, 월 예상 거래량 같은 정보를 제출해야 한다.

3. 가상계좌

카드가 없거나 계좌이체를 선호하는 유저를 위한 결제 방식이다. 유저에게 일회용 가상 계좌번호를 발급하고, 입금이 확인되면 웹훅으로 서버에 알려준다.

공개 fee page 기준 건당 400원이다. B2B 서비스나 고가 상품을 판매할 때 유용하다.

// 가상계좌 결제 요청
await payment.requestPayment({
  method: "VIRTUAL_ACCOUNT",
  amount: { currency: "KRW", value: 99000 },
  orderId: "order-uuid",
  orderName: "연간 플랜",
  validHours: 24, // 24시간 내 입금
  bank: "우리", // 특정 은행 지정 가능
});

입금 완료 시 설정한 웹훅 URL로 virtualAccount.status === "DONE" 이벤트가 날아온다.

4. 결제 대시보드 & 정산 관리

토스페이먼츠 파트너센터에서 실시간 거래 현황, 일별/월별 매출, 정산 내역, 환불 처리를 전부 관리할 수 있다.

정산은 공식 fee page 기준 평균 5일 이내로 안내된다. 실제 정산 조건은 계약 형태와 결제수단에 따라 달라질 수 있다.

---

요금 체계

결제 수단	수수료
신용∙체크카드 (공개 fee page 기준 일반)	3.4%
가상계좌	건당 400원
간편결제	수단별/계약별 상이
가입비	220,000원부터 (최초 1회)
연관리비	110,000원부터 (연 1회)

영세/중소 우대수수료는 정책과 가맹점 구간에 따라 달라진다. 공개 fee page에 나온 일반 수수료와 실제 계약 수수료가 다를 수 있으니, 운영 전에는 반드시 최신 계약 조건을 확인해야 한다.

---

시작하기

1단계: 사업자등록

토스페이먼츠는 사업자등록이 필수다. 개인도 가능하고, 토스 공식 사이트에서 사업자등록 신청을 도와주는 페이지를 운영한다. 홈택스로 직접 하면 약 2분이면 처리된다.

개인사업자로 등록하면 충분하다. 법인은 나중에 필요해질 때 전환해도 된다.

2단계: 토스페이먼츠 가입

tosspayments.com에서 사업자 정보로 가입한다. 심사 완료 후(보통 1 영업일) 파트너센터에 접근할 수 있다.

3단계: API 키 발급

파트너센터 → 개발 → API 키에서 테스트 키와 라이브 키를 확인한다. 테스트 키는 가입 즉시 사용 가능하다.

테스트 키(test_ck_...)로 모든 플로우를 검증하고, 라이브 준비가 되면 라이브 키(live_ck_...)로 교체한다.

4단계: SDK 설치 & 연동

위에서 본 SDK 코드를 붙이고, 결제 승인 API까지 서버에 구현하면 끝이다.

// 결제 승인 (서버)
const response = await fetch("https://api.tosspayments.com/v1/payments/confirm", {
  method: "POST",
  headers: {
    Authorization: `Basic ${Buffer.from(`${secretKey}:`).toString("base64")}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ paymentKey, orderId, amount }),
});

---

장단점 정리

장점

• DX 강점: 문서, SDK, 테스트 흐름이 비교적 개발자 친화적이다
• 정산이 빠른 편: 공개 fee page 기준 평균 5일 이내. 현금흐름이 민감한 팀에 유리하다
• 공식 문서 품질: 결제창/가상계좌/빌링 가이드가 분리돼 있어 처음 붙이기 수월하다
• 공식 MCP/LLM 가이드 존재: AI 도구와 함께 연동하는 흐름을 공식 문서와 블로그에서 직접 밀고 있다
• 가입 간편: 온라인 가입, 빠른 심사, 복잡한 서류 없음

단점

• 사업자 필수: 개인으로는 가입 불가. 사업자등록 선행 필요. 사업자 없이 디지털 콘텐츠를 판매하고 싶다면 그로블이 대안이 될 수 있다
• 빌링 추가 계약: 구독/정기결제는 별도 심사가 필요해서 출시 일정에 변수가 생긴다
• 단일 PG 종속: 국내 결제만 처리한다. 여러 PG사를 하나의 SDK로 통합하고 싶다면 포트원을 통해 멀티 PG 구성도 가능하다. 해외 유저를 받으려면 Stripe 같은 별도 도구가 필요하다
• 간편결제 수수료 불투명: 카카오페이, 네이버페이 수수료는 별도 협의 구조

---

한국 PG 한눈에 비교

항목	토스페이먼츠	포트원	페이플	PAYAPP
성격	PG 직영	PG 통합 미들웨어	스타트업 특화 PG	비사업자 결제
카드 수수료(공개 기본)	3.4%	PG사별	계약형	1.9%
정산 주기	공식 fee page 기준 평균 5일 이내	PG사 따름	D+1 멤버십 존재	D+5 기본
사업자 필수	필수	PG 계약 시 필수	필수	필수 (라이트 종료)
정기결제	추가 계약	V2 API	카드+계좌+해외	가능
DX	강한 편 + 공식 MCP/LLM 가이드	V2 REST API	docs.payple.kr	제한적
추천	빠른 정산+DX	멀티 PG 전략	구독 SaaS	사업자 전용

언제 무엇을 선택할까

• DX와 빠른 정산이 최우선 → 토스페이먼츠
• 여러 PG를 하나로 관리 → 포트원
• 카드+계좌 정기결제 → 페이플
• 사업자 없이 디지털 콘텐츠 판매 → 그로블 (PAYAPP 라이트 종료)

---

결론

국내 결제를 붙여야 하는 1인 개발자에게 토스페이먼츠는 여전히 유력한 첫 선택지다.

테스트 키로 빠르게 시작할 수 있고, billing 문서도 비교적 명확하다. 결제 연동이라는 귀찮은 작업을 상대적으로 덜 비틀리게 끝낼 수 있도록 설계되어 있다.

빌링 심사가 별도로 필요한 구독 서비스라면 출시 일정을 잡을 때 1~3 영업일의 여유를 두면 된다. 일반 결제는 가입 당일부터 바로 라이브로 올릴 수 있다.

해외 유저가 있거나 글로벌 시장을 타겟으로 한다면 토스페이먼츠만으로는 부족하다. 그 경우에는 Paddle이나 Lemon Squeezy를 함께 검토하는 게 맞다.

하지만 한국 유저를 대상으로 하는 서비스라면, 토스페이먼츠 하나면 결제 인프라의 99%는 해결된다.

---

함께 읽으면 좋은 글

• 포트원 완전 가이드 — 토스페이먼츠, KG이니시스 등 여러 PG사를 하나의 SDK로 통합 관리하고 싶을 때
• 페이플 완전 가이드 — 정기결제·구독 서비스에 특화된 PG사, 빌링 심사 부담 없이 시작하고 싶을 때
• PAYAPP 가이드 — 비사업자 결제(페이앱 라이트) 서비스 종료 경위와 현재 대안 정리