토스페이먼츠 완전 가이드: 1인 개발자를 위한 국내 최고 DX PG사

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

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

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

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

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

토스페이먼츠가 뭔가

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

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

기존 PG사들이 레거시 API + 복잡한 서류 절차 + 느린 정산으로 개발자들에게 악명이 높았다면, 토스페이먼츠는 처음부터 개발자 경험(DX)을 핵심 경쟁력으로 잡고 설계했다.

---

1인 개발자에게 왜 좋은가

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

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

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

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

2. 정산이 빠르다 돈을 받고 실제로 내 통장에 들어오기까지의 시간이 D+2~5일이다. 기존 레거시 PG사들이 D+7을 기본으로 잡는 것과 비교하면 최대 5일 빠르다. 부트스트랩 파운더에게는 현금흐름이 생명이라 이 차이가 크다.

3. 문서가 실제로 잘 되어 있다 docs.tosspayments.com에 들어가면 코드 예제가 JavaScript, TypeScript, Java, Python, PHP, Ruby 전부 있고, 복사해서 바로 쓸 수 있는 수준이다. "연동 가이드 → 실제 동작하는 코드"까지의 거리가 업계에서 가장 짧다.

---

핵심 기능 4가지

1. 결제창 (Payment Widget)

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

SDK v2.6 기준으로 npm 주간 다운로드 30K를 넘긴다. React, Next.js, Vue 환경 모두 지원하고, 설치부터 첫 결제 테스트까지 실제로 5분이면 된다.

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. 가상계좌

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

건당 300원 수수료로 고정이다. 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. 결제 대시보드 & 정산 관리

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

정산은 D+2~5일로 자동 처리된다. 별도 신청 없이 등록한 계좌로 자동 입금된다. 환불도 대시보드에서 버튼 하나로 처리 가능하다.

---

요금 체계

결제 수단	수수료
신용카드 (영세 사업자)	0.8%
신용카드 (중소 사업자)	1.3% ~ 1.9%
신용카드 (일반)	2.8%
계좌이체	1.8%
가상계좌	건당 300원
간편결제 (카카오페이, 네이버페이 등)	수단별 상이

영세/중소 사업자 기준은 연 매출에 따라 정부가 구분한다. 처음 시작하는 1인 개발자라면 대부분 영세 기준(0.8%)이 적용된다.

---

시작하기

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, 샌드박스 모두 개발자 친화적으로 설계. 처음 연동하는 사람도 반나절이면 된다
• 정산 최단: D+2~5일. 부트스트랩 파운더에게 현금흐름이 빠른 건 실질적인 이득이다
• MCP 서버 공식 지원: AI 코딩 환경에서 결제 API를 다루는 유일한 PG사
• 가입 간편: 온라인 가입, 빠른 심사, 복잡한 서류 없음

단점

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

---

한국 PG 한눈에 비교

항목	토스페이먼츠	포트원	페이플	PAYAPP
성격	PG 직영	PG 통합 미들웨어	스타트업 특화 PG	비사업자 결제
카드 수수료(영세)	0.8%	PG사별 (1.6~1.7%)	1.0%	1.9%
정산 주기	D+2~5일	PG사 따름	D+5 (D+1 멤버십)	D+5 (D+1 추가비)
사업자 필수	필수	PG 계약 시 필수	필수	필수 (라이트 종료)
정기결제	추가 계약	V2 API	카드+계좌+해외	가능
DX	최고 (MCP 서버)	V2 REST API	docs.payple.kr	부족
추천	빠른 정산+DX	멀티 PG 전략	구독 SaaS	사업자 전용

언제 무엇을 선택할까

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

---

결론

국내 결제를 붙여야 하는 1인 개발자에게 토스페이먼츠는 현재 가장 합리적인 첫 선택지다.

사업자등록 2분, 가입 당일 테스트 시작, D+2~5일 정산, MCP 서버까지. 결제 연동이라는 귀찮은 작업을 최대한 빠르게 끝낼 수 있도록 설계되어 있다.

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

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

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

---

함께 읽으면 좋은 글

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