시작하기
5. 빌링키 관리하기
구독 해지에 따른 빌링키 삭제와 삭제 콜백 대응까지 운영을 준비해요.
마지막 단계에서는 운영 중 필요한 빌링키 관리를 다뤄요. 사용자가 구독을 해지하면 빌링키를 삭제하고, 토스 쪽에서 삭제가 발생하는 경우에도 대응해야 해요.
빌링키 삭제하기
사용자가 구독을 해지하거나 탈퇴하면 빌링키를 삭제하세요. 삭제된 빌링키는 더 이상 자동 결제에 사용할 수 없어요.
curl https://pay.toss.im/api/v1/billing-key/remove \
-H "Content-Type: application/json" \
-d '{
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"billingKey": "example-billingKey"
}'응답의 code가 0이면 삭제 완료예요.
토스 쪽 삭제에 대응하기
토스 쪽에서 삭제가 발생하면 가맹점 콜백 URL로 action: "REMOVED" 콜백이 올 수 있어요. 이 콜백을 받으면 해당 사용자의 구독을 중지하고, 계속 이용하려면 재등록(1단계부터 다시)을 안내하세요.
승인 실패만으로 구독 상태를 판단하지 마세요. 콜백 유실 가능성도 있으니, 승인이 COMMON_BILLING_KEY_NOT_FOUND로
실패하면 상태 조회 API로 빌링키 상태를 확인해서 REMOVE, CANCEL이면 구독 중지 처리하는
방어 로직을 권장해요.
테스트와 라이브 전환
테스트 방법과 실거래용 API Key 전환은 일반 결제와 같아요. 6. 테스트와 라이브 전환하기를 참고하되, 자동 결제에서는 이 시나리오를 추가로 점검하세요.
- 빌링키 생성부터 인증, 활성화 콜백 수신, 승인까지 전체 흐름이 이어지는지 확인해요.
- 같은
orderNo로 중복 승인이 발생하지 않는지 확인해요. - 삭제 후 승인이 실패하는지,
REMOVED콜백 처리가 동작하는지 확인해요. - 승인 결제 건의 환불이 정상 동작하는지 확인해요.
더 알아보기
- 자동 결제 전체 API 명세는 자동 결제 API 레퍼런스를 참고하세요.
- 승인된 결제의 환불은 결제 환불하기를 참고하세요.
- API 오류 코드 목록은 에러 코드를 참고하세요.