3. 활성화 확인하기

이 단계에서는 빌링키가 결제에 쓸 수 있는 상태가 됐는지 확인해요. 사용자가 인증을 완료하면 토스가 1단계에서 전달한 resultCallback URL로 결과를 보내줘요.

활성화 콜백 받기

사용자가 등록을 성공적으로 마치면 토스 서버가 가맹점 콜백 URL로 POST 요청을 보내요. 핵심 필드는 다음과 같고, 카드 등록이면 카드 정보가, 토스머니면 계좌 정보가 함께 와요.

{
  "action": "ACTIVATED",
  "userId": "tutorial-user-001",
  "billingKey": "example-billingKey",
  "payMethod": "CARD"
}

• action이 ACTIVATED면 빌링키가 활성화된 거예요. 가맹점 DB에서 해당 userId의 구독 상태를 활성으로 바꾸면 돼요.
• 토스 쪽 사정으로 빌링키가 삭제되면 action: "REMOVED" 콜백이 올 수 있어요. 이 경우 구독을 중지하고 재등록을 안내해야 해요.

전체 페이로드는 빌링키 처리결과 callback 레퍼런스에서 확인할 수 있어요.

상태 조회로 확인하기

콜백을 받지 못했거나 현재 상태를 직접 확인하고 싶다면 상태 조회 API를 사용해요. userId로 조회해요.

curl https://pay.toss.im/api/v1/billing-key/status \
-H "Content-Type: application/json" \
-d '{
  "apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
  "userId": "tutorial-user-001"
}'

응답의 status로 빌링키의 현재 상태를 알 수 있어요.

{
  "code": 0,
  "userId": "tutorial-user-001",
  "billingKey": "example-billingKey",
  "status": "ACTIVE",
  "payMethod": "CARD"
}

status가 ACTIVE면 결제할 수 있는 상태예요. 인증이 아직 안 끝났다면 CREATE로, 등록에 실패했다면 FAIL로 응답돼요. 상태별 의미는 개요의 빌링키 상태 표를 참고하세요.

사용자가 토스 앱에서 결제수단을 바꾸면 payMethod가 업데이트될 수 있으니, 회원 관리 화면에 결제수단을 보여준다면 이 API로 최신 값을 확인하세요.

다음 단계

ACTIVE를 확인했다면 이제 인증 없이 결제할 수 있어요. 4. 자동 결제 승인하기로 이동하세요.