콘텐츠로 이동

Toss Payments 결제 흐름 (빌링)

개요

구독형 서비스는 매달 같은 고객에게 같은 금액을 청구해야 해요. 그런데 결제마다 카드를 다시 입력하게 하면 이탈이 커지죠. 토스페이먼츠의 자동결제(빌링/Billing) 는 카드를 한 번 등록해 두면, 이후에는 별도 인증 없이 결제를 요청할 수 있는 정기결제 방식이에요. 공식 문서는 자동결제를 정기 구독형 서비스에만 쓸 수 있고, 비정기 결제엔 정책적으로 제한된다고 명확히 해요. 이 페이지는 공식 문서 기준으로 빌링키 발급부터 정기 결제 실행까지의 흐름을 풀어요.

핵심 개념

자동결제의 큰 흐름

토스 공식 문서는 자동결제 연동을 세 단계로 정리해요.

  1. 카드 등록창 호출 (Client) — SDK로 카드 등록창을 띄워 구매자의 카드 정보를 인증·등록.
  2. 빌링키 발급 API 요청 (Server) — 발급받은 빌링키(billingKey) 를 DB에 저장.
  3. 빌링 결제 승인 요청 (Server) — 저장한 빌링키로 원하는 주기·시점에 자동결제 실행.

중요한 점은 스케줄링 기능은 직접 구현해야 한다는 거예요. 토스페이먼츠는 자체 스케줄링을 제공하지 않아요. 우리 쪽에서 node-cron 같은 도구로 "매월 1일에 결제 요청"을 만들어야 해요.

1. 카드 등록

requestBillingAuth('카드', ...) 메서드로 카드 등록창을 띄워요. 여기서 customerKey(상점이 만든 구매자 고유 ID)가 필수이고, successUrl·failUrl(성공·실패 시 이동 페이지)을 지정해요. 카드 인증·본인인증이 끝나면 successUrl로 이동하는데, URL에 authKey(빌링키 발급용 1회성 인증 키)와 customerKey가 쿼리 파라미터로 담겨 와요.

2. 빌링키 발급

authKey를 이용해 빌링키 발급 API를 호출해요. 이때 인증 헤더는 시크릿 키 뒤에 :을 붙여 base64로 인코딩한 값을 Basic 인증으로 써요. 요청 본문에 authKey와 customerKey를 보내고, HTTP 200 OK를 받으면 응답의 billingKey 가 발급돼요. 이 빌링키를 customerKey와 매핑해 서버에 저장해요.

빌링키는 한 번 발급되면 다시 조회할 수 없고, 유효기간은 연결된 카드 유효기간과 같아요. 노출되어도 매핑된 customerKey를 모르면 결제가 불가능해요.

3. 자동결제 승인

발급한 billingKey를 자동결제 승인 API의 경로 파라미터로 넣고, 요청 본문에 주문 정보와 customerKey를 담아 호출해요. 성공하면 200 OK와 함께 Payment 객체가 돌아와요. 자동결제는 card 필드가 포함돼 있어요.

테스트 환경

테스트 모드에선 본인인증 문자가 발송되지 않아, 인증번호로 000000을 입력하고, 카드 번호의 앞 6자리(BIN)만 유효해도 등록돼요. 라이브에선 전체 카드 번호가 유효해야 해요. 현재 자동결제는 국내 발급 카드만 지원하고, 해외 카드·해외 결제는 지원하지 않아요.

실제 적용 (데이터스케쳐스)

웹사이트에서 구독형 요금제를 판다면 Toss 자동결제가 적합해요. 흐름은 이렇게 이어져요 — 방문자가 상품을 골라 카드를 등록하면(requestBillingAuth), 우리 서버가 authKey로 빌링키를 발급해 customerKey와 함께 저장하고, 이후 매월 정해진 시각에 그 빌링키로 결제 승인을 호출해요.

이 연동에서 가장 신경 쓸 부분은 스케줄링을 직접 구현해야 한다는 점과, 빌링키를 안전하게 저장하는 거예요. 빌링키는 재조회가 안 되고 비밀에 가깝다 보니, 사용자(고객)와의 매핑과 암호화 저장을 제대로 해야 정기결제가 안정적으로 돌아가요. 결제 성공·실패를 실시간으로 받는 방법은 결제 웹훅, 전체 결제 흐름은 Toss Payments에서 이어져요.

더 알아보기