토스페이먼츠 자동결제: 빌링키 발급과 정기결제 처리

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

자동결제(빌링)는 구매자가 등록한 결제수단을 이용해 서비스 서버가 결제를 요청하는 방식입니다. 구독의 결제일에 맞춰 빌링키로 승인을 요청하며, 결제 일정과 구독 상태는 서비스가 관리합니다. 오늘은 토스페이먼츠 카드 자동결제의 발급·승인·실패 처리 흐름을 알아보겠습니다.

토스페이먼츠 자동결제는 일반결제와 무엇이 다른가요?

멤버십, SaaS, 정기배송처럼 매달 결제가 일어나는 서비스는 구매자에게 매번 카드를 다시 입력하게 할 수 없습니다. 이럴 때 쓰는 기능이 토스페이먼츠 자동결제, 흔히 빌링이라 부르는 방식입니다.

결제위젯과 결제창 비교, 일반결제 승인 흐름은 저희가 앞서 쓴 '토스페이먼츠 연동 방법 총정리'에서 다뤘습니다. 이번에는 구매자가 화면 앞에 없을 때 일어나는 정기결제 연동만 살펴봅니다.

정기결제 연동 흐름은 세 번의 호출로 이어집니다

첫 호출은 카드 등록창을 여는 일입니다.

브라우저에서 SDK의 requestBillingAuth()를 호출하면 카드 등록창이 뜹니다. 구매자가 카드 정보를 넣고 본인인증을 마치면 successUrl의 쿼리 파라미터로 customerKey와 authKey가 돌아옵니다.

두 번째로 서버가 authKey를 빌링키로 바꿉니다.

authKey는 일회성 인증 키입니다. 서버는 시크릿 키로 인증 헤더를 만들고 POST /v1/billing/authorizations/issue에 authKey와 customerKey를 보내 빌링키를 발급받습니다.

세 번째 호출은 결제일마다 반복됩니다.

서버가 POST /v1/billing/{billingKey}에 금액과 주문 정보를 담아 승인을 요청합니다. 토스페이먼츠 자동결제에는 스케줄링 기능이 없으니 언제 호출할지는 서비스의 배치 작업이 결정합니다.

// 결제일 배치에서 호출 (요약)
await fetch(`https://api.tosspayments.com/v1/billing/${billingKey}`, {
  method: "POST",
  headers: { Authorization: `Basic ${encoded}`, "Content-Type": "application/json" },
  body: JSON.stringify({ customerKey, amount: 9900, orderId, orderName: "월간 멤버십" }),
});

customerKey와 빌링키는 어떻게 설계하고 보관할까

customerKey는 남이 추측할 수 없는 값이어야 합니다.

토스페이먼츠 API 레퍼런스는 순차 숫자, 이메일, 전화번호, 사용자 아이디 같은 값을 피하고 UUID 같은 무작위 값을 쓰라고 안내합니다. 회원 기본 키 대신 별도 컬럼에 무작위 값을 두는 편이 안전합니다.

빌링키는 다시 조회할 수 없다는 전제로 저장합니다.

발급된 빌링키를 조회하는 API가 없습니다. 잃어버리면 구매자에게 카드 정보를 다시 받아야 합니다. 보관은 customerKey와 짝지어 서버 DB에 암호화해 둡니다. 시크릿 키와 마찬가지로 클라이언트 코드에는 노출하지 않습니다.

결제 실패와 카드 만료는 누가 처리하나요?

실패 처리도 서비스 쪽 일입니다.

잔고 부족이나 한도 초과는 승인을 요청해 봐야 알 수 있습니다. 며칠 간격으로 몇 번 다시 시도할지, 언제 구독을 멈출지도 토스페이먼츠가 대신 정해 주지 않으니 기획 단계에서 잡아 둬야 합니다.

재시도에는 멱등키를 붙입니다.

자동결제 승인은 최대 60초가 걸릴 수 있으니 타임아웃은 60초 이상으로 잡습니다. 응답을 못 받은 채 다시 호출하면 이중 결제가 날 수 있습니다. 같은 논리적 결제 요청을 재시도할 때 동일한 Idempotency-Key를 사용하면 중복 처리를 방지할 수 있습니다. 매달 새로 청구하는 결제는 별도 주문과 키로 구분합니다. 멱등키 유효기간은 15일입니다.

카드가 만료되면 빌링키를 새로 발급받습니다.

카드를 재발급받았거나 유효기간이 지났을 때 따로 갱신하는 절차는 없습니다. 그래서 결제 실패 알림에 카드 재등록 링크를 함께 넣어 둡니다.

토스페이먼츠 자동결제, 별도 계약과 심사가 필요할까

토스페이먼츠 개발자 문서는 자동결제를 리스크 검토와 추가 계약 후에 쓸 수 있다고 안내합니다. 정기 구독형 서비스가 아니면 사용이 제한됩니다. 계약 없는 클라이언트 키로 호출하면 NOT_SUPPORTED_METHOD 에러가 납니다. 네이버페이·토스페이 자동결제는 별도 심사가 필요하고 카카오페이 등 다른 국내 간편결제는 지원하지 않습니다.

세부 항목과 최신 적용 조건은 토스페이먼츠 자동결제 가이드를 참고해 보세요.

매달 이어지는 결제, 운영까지 함께 준비해요

결제 흐름을 하나씩 붙이다 보면 화면뿐 아니라 데이터와 운영 방식도 함께 살펴보게 됩니다. 지금 서비스에 필요한 범위부터 차근차근 정리해볼 수 있습니다.

똑똑한개발자는 UX/UI 디자인과 웹·앱 개발을 함께 진행합니다. 사용자가 이용하는 화면과 운영에 필요한 기능을 연결해 서비스를 만들어가는 과정을 돕습니다.

결제 흐름을 준비하면서 궁금한 점이 있다면 아래 똑똑한개발자 링크로 편하게 이야기 남겨주세요. 함께 살펴보겠습니다. 감사합니다. :)