메인 콘텐츠로 건너뛰기
MeterEngine은 지금 미리 보기 단계라 테스트 환경에서 연동을 검증하는 용도로 씁니다. 자세한 내용은 MeterEngine 소개에 있습니다.

업무 환경이 결제 모드를 정한다

테스트 환경과 실제 환경에서는 결제 모드가 업무 환경에 고정되어 있습니다. 도입사가 바꿀 수 없고, 바꿀 필요도 없습니다. 지금 업무 환경의 결제 모드는 ‘도입사 설정’ 화면의 ‘현재 결제 모드’에 보이고, read 권한 API 키로 GET /v1/payment-setting을 불러도 확인할 수 있습니다. 테스트 환경과 실제 환경에서는 응답의 updated_at이 늘 null입니다.
응답 200
토스페이먼츠 키, 고객 카드, 결제 시도, 결제 취소는 모두 업무 환경마다 따로입니다. 테스트 환경에서 등록한 카드로 실제 환경의 인보이스를 결제할 수 없습니다. 테스트 환경도 보낸 이벤트와 확정한 인보이스는 되돌릴 수 없습니다. 테스트 환경이 무엇을 분리하고 무엇은 실제로 일어나는지는 업무 환경에 있습니다.

테스트 환경에서 확인할 것

1

테스트 키를 저장한다

업무 환경을 ‘테스트 환경’으로 두고 토스페이먼츠 테스트 키(test_ck_, test_sk_)를 저장합니다. 토스페이먼츠 상점 준비와 키 저장
2

테스트 카드를 등록한다

시험용 고객에게 카드 등록 링크를 만들어 직접 열어 봅니다. 토스페이먼츠 테스트 환경에서는 본인인증 문자가 오지 않으니 인증번호 칸에 000000을 넣습니다. 카드 번호는 앞 여섯 자리(BIN)만 유효하면 등록됩니다. 실제 환경에서는 카드 번호 전체가 유효해야 합니다. 고객 카드 등록 링크
3

결제를 요청한다

확정한 인보이스로 결제를 요청하고 status가 done인지 봅니다. 첫 결제 요청과 결과 확인
4

실패를 재현한다

아래 테스트 헤더로 결제 실패를 일부러 만들어 실패 처리와 통보 수신을 확인합니다.

결제 실패 재현하기

테스트 환경에서 결제 실패를 재현하려면 결제 요청에 TossPayments-Test-Code 헤더로 토스페이먼츠 오류 코드를 넣습니다(예: INVALID_REJECT_CARD). MeterEngine은 값을 그대로 토스페이먼츠에 넘기므로, 실제 거절과 같은 경로로 실패와 자동 재시도 흐름을 미리 확인할 수 있습니다. 넣을 수 있는 오류 코드는 토스페이먼츠 오류 코드 문서에서 고릅니다.
거절되면 응답은 201이고 status가 failed, failure_code가 넣은 오류 코드, failure_message가 토스페이먼츠의 거절 문구입니다. 빈 값을 보내면 헤더를 보내지 않은 것으로 봅니다. 이 헤더는 그 요청 한 번에만 쓰이고, 자동 재시도와 고객 화면에서 다시 하는 결제에는 실리지 않습니다.
INVALID_REJECT_CARD처럼 카드 자체의 오류는 고객이 카드를 다시 등록하기 전에는 MeterEngine이 자동으로 다시 시도하지 않는 실패입니다. 자동 재시도를 확인하려면 다시 시도하는 실패 코드를 넣으세요. 어떤 실패를 다시 시도하는지는 결제 실패와 재시도에 있습니다.
실제 환경에서 TossPayments-Test-Code 헤더를 보내면 MeterEngine이 400 toss_payments_test_code_in_live_mode로 거절하고 결제 시도를 만들지 않습니다. 실제 환경으로 옮길 때 연동 코드에서 이 헤더를 빼세요.

실제 환경으로 옮기기

테스트 환경의 데이터는 실제 환경으로 복사되지 않습니다. 실제 환경에서 아래를 처음부터 다시 준비합니다.
1

토스페이먼츠 자동결제 계약을 맺는다

실결제 자동결제는 토스페이먼츠의 리스크 검토와 계약 뒤에 쓸 수 있습니다. 토스페이먼츠 상점 준비와 키 저장
2

업무 환경을 실제 환경으로 바꾼다

화면 위 ‘업무 환경’에서 ‘실제 환경’을 고르고 ‘전환’을 누릅니다.
3

미터, 단가, 고객을 다시 만든다

고객, 미터, 단가는 업무 환경마다 따로 만들어야 합니다. 업무 환경
4

실제 환경 API 키와 통보를 준비한다

실제 환경에서 API 키를 발급하면 me_live_로 시작하는 키가 나옵니다. MeterEngine 통보 수신 주소도 실제 환경에 다시 등록합니다. API 키 발급과 첫 호출, 웹훅 받기 시작하기
5

실결제 토스페이먼츠 키를 저장한다

계약한 상점의 live_ck_, live_sk_ 키를 저장합니다. 토스페이먼츠 웹훅 주소는 테스트 환경과 같은 주소를 쓰고, 실결제 상점(MID)에도 등록되어 있는지 확인합니다.
6

고객에게 카드를 다시 등록받는다

실제 환경의 고객마다 카드 등록 링크를 새로 만들어 전달합니다. 테스트 환경에서 등록한 카드는 실제 환경에서 쓰이지 않습니다.

API 키의 모드와 결제 모드

결제 요청과 카드 등록 링크 만들기는 API 키의 모드와 업무 환경의 결제 모드가 다르면 409 payment_mode_mismatch로 거절됩니다. 테스트 환경에서 발급한 키는 테스트 결제, 실제 환경에서 발급한 키는 실결제에 고정되어 있어 두 환경에서는 이 오류가 나지 않습니다. 이 오류가 나면 ‘기존 데이터’에서 발급한 키를 쓰고 있는지 확인하세요.
업무 환경이 ‘기존 데이터’일 때만 ‘도입사 설정’ 화면에서 결제 모드를 바꿀 수 있습니다(‘결제 모드 변경’). 실결제로 바꾸려면 실결제 토스페이먼츠 키를 먼저 저장해야 하고, 없으면 409 toss_payments_credential_missing으로 거절됩니다. 새로 연동한다면 테스트 환경과 실제 환경을 쓰세요. 두 환경은 결제 모드가 고정이라 바꿀 필요가 없습니다.