이 문서는 PASSV 이용권(memberships) 결제에 쓰는 토스페이먼츠 라이브(실연동) 키를 발급받아 운영 변수에 반영하는 절차를 정리한다.
토스페이먼츠는 로그인만 한다고 라이브 키가 바로 나오지 않는다. 가맹점 계약 심사가 완료돼야 라이브 키가 열린다. 테스트 키는 로그인 직후부터 쓸 수 있고, 라이브 키는 심사 승인 후 상점관리자에서 모드를 전환해야 보인다.
이 문서에서 끝내야 하는 일은 아래 4가지다.
| 항목 | 값 |
|---|---|
| 상점관리자 | https://dashboard.tosspayments.com |
| API 호출 기준 URL | https://api.tosspayments.com/v1 (테스트·라이브 공통) |
| 백엔드 변수 1 | TOSS_CLIENT_KEY |
| 백엔드 변수 2 | TOSS_SECRET_KEY |
| 백엔드 변수 3 | TOSS_WEBHOOK_SECRET |
| 테스트 키 접두어 | 클라이언트 test_ck_... / 시크릿 test_sk_... |
| 라이브 키 접두어 | 클라이언트 live_ck_... / 시크릿 live_sk_... |
| PASSV 결제 연동 방식 | 빌링키(자동결제) 기반 이용권 정기결제 |
중요한 점은 아래 4개다.
test_ / live_)다. 그래서 URL이 아니라 키를 라이브로 바꾸는 것이 핵심이다.UNAUTHORIZED_KEY 계열) 오류가 난다. 클라이언트·시크릿 키는 같은 환경끼리 맞춰서 넣는다.https://dashboard.tosspayments.com에 로그인한다.테스트인지 라이브(실연동)인지 확인한다.test_ 접두어 키만 보인다.심사 중이면 라이브 키는 잠겨 있다.완료/승인 상태여야 라이브 모드 전환이 가능하다.가맹점 신청/계약하기) 메뉴로 이동한다.- 사업자등록증
- 정산 받을 대표 계좌(통장 사본)
- 서비스 URL / 앱 정보, 판매 상품·서비스 소개
- 대표자/담당자 정보
- (업종에 따라) 통신판매업 신고증 등
심사 중에서 완료/승인으로 바뀌었는지 확인한다.라이브(실연동)로 전환한다.개발자센터 또는 API 키 메뉴로 이동한다.클라이언트 키: live_ck_...
시크릿 키: live_sk_...
TOSS_WEBHOOK_SECRET으로 토스 웹훅 서명을 검증한다.401로 거부되고, 미설정이면 통과시키되 경고를 남긴다(현재 백엔드 동작 기준).상점관리자에서 확인한 라이브 값을 아래처럼 넣는다.
| 위치 | 변수명 | 넣는 값 |
|---|---|---|
| 백엔드 운영 변수 | TOSS_CLIENT_KEY |
라이브 클라이언트 키 live_ck_... |
| 백엔드 운영 변수 | TOSS_SECRET_KEY |
라이브 시크릿 키 live_sk_... |
| 백엔드 운영 변수 | TOSS_WEBHOOK_SECRET |
토스 웹훅 서명 검증 시크릿 |
| 구분 | 파일 | 의미 |
|---|---|---|
| 변수 정의 | services/sens-api/config.py |
TOSS_CLIENT_KEY, TOSS_SECRET_KEY, TOSS_WEBHOOK_SECRET 선언 |
| 예시 변수 | services/sens-api/.env.example |
TOSS_CLIENT_KEY, TOSS_SECRET_KEY 자리 |
| 결제 클라이언트 | services/sens-api/contexts/payments/application/services.py |
TossPaymentsService(기준 URL https://api.tosspayments.com/v1, 시크릿 키로 Basic 인증) |
| 이용권 정기결제 | services/sens-api/contexts/memberships/application/services.py |
빌링키 발급·정기결제 처리 |
test_/live_)와 클라이언트·시크릿 키의 환경 일치를 먼저 확인한다.TOSS_WEBHOOK_SECRET 값을 확인한다.완료/승인으로 바뀐 것을 확인했다.live_ck_..., live_sk_...를 확인했다.TOSS_CLIENT_KEY에 라이브 클라이언트 키를 넣었다.TOSS_SECRET_KEY에 라이브 시크릿 키를 넣었다(백엔드 전용).TOSS_WEBHOOK_SECRET에 웹훅 시크릿을 넣었다.Manual 08. 결제 연동 설정
상위: 08. 결제 연동 설정 · 관련: Infisical 시크릿 반영과 권한 변경 절차