토스페이먼츠 결제 승인 요청이 실패해요

결제창 성공 뒤 서버 승인 요청이 실패할 때 결제 키·주문번호·금액과 승인 응답을 대조하는 시작 Guide입니다. 오류 원문과 발생 환경이 일치하지 않으면 원인을 단정하지 않습니다.

먼저 기록할 것

1. 화면·브라우저 개발자 도구·서버 로그 중 어디에서 오류를 확인했는지 기록합니다.
2. 오류 문구·상태 코드·요청 주소·발생 시각을 가능한 한 원문 그대로 보존합니다.
3. 최근 배포·설정·도메인·플러그인·호스팅 변경 여부를 기록합니다.
4. 문의 자료에서는 비밀번호·토큰·쿠키·고객 정보·결제 정보를 제거합니다.

상황별 다음 단계

1. 토스페이먼츠 결제 승인 API 요청이 실패함이면 토스페이먼츠 결제 승인 요청이 실패함 문서를 확인합니다.
2. 승인 요청의 orderId가 상점 주문과 다름이면 토스페이먼츠 orderId가 상점 주문과 일치하지 않음 문서를 확인합니다.
3. 승인 이후 상점 주문 상태가 완료로 확인되지 않음이면 토스페이먼츠 결제 뒤 주문 상태를 확인할 수 없음 문서를 확인합니다.

확인 순서

1. 문제를 재현하는 URL 또는 기능을 한 가지로 고정합니다.
2. 위 Problem의 관찰값과 현재 화면·로그가 일치하는지 비교합니다.
3. 한 번에 하나의 설정이나 코드만 확인하고, 변경 전 값을 보관합니다.
4. 수정 후 같은 브라우저·주소·기능에서 다시 확인합니다.

승인 요청을 판정하는 기준

관찰값	판정 기준	다음 확인
결제창은 성공했지만 승인 API가 실패함	결제창 성공과 서버 승인 요청은 별도 단계입니다.	paymentKey, orderId, 금액, 인증 헤더와 승인 응답 코드를 비교합니다.
orderId가 상점 주문과 다름	승인 결과를 올바른 주문에 연결할 수 없는 상태입니다.	클라이언트 생성 값과 서버 저장 값을 같은 요청 ID로 비교합니다.
승인은 성공했지만 주문 상태가 미완료	주문 생성·웹훅·DB 트랜잭션 중 한 구간이 반영되지 않은 상태입니다.	승인 시각의 서버 로그와 주문 상태 변경 로그를 비교합니다.

실제 결제 키·시크릿 키·카드 정보는 기록하지 않습니다. 결제 상태가 불명확하면 재승인·환불·주문 상태 변경을 먼저 실행하지 않습니다.

수정 후 재확인

1. 테스트 환경에서 같은 금액·주문 ID 흐름을 한 번 실행합니다.
2. 승인 요청과 응답의 상태 코드·오류 코드, 주문 저장 결과를 기록합니다.
3. 완료 화면과 웹훅을 사용하는 경우 각각의 응답 코드와 중복 처리 결과를 확인합니다.
4. 운영 결제는 PG 관리자 화면의 상태와 상점 주문 상태가 일치할 때만 완료로 기록합니다.

관련 점검표: 국내 PG 결제 승인·주문 상태 확인표

오진하지 않기

이 Guide의 제목이나 플랫폼 이름만으로 원인을 확정하지 않습니다. Problem 문서의 조건과 실제 관찰값이 다르면 설정을 변경하지 말고 오류 원문과 환경을 다시 기록합니다.