Skip to content

Toss Payments

웹사이트에서 상품을 팔려면 결제가 필요하고, 결제는 우리가 직접 만들기엔 너무 무거운 일이에요. 카드 검증, 보안, 정산 같은 걸 처음부터 짜기보다 결제 대행사(PG)가 제공하는 문을 여는 편이 현실적이죠. Toss Payments는 토스페이먼츠가 제공하는 결제 연동 API예요. 카드·간편결제 등 다양한 결제 수단을 코드 몇 줄로 붙일 수 있어서 기본 결제 채널로 씁니다. 현재 🔵 적용 상태예요.

한눈에 보면 이렇게 흐름이 이어져요. 상품 선택 → 결제 수단(Toss) → 결제 완료 → Webhook → 구독 활성화/후속 처리예요. 결제가 완료되는 순간보다, 그 신호를 우리 서버가 받아 처리하는 부분이 실제로는 핵심이에요.

핵심 개념

  • 결제 방식의 구분 — 카드 결제처럼 즉시 끝나는 일반 결제와, 매달 반복되는 정기결제, 대금을 제3자에 맡겼다가 넘기는 에스크로가 용도에 따라 나뉘어요. 상품 형태에 맞춰 선택합니다.
  • 결제 연동 API — 토스페이먼츠가 대신 결제 처리·정산을 맡아주고, 우리 앱은 그 API에 결제 요청을 붙이는 구조예요. 결제 수단·심사·보안을 직접 구현하지 않고 거쳐갈 수 있어요.
  • 다양한 결제 수단 — 카드 결제는 물론 간편결제·계좌이체·가상계좌 등 여러 수단을 지원합니다. '어떤 수단을 보여줄지'를 선택해서 붙일 수 있어요.
  • 결제 Webhook — 결제가 성공·실패했을 때 PG가 우리 서버로 상태를 알려주는 콜백이에요. 결제만 일어나고 끝이 아니라, 성공 신호를 받아야만 구독 활성화 같은 후속 처리가 일어나죠.
  • 정기결제 — 매달 일정 금액을 자동으로 청구하는 구독 결제를 지원해요. 요금제 상품의 근간이 되는 부분이에요.
  • 결제의 신뢰 — 고액·신뢰가 중요한 거래에서는 대금을 제3자에 맡겼다가 완료 후 넘기는 에스크로 방식도 결합해 쓸 수 있어요.

사용 사례 / 실제 적용

대표 흐름은 Notion → 웹빌더 → 커스텀 도메인 → 결제의 마지막 단계예요. 방문자가 웹사이트에서 상품을 사면, Toss 결제 페이지로 이어져 결제를 완료하고, 결제 웹훅이 성공 신호를 우리 서버에 보내면 구독이 열립니다. 요금제 상품은 정기결제로, 신뢰가 중요하거나 고액인 거래는 에스크로를 검토하죠. 이어지는 흐름은 외부 연동 허브와 Notion API에서 이어져요.

결제 연동에서 가장 신경 쓸 부분은 웹훅의 신뢰성과 중복 처리예요. 결제 웹훅이 두 번 오거나, 네트워크가 끊겨 신호를 놓치면 구독이 잘못 열리거나 닫힐 수 있어요. 그래서 '한 번만 처리하는 멱등성'과 '놓친 이벤트를 재확인하는 재검증 흐름'을 결제 연동과 함께 설계하는 게 중요해요. 지금은 Toss가 적용 단계지만, 사업이 확장되면 KG이니시스·Stripe 같은 대안도 역량으로 갖춰두고 있어요(외부 연동 허브 참고). 운영할 때는 이 점도 기억하면 좋아요.

  • 서명 검증 — 웹훅이 정말 PG에서 온 것인지 서명을 확인해, 위조된 요청이 후속 처리를 일으키지 않게 해요.
  • 상태 조회로 보정 — 웹훅을 놓쳤을 때 대비해, 주기적으로 PG에 결제 상태를 조회해서 맞지 않으면 보정하는 흐름을 둬요.
  • 후속 처리의 멱등성 — 같은 결제 성공 신호를 두 번 받아도 구독이 두 번 열리지 않도록, 처리 키로 중복을 막아요.
  • 주문 데이터 저장 — 결제 요청·성공 내역을 우리 쪽에도 기록해, 고객 문의·정산 대조에 대비해요.
  • 테스트 환경 — 실제 결제가 아닌 테스트 모드로 연동을 검증하면 운영과 별개로 안전하게 확인할 수 있어요.
  • 취소·환불 처리 — 결제만큼 취소·환불 흐름도 연동의 일부예요. 상태가 뒤섞이지 않게 명확히 설계해요.
  • 정산 대조 — 주기적으로 결제·정산 내역을 맞춰보는 흐름을 두어 금액이 어긋나지 않는지 확인해요.
  • PG 의존 줄이기 — 결제 관련 호출을 인터페이스로 감싸 두면, PG를 바꿔도 결제 로직 전체를 고치지 않아요.

심화 챕터

결제 연동의 두 축은 아래 챕터에서 공식 문서를 기준으로 다뤄요.

더 알아보기