이 기능은 콘솔에 로그인한 상태에서만 됩니다. API 키로 부르면 거절됩니다.
토스페이먼츠 상점 준비
- 토스페이먼츠 개발자센터에 가입하면 전자결제 계약 전에도 테스트 상점 키를 확인할 수 있습니다. 테스트 환경 연동은 이 테스트 키로 시작합니다.
- 실결제로 자동결제를 쓰려면 토스페이먼츠의 추가 리스크 검토와 자동결제 계약이 필요합니다. 토스페이먼츠 정책상 자동결제는 정기 구독형 서비스에만 허용됩니다. 조건은 토스페이먼츠 자동결제 연동 가이드에서 확인하세요.
- 키는 개발자센터의 ‘API 키’ 메뉴에서 확인합니다. MeterEngine에는 자동결제(빌링) 상점(MID)의 API 개별 연동 키(클라이언트 키와 시크릿 키 한 쌍)를 넣습니다. 토스페이먼츠는 자동결제처럼 서비스마다 다른 상점에 API 개별 연동 키를 발급하니, 자동결제 상점을 골랐는지 확인하세요. 키 종류는 토스페이먼츠 API 키 문서에 있습니다.
업무 환경마다 받는 키
토스페이먼츠 키는 업무 환경마다 따로 저장합니다. 테스트 환경에 저장한 키는 실제 환경에서 쓰이지 않고, 그 반대도 같습니다. 환경마다 받는 키의 앞부분이 정해져 있습니다.- 테스트 환경
- 실제 환경
테스트 키로 한 결제는 실제로 결제되지 않으며 카드에서 금액이 빠져나가지 않습니다.
키 저장
1
도입사 설정 화면을 연다
콘솔 왼쪽 메뉴 ‘과금과 연동’에서 ‘도입사 설정’을 엽니다. 키를 저장하려면 admin(전체 관리) 권한이 있는 구성원으로 로그인해야 합니다.
2
토스 키 저장을 연다
‘토스페이먼츠 연동’ 구역에서 ‘토스 키 저장’을 누릅니다. 업무 환경이 테스트 환경이면 테스트 키를, 실제 환경이면 실결제 키를 저장하는 창이 열립니다.
3
클라이언트 키와 시크릿 키를 넣는다
개발자센터에서 복사한 키를 ‘클라이언트 키’와 ‘시크릿 키’에 넣고 저장합니다.
4
저장 결과를 확인한다
MeterEngine은 저장하기 전에 시크릿 키로 토스페이먼츠에 결제 조회를 한 번 보내 키가 유효한지 확인합니다. 이 확인은 결제를 만들지 않습니다. 저장되면 키 목록에 결제 모드, ‘관리 상태’, ‘시크릿 키 끝 네 글자’, ‘확인 시각’, ‘저장 시각’이 보입니다.
secret_key_last_four)만 나옵니다.
저장이 거절될 때
키를 바꾸거나 멈출 때
- 교체: ‘토스 키 저장’으로 새 키를 저장하면 이전 키를 덮어씁니다. 이전 키는 키 목록 위 ‘토스 키 관리 상태’에서 ‘보관됨’이나 ‘전체’를 고르면 볼 수 있습니다. 새로 만드는 카드 등록 링크는 새 키를 씁니다.
- 보관: 키 목록의 ‘토스 키 보관’을 누르면 그 환경의 새 결제와 카드 등록이 멈춥니다. 이미 진행 중인 결제의 결과 확인과 결제 취소에는 보관한 키를 계속 씁니다. 다시 쓰려면 키를 다시 저장합니다.
토스페이먼츠 웹훅 등록
토스페이먼츠 웹훅을 등록하면 결제 상태가 바뀔 때 토스페이먼츠가 MeterEngine에 바로 알려 줍니다. 등록하지 않아도 MeterEngine이 결과를 확인하지 못한 결제를 주기적으로 다시 조회하므로 결과는 들어오지만, 등록하면 더 빨리 반영됩니다.1
도입사 id를 확인한다
웹훅 주소에는 도입사 id(UUID)가 들어갑니다. read 권한 API 키로 응답에는 도입사의
GET /v1/organization을 부르면 응답의 id가 도입사 id입니다. 콘솔 주소창의 organization_id= 뒤 값도 같은 값입니다.id, name, status, created_at이 있습니다. 아래 예시에서는 도입사 id가 7c9e6679-7425-40de-944b-e07fc1f90ae7이라고 하겠습니다.2
웹훅 주소를 만든다
주소는 도입사 id는 업무 환경과 관계없이 하나이므로 테스트 결제와 실결제 모두 이 주소 하나로 받습니다.
https://meterengine.com/v1/toss-payments-webhooks/<도입사 id> 입니다. 위 예시라면 다음과 같습니다.3
토스페이먼츠 개발자센터에 등록한다
개발자센터의 웹훅 메뉴에서 ‘웹훅 등록하기’를 누르고, 이름과 위 주소를 넣은 뒤 이벤트로
PAYMENT_STATUS_CHANGED를 고릅니다. 토스페이먼츠 웹훅은 상점(MID)마다 따로 설정하므로 MeterEngine에 키를 넣은 상점마다 등록합니다. 메뉴 위치는 토스페이먼츠 웹훅 가이드에 있습니다.PAYMENT_STATUS_CHANGED일 때만 본문의 주문번호로 결제 시도를 찾고, 그 시도에 쓴 키로 토스페이먼츠에 결제를 다시 조회해 결과 확인 중인 결제와 취소에 반영합니다. 본문을 읽을 수 없거나, 다른 이벤트이거나, 반영할 결제 시도가 없으면 아무것도 바꾸지 않고 200으로 답합니다. 다시 조회한 결과를 확인하지 못하면 500으로 답해 토스페이먼츠가 다시 보내게 합니다.
이 주소는 토스페이먼츠가 부르는 주소입니다. 도입사 서버에서 직접 부르지 마세요. 도입사가 결제 결과를 받으려면 MeterEngine 통보를 등록합니다. 웹훅 받기 시작하기
다음 단계
테스트 결제와 실결제
테스트 환경에서 먼저 확인하고 실제 환경으로 옮기기
고객 카드 등록 링크
고객에게 카드를 등록받기