메인 콘텐츠로 건너뛰기
이 기능은 콘솔에 로그인한 상태에서만 됩니다. API 키로 부르면 거절됩니다.
MeterEngine은 도입사의 토스페이먼츠 상점 키로 고객 카드를 등록하고 결제합니다. 결제 대금은 도입사의 토스페이먼츠 상점으로 들어갑니다. 이 페이지는 키를 준비해 저장하고, 토스페이먼츠가 결제 상태 변경을 MeterEngine에 알리도록 웹훅을 등록하는 순서를 다룹니다.

토스페이먼츠 상점 준비

  • 토스페이먼츠 개발자센터에 가입하면 전자결제 계약 전에도 테스트 상점 키를 확인할 수 있습니다. 테스트 환경 연동은 이 테스트 키로 시작합니다.
  • 실결제로 자동결제를 쓰려면 토스페이먼츠의 추가 리스크 검토와 자동결제 계약이 필요합니다. 토스페이먼츠 정책상 자동결제는 정기 구독형 서비스에만 허용됩니다. 조건은 토스페이먼츠 자동결제 연동 가이드에서 확인하세요.
  • 키는 개발자센터의 ‘API 키’ 메뉴에서 확인합니다. MeterEngine에는 자동결제(빌링) 상점(MID)의 API 개별 연동 키(클라이언트 키와 시크릿 키 한 쌍)를 넣습니다. 토스페이먼츠는 자동결제처럼 서비스마다 다른 상점에 API 개별 연동 키를 발급하니, 자동결제 상점을 골랐는지 확인하세요. 키 종류는 토스페이먼츠 API 키 문서에 있습니다.
test_gck_, test_gsk_, live_gck_, live_gsk_로 시작하는 주문서형, 결제창형 연동 키(결제위젯 키)는 받지 않습니다. 저장하면 400 invalid_toss_payments_credential로 거절됩니다.

업무 환경마다 받는 키

토스페이먼츠 키는 업무 환경마다 따로 저장합니다. 테스트 환경에 저장한 키는 실제 환경에서 쓰이지 않고, 그 반대도 같습니다. 환경마다 받는 키의 앞부분이 정해져 있습니다.
테스트 키로 한 결제는 실제로 결제되지 않으며 카드에서 금액이 빠져나가지 않습니다.
키를 저장하기 전에 화면 위 ‘업무 환경’이 키를 쓸 환경인지 확인하세요. 로그인하면 ‘기존 데이터’로 열리므로 먼저 ‘테스트 환경’으로 전환합니다. 업무 환경을 고르는 방법은 업무 환경에 있습니다.

키 저장

1

도입사 설정 화면을 연다

콘솔 왼쪽 메뉴 ‘과금과 연동’에서 ‘도입사 설정’을 엽니다. 키를 저장하려면 admin(전체 관리) 권한이 있는 구성원으로 로그인해야 합니다.
2

토스 키 저장을 연다

‘토스페이먼츠 연동’ 구역에서 ‘토스 키 저장’을 누릅니다. 업무 환경이 테스트 환경이면 테스트 키를, 실제 환경이면 실결제 키를 저장하는 창이 열립니다.
3

클라이언트 키와 시크릿 키를 넣는다

개발자센터에서 복사한 키를 ‘클라이언트 키’와 ‘시크릿 키’에 넣고 저장합니다.
4

저장 결과를 확인한다

MeterEngine은 저장하기 전에 시크릿 키로 토스페이먼츠에 결제 조회를 한 번 보내 키가 유효한지 확인합니다. 이 확인은 결제를 만들지 않습니다. 저장되면 키 목록에 결제 모드, ‘관리 상태’, ‘시크릿 키 끝 네 글자’, ‘확인 시각’, ‘저장 시각’이 보입니다.
시크릿 키는 암호화해 저장하고 원문을 다시 보여 주지 않습니다. 목록과 API 응답에는 마지막 네 자(secret_key_last_four)만 나옵니다.

저장이 거절될 때

클라이언트 키는 앞부분만 검사하고 토스페이먼츠에 확인하지 않습니다. 시크릿 키와 다른 상점의 클라이언트 키를 넣어도 저장됩니다. 두 키를 같은 상점의 ‘API 키’ 메뉴에서 복사하고, 저장한 뒤 테스트 환경에서 카드 등록까지 한 번 해 보세요.

키를 바꾸거나 멈출 때

  • 교체: ‘토스 키 저장’으로 새 키를 저장하면 이전 키를 덮어씁니다. 이전 키는 키 목록 위 ‘토스 키 관리 상태’에서 ‘보관됨’이나 ‘전체’를 고르면 볼 수 있습니다. 새로 만드는 카드 등록 링크는 새 키를 씁니다.
  • 보관: 키 목록의 ‘토스 키 보관’을 누르면 그 환경의 새 결제와 카드 등록이 멈춥니다. 이미 진행 중인 결제의 결과 확인과 결제 취소에는 보관한 키를 계속 씁니다. 다시 쓰려면 키를 다시 저장합니다.
키를 교체해도 이미 등록한 고객 카드는 그 카드의 등록 링크를 만들 때 저장되어 있던 키로 계속 결제합니다. 교체 전에 만든 링크로 교체 뒤에 등록한 카드도 이전 키로 결제합니다. 다른 상점의 키로 바꿨다면 새 링크를 만들어 고객에게 카드를 다시 등록받아야 새 상점으로 결제됩니다. 카드 등록 방법은 고객 카드 등록 링크에 있습니다.

토스페이먼츠 웹훅 등록

토스페이먼츠 웹훅을 등록하면 결제 상태가 바뀔 때 토스페이먼츠가 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

웹훅 주소를 만든다

주소는 https://meterengine.com/v1/toss-payments-webhooks/<도입사 id> 입니다. 위 예시라면 다음과 같습니다.
도입사 id는 업무 환경과 관계없이 하나이므로 테스트 결제와 실결제 모두 이 주소 하나로 받습니다.
3

토스페이먼츠 개발자센터에 등록한다

개발자센터의 웹훅 메뉴에서 ‘웹훅 등록하기’를 누르고, 이름과 위 주소를 넣은 뒤 이벤트로 PAYMENT_STATUS_CHANGED를 고릅니다. 토스페이먼츠 웹훅은 상점(MID)마다 따로 설정하므로 MeterEngine에 키를 넣은 상점마다 등록합니다. 메뉴 위치는 토스페이먼츠 웹훅 가이드에 있습니다.
MeterEngine은 토스페이먼츠가 보낸 본문을 그대로 믿지 않습니다. PAYMENT_STATUS_CHANGED일 때만 본문의 주문번호로 결제 시도를 찾고, 그 시도에 쓴 키로 토스페이먼츠에 결제를 다시 조회해 결과 확인 중인 결제와 취소에 반영합니다. 본문을 읽을 수 없거나, 다른 이벤트이거나, 반영할 결제 시도가 없으면 아무것도 바꾸지 않고 200으로 답합니다. 다시 조회한 결과를 확인하지 못하면 500으로 답해 토스페이먼츠가 다시 보내게 합니다.
이 주소는 토스페이먼츠가 부르는 주소입니다. 도입사 서버에서 직접 부르지 마세요. 도입사가 결제 결과를 받으려면 MeterEngine 통보를 등록합니다. 웹훅 받기 시작하기

다음 단계

테스트 결제와 실결제

테스트 환경에서 먼저 확인하고 실제 환경으로 옮기기

고객 카드 등록 링크

고객에게 카드를 등록받기