토스페이먼츠 결제 후 페이지가 비는 문제, 어디를 봐야 할까

결제 성공과 주문 성공은 다르다

먼저 이 구분이 중요합니다.

결제 성공은 결제사가 돈을 받을 준비를 마쳤거나 승인 처리를 완료했다는 뜻입니다. 주문 성공은 우리 서비스가 그 결과를 받아서 주문 데이터로 저장하고, 사용자에게 완료 화면을 보여줬다는 뜻입니다.

AI가 결제 연동을 만들 때는 결제창 호출까지는 꽤 잘 만듭니다. 문제는 그 다음입니다.

• 결제 성공 후 돌아오는 주소가 맞는가
• 성공 페이지에서 필요한 값을 읽고 있는가
• 결제 승인 또는 검증 절차가 필요한 구조인가
• 주문 데이터를 데이터베이스에 저장하는가
• 저장된 주문을 완료 화면에서 다시 불러오는가

이 중 하나만 빠져도 "결제는 됐는데 화면은 비어 있는" 상태가 됩니다.

1. 성공 URL에 값이 넘어오는지 확인하기

결제가 끝나면 사용자는 성공 페이지로 돌아옵니다. 이때 URL에는 보통 결제와 주문을 식별할 수 있는 값들이 붙습니다. 예를 들어 주문 번호, 결제 키, 금액 같은 값입니다.

주문 완료 화면이 비어 있다면 가장 먼저 볼 것은 성공 페이지 URL입니다. 주소 뒤에 필요한 값이 붙어 있는지 확인하세요. 값이 없다면 결제창을 띄울 때 successUrl을 잘못 만들었거나, 주문 정보를 넘기는 과정이 빠졌을 수 있습니다.

비개발자라도 할 수 있는 확인은 간단합니다.

• 결제 완료 후 주소창을 복사한다
• 주소에 orderId 같은 식별값이 있는지 본다
• 테스트 주문마다 값이 달라지는지 본다
• 성공 페이지를 새로고침해도 같은 값으로 화면이 뜨는지 본다

주소에 아무 값도 없는데 완료 화면에서 주문을 보여주려고 하면, 화면은 빈 상태가 될 가능성이 높습니다.

2. 주문을 언제 저장하는지 확인하기

결제 기능에서 자주 생기는 실수는 주문 저장 시점이 애매한 것입니다.

어떤 프로젝트는 결제창을 열기 전에 임시 주문을 저장합니다. 어떤 프로젝트는 결제 성공 후에 주문을 저장합니다. 둘 다 가능하지만, 어느 쪽인지 분명해야 합니다.

AI가 만든 코드에서는 이 흐름이 중간에 섞이는 일이 있습니다. 결제 전에는 장바구니 데이터만 있고, 결제 후에는 URL 값만 있는데, 정작 데이터베이스에는 주문을 저장하지 않는 식입니다.

확인할 질문은 이렇습니다.

• 결제 버튼을 누르기 전에 주문 레코드가 만들어지는가
• 결제 성공 후 주문 상태가 paid로 바뀌는가
• 실패하거나 취소했을 때 주문 상태는 어떻게 되는가
• 같은 결제를 두 번 처리하지 않도록 막고 있는가

결제 오류는 화면 문제가 아니라 데이터 흐름 문제인 경우가 많습니다.

3. 금액과 주문 번호가 서로 맞는지 확인하기

결제 연동에서 중요한 것은 "돌아온 값이 믿을 수 있는가"입니다. 사용자가 돌아온 URL에 금액이 있다고 해서 그대로 주문 완료 처리하면 위험합니다. 금액이나 주문 번호는 서버나 데이터베이스에 있는 원래 주문과 맞는지 확인해야 합니다.

초기 MVP에서는 이 부분이 대충 넘어가기도 합니다. 테스트에서는 문제가 없어 보이지만, 실제 결제에서는 주문 금액 불일치나 중복 처리 문제가 생길 수 있습니다.

특히 이런 증상이 있으면 금액과 주문 번호 흐름을 봐야 합니다.

• 결제 완료 화면의 금액이 가끔 0원으로 나온다
• 관리자 주문 금액과 결제 금액이 다르다
• 같은 주문이 두 번 저장된다
• 결제는 성공했는데 어떤 상품인지 알 수 없다

결제는 고객 신뢰와 바로 연결됩니다. 화면만 맞추기보다 데이터가 맞는지까지 확인해야 합니다.

4. 배포 환경의 주소와 키를 확인하기

로컬 테스트에서는 되는데 실제 도메인에서만 결제 후 화면이 비는 경우도 있습니다. 이때는 코드보다 배포 설정을 먼저 봅니다.

흔한 원인은 성공 URL이나 실패 URL이 로컬 주소로 남아 있는 경우입니다. localhost 주소, 미리보기 도메인, 예전 배포 주소가 코드나 환경 변수에 남아 있으면 실제 고객은 엉뚱한 페이지로 돌아올 수 있습니다.

확인할 것:

• successUrl과 failUrl이 운영 도메인 기준인가
• 테스트 키와 라이브 키를 구분했는가
• Vercel 같은 배포 서비스에 환경 변수가 등록되어 있는가
• 키를 바꾼 뒤 재배포했는가

AI는 현재 보고 있는 코드 안에서는 답을 잘 찾지만, 배포 서비스에 빠진 환경 변수까지 스스로 알 수는 없습니다.

AI에게 다시 물어볼 때는 이렇게

결제 문제가 생겼을 때 AI에게 "토스페이먼츠 결제 오류 고쳐줘"라고만 하면 범위가 너무 넓습니다. 아래처럼 흐름을 나눠서 물어보는 편이 낫습니다.

• 결제 성공 후 돌아오는 URL에서 어떤 값을 읽고 있는지 먼저 설명해줘.
• 주문 데이터가 결제 전과 결제 후 중 언제 저장되는지 찾아줘.
• 완료 페이지가 빈 화면이 되는 원인을 화면 렌더링, URL 파라미터, DB 조회로 나눠서 분석해줘.
• 코드를 바로 수정하지 말고 결제 흐름을 단계별로 정리해줘.

바로 수정부터 시키지 않는 것이 중요합니다. 결제는 한 줄 고쳐서 되는 문제처럼 보여도, 실제로는 주문 저장 흐름 전체를 확인해야 안전합니다.

정리

토스페이먼츠 결제 후 주문 완료 페이지가 비어 있다면 다음 순서로 보세요.

1. 성공 URL에 주문 식별값이 있는지
2. 주문을 결제 전이나 결제 후에 실제로 저장하는지
3. 결제 금액과 주문 금액이 일치하는지
4. 운영 도메인과 환경 변수가 맞는지
5. 완료 화면이 DB에서 주문을 다시 불러오는지

결제는 "일단 되게"보다 "틀렸을 때 사고가 나지 않게"가 더 중요합니다. 테스트 결제에서는 지나간 문제가 실제 고객 앞에서 드러날 수 있으니, 운영 전에 흐름을 한 번은 사람 눈으로 점검하는 편이 좋습니다.

관련 글: AI 코딩 에이전트가 고치지 못하는 버그의 3가지 특징, AI로 만든 서비스 유지보수 맡기기 전 확인할 것