자동 결제 시작하기
빌링키를 한 번 발급받아 구매자 인증 없이 반복 결제하는 자동 결제 연동 튜토리얼이에요.
이 튜토리얼은 구독, 멤버십처럼 반복 결제가 필요한 서비스를 위한 문서예요. 순서대로 따라 하면 빌링키 발급부터 사용자 인증, 자동 결제 승인, 빌링키 관리까지 완주할 수 있어요. 일반 결제 튜토리얼처럼 실제 출금이 일어나지 않는 테스트용 API Key로 진행해요.
자동 결제가 일반 결제와 다른 점
일반 결제는 결제할 때마다 구매자가 토스 앱에서 인증해요. 자동 결제는 최초 한 번만 인증해서 빌링키를 활성화하고, 그 뒤로는 가맹점 서버가 빌링키로 승인 API를 호출할 때마다 인증 없이 결제돼요. 승인 요청의 유효시간이나 횟수 제한이 없어서 월 구독 같은 반복 청구에 맞아요.
| 구분 | 일반 결제 | 자동 결제 |
|---|---|---|
| 구매자 인증 | 매 결제마다 | 최초 등록 시 한 번 |
| 결제 실행 | 인증 완료 후 승인 | 가맹점이 원하는 시점에 승인 API 호출 |
| 핵심 식별자 | payToken (결제 건 단위) | billingKey (사용자 결제수단 단위) |
| 결제 수단 | 토스머니, 카드 | 토스머니, 카드 |
전체 흐름은 다음 그림과 같아요. 빌링키 생성과 사용자 인증(1회)을 거쳐 활성화되면, 이후에는 승인 요청만 반복돼요.
빌링키의 상태
빌링키는 상태를 가지고, 튜토리얼의 매 단계가 이 상태를 중심으로 진행돼요. 생성하면 CREATE로 시작하고, 사용자가 인증을 완료하면 ACTIVE가 되어 결제에 쓸 수 있어요. 상태는 상태 조회 API로 언제든 확인할 수 있어요.
| status | 의미 | 다루는 단계 |
|---|---|---|
CREATE | 빌링키가 생성됐지만 아직 사용자가 인증하지 않은 상태예요. | 1. 빌링키 생성하기 |
ACTIVE | 활성화 완료. 승인 API로 결제할 수 있는 유일한 상태예요. | 3. 활성화 확인하기 |
REMOVE | 삭제된 상태예요. | 5. 빌링키 관리하기 |
CANCEL | 취소된 상태예요. | 5. 빌링키 관리하기 |
FAIL | 등록에 실패한 상태예요. | 3. 활성화 확인하기 |
미리 준비할 것
- API Key는 일반 결제와 같아요. 계약 전이라면 공용 테스트용 API Key(
sk_test_w5lNQylNqa5lNQe013Nq)로 따라 할 수 있어요. - 빌링키 생성 API를 호출하고 활성화 콜백을 받을 가맹점 서버가 필요해요. 콜백 URL은 외부에서 접근 가능해야 해요.
- 토스 앱이 설치된 휴대폰이 필요해요. 별도 테스트 계정이나 SDK 없이 본인 토스 앱으로 인증을 진행해요.
연동 단계
다섯 단계로 진행해요. 각 단계는 이전 단계의 결과를 이어받으니 순서대로 읽는 것을 추천해요.
1. 빌링키 생성하기
빌링키 생성 API를 호출하고 인증 URI를 받아요.
2. 사용자 인증 받기
OS별 인증 URI로 사용자를 보내 토스 앱에서 결제수단을 등록해요.
3. 활성화 확인하기
콜백과 상태 조회로 빌링키가 ACTIVE인지 확인해요.
4. 자동 결제 승인하기
활성화된 빌링키로 인증 없이 결제를 실행해요.
5. 빌링키 관리하기
상태 조회와 삭제, 삭제 콜백 대응까지 운영을 준비해요.
일반 결제를 아직 연동하지 않았다면 일반 결제 튜토리얼을 먼저 읽는 것을 추천해요. API Key 준비, 테스트 방법, 라이브 전환 등 공통 내용은 이 튜토리얼에서 반복하지 않아요.