결제 연동을 테스트 모드에서 끝내고 실결제 전환을 앞두고 있다면, 지금 손이 멈춰 있을 가능성이 높다. 테스트 카드로는 승인도 나고 주문 상태도 잘 바뀌는데, 실결제 키를 넣는 순간부터는 돈이 두 번 빠지거나, 주문이 사라지거나, 환불이 꼬이는 장면이 머릿속에 먼저 떠오른다.
나도 실결제 키를 넣기 전에 한동안 결제 버튼 앞에서 망설였다. 그 불안이 막연한 게 아니라는 걸 나중에 알았다. 테스트 모드는 우리가 만든 흐름이 맞는지는 보여주지만, 카드사가 실제로 어떻게 답하는지와 정산이 어떻게 잡히는지는 보여주지 않는다.
키를 어디서 어떻게 교체하는지는 이 글 범위가 아니다. 여기서는 전환 직후 돈과 주문이 어디서 꼬이는지, 그걸 막으려면 어떤 순서로 확인해야 하는지만 적는다.
테스트에선 잘 되는데, 실결제로 바꾸는 순간 왜 불안할까
테스트 모드와 실결제는 같은 API를 부르지만 뒤에서 일어나는 일이 다르다. 차이를 한눈에 보면 이렇다.
| 구분 | 테스트 모드 | 실결제 |
|---|---|---|
| 카드 | 정해진 테스트 카드, 결과가 거의 항상 같음 | 실제 카드사 응답, 한도와 인증 결과가 상황마다 다름 |
| 인증 단계 | 인증 화면이 안 뜨거나 늘 같은 결과로 끝남 | 카드사별 인증 화면, 중간에 사용자가 이탈할 수 있음 |
| 응답 지연 | 거의 없음 | 늦은 응답과 타임아웃이 실제로 섞임 |
| 정산 | 돈이 움직이지 않음 | 정산일, 수수료, 취소 후 반영 시점이 따로 있음 |
| 웹훅 | 테스트 도메인으로 잘 옴 | 운영 도메인 설정이 틀리면 아무 경고 없이 안 옴 |
걱정은 보통 세 갈래로 온다. 돈이 중복으로 청구되는 것, 결제는 됐는데 주문이 생기지 않는 것, 환불을 눌렀는데 주문 상태만 그대로 남는 것. 이 셋은 따로 노는 문제가 아니다. 하나의 주문에서 금액 불일치와 타임아웃이 같이 겹치면 이 셋이 한꺼번에 나온다.
키를 바꾸기 전과 바꾼 후에 볼 설정
설정 확인은 키를 바꾸기 전에 끝내 두는 편이 낫다. 순서는 아래와 같다.
- 가맹점 정보와 사업자 상태가 정상인지, 정산 계좌가 본인 명의로 등록됐는지 확인한다.
- 웹훅 URL과 결제 완료 후 돌아올 리다이렉트 URL을 운영 도메인 기준으로 다시 등록한다.
- 결제수단, 통화, 최소·최대 결제 금액이 서비스에서 파는 상품과 맞는지 본다.
- 환경 변수로 키를 주입하는지 확인하고, 코드 안에 테스트 값이 박혀 있지 않은지 검색한다.
마지막 항목은 생각보다 자주 빠진다. 테스트 키를 코드에 직접 써 두고 환경 변수를 나중에 붙이면, 키를 바꿔도 예전 값이 계속 쓰인다. 전환 직전에 아래처럼 한 번 검색해 보는 편이다.
grep -rnE "test_|localhost|staging" ./src ./config
웹훅 URL은 내가 점검표에 가장 먼저 넣은 항목이다. 테스트 도메인 주소가 남은 채로 실결제를 열면, 승인은 나는데 알림은 어디로도 가지 않는다. 주문 화면만 보면 멀쩡해 보여서 더 찾기 어렵다.
전환 후에는 같은 항목을 다시 본다. 키가 바뀌었는지, 웹훅 수신 로그에 실제 요청이 들어오는지, 리다이렉트 후 주문 상태가 맞게 바뀌는지를 확인한다.
테스트는 되는데 실결제에서만 깨지는 원인
금액과 통화가 어긋나는 경우
증상은 주문서 금액과 승인 금액이 몇 원 다르게 찍히는 것이다. 원인은 대개 세 가지 중 하나다. 부가세를 포함했는지 빼고 계산했는지가 화면과 서버에서 다르거나, 소수점 처리가 다르거나, 클라이언트가 보낸 금액을 서버가 그대로 믿는 경우다. 점검은 금액을 서버에서만 계산하는지 보는 것으로 시작한다.
서버: 상품가 합계 + 배송비 - 할인 = 결제금액 (서버에서 계산)
클라이언트: 결제금액을 그대로 전달, 서버는 검증만
검증 실패 시 승인 요청 자체를 보내지 않는다
인증 화면에서 흐름이 끊기는 경우
테스트 카드는 인증 화면을 거의 타지 않거나 항상 같은 결과로 끝난다. 실제 카드에서는 카드사 인증 화면이 뜨고, 사용자가 팝업을 닫거나 리다이렉트 중에 세션이 끊기면 주문이 결제 대기 상태로 남는다. 증상은 결제 화면에서 돈이 나갔다는 고객 문의와 주문 목록의 대기 상태가 같이 나타나는 것이다. 이건 테스트 카드로는 재현이 안 된다. 실결제 전에 팝업 차단 상태와 뒤로 가기 상황을 직접 여러 번 눌러 보는 수밖에 없다.
타임아웃 뒤 재시도로 중복 승인이 나는 경우
승인 응답이 늦으면 클라이언트는 실패로 보고 다시 결제를 요청하기 쉽다. 그 사이 카드사는 이미 승인을 끝냈을 수 있다. 그래서 재시도 로직을 붙이기 전에 같은 주문에 대해 중복 요청을 막는 키를 먼저 설계한다는 원칙을 정했다. 재시도 전에는 반드시 결제 조회 API로 그 주문의 상태를 먼저 본다. 다만 이 방식도 완벽하지 않다. 조회 시점에 승인이 아직 끝나지 않았다면 판단이 한 번 더 늦어진다. 이 경계는 아직 깔끔하게 정리하지 못했다.

웹훅이 안 왔거나 가짜일 때, 어떻게 검증할까
웹훅은 결제 완료를 알려 주는 신호일 뿐, 그 자체를 진실로 믿으면 안 된다. 위조된 요청이 들어올 수도 있고, 네트워크 문제로 아예 안 올 수도 있다. 수신 한 건마다 아래 순서로 처리한다.
- 서명을 검증한다. 실패하면 요청을 버리고 기록만 남긴다.
- 같은 이벤트 ID를 이미 처리했는지 본다. 처리했다면 응답만 주고 끝낸다.
- 우리 DB에서 주문을 조회한다.
- 결제 조회 API로 실제 금액과 상태를 다시 확인한다.
- 금액이 맞고 상태가 승인이면 주문 상태를 바꾼다. 맞지 않으면 보류하고 알림을 보낸다.
webhook 수신
서명 검증 실패 → 버리고 기록만 남김
이미 처리한 event_id → 200 응답하고 종료
주문 = 주문 조회(order_id)
실제 = 결제 조회 API(payment_id)
if 실제.금액 != 주문.금액 → 상태 보류, 알림
if 실제.상태 == 승인 and 주문.상태 == 결제대기 → 결제완료로 전이
200 응답
상태 전이는 한 방향으로만 간다. 결제완료였던 주문이 다시 결제대기로 돌아가는 일이 없도록 규칙을 정해 둔다. 이 규칙이 없으면 늦게 도착한 웹훅 하나가 주문 상태를 뒤집는다.
내가 쓰는 보완 장치는 서버 크론으로 돌리는 일일 대사다. 전날 승인 건수와 웹훅 수신 건수를 맞춰 보고, 어긋난 건만 목록으로 뽑는다. 다만 지연 수신이 있어서 전날 건이 당일 대사에서 안 맞는 경우가 있다. 그래서 불일치 건은 바로 실패로 확정하지 않고 다음 대사에서 다시 본다. 이 방식은 늦게 들어온 웹훅은 잡아 주지만, 웹훅이 영영 안 오는 경우는 결제 조회로 직접 찾아야 한다는 한계가 있다.

실결제 전 소액 결제와 환불 흐름까지 확인해야 하는 이유
승인과 정산은 다른 일이다. 카드 승인이 떨어졌다고 정산이 끝난 게 아니고, 취소를 했다고 정산에서 바로 빠지는 것도 아니다. 그래서 실결제 전환 전에 소액 결제 한 건을 끝까지 돌려 본다. 금액은 실제 상품가 대신 결제 가능한 최소 금액으로 잡는다.
| 단계 | 확인할 것 | 기대 상태 |
|---|---|---|
| 1. 결제 | 승인 응답과 결제 ID | 주문 결제대기 |
| 2. 웹훅 | 수신 로그, 서명 검증 통과 | 주문 결제완료로 전이 |
| 3. 부분 환불 | 환불 금액, 환불 API 응답 | 주문 부분환불, 잔여 금액 표시 |
| 4. 전액 환불 | 취소 응답, 웹훅 도착 여부 | 주문 취소, 결제 상태 취소 |
| 5. 정산 | 정산 리포트에 취소가 반영된 날짜 | 정산 금액에서 빠짐 |
환불 흐름은 결제 흐름보다 나중에 만들기 쉽다. 그러면 주문 상태 전이 표에 환불 칸이 빠진 채 남는다. 결제 화면만 보고 전환하면 이 빈칸을 놓친다. 그래서 나는 소액 결제 한 건을 결제부터 정산 확인까지 한 번 돌리는 것을 전환 조건으로 둔다.
한계도 있다. 환불이 안 되는 조건, 예를 들어 이미 정산이 끝난 건이나 일정 기간이 지난 건은 결제 수단과 PG마다 다르다. 이건 직접 약관과 관리자 화면에서 확인해야 한다. 정산 반영 시점도 같다. 내가 본 날짜가 다른 결제 수단에서도 같다고 장담할 수 없다.

오픈 후 첫 일주일, 어떤 로그와 지표를 봐야 할까
오픈 직후에는 지표를 매일 같은 시간에 같은 항목으로 기록한다. 정상 범위를 고정 숫자로 정하면 서비스마다 맞지 않는다. 대신 평소 대비 변화를 본다. 처음 며칠은 기준선이 없으니 그냥 기록만 쌓는다.
| 지표 | 보는 방법 | 변화 신호 |
|---|---|---|
| 승인율 | 승인 건 / 결제 시도 건 | 평소보다 눈에 띄게 떨어짐 |
| 웹훅 수신율 | 웹훅 수신 건 / 승인 건 | 승인은 있는데 수신이 줄어듦 |
| 불일치 건수 | 대사 배치 결과 | 금액이 맞지 않는 건이 나옴 |
| 타임아웃 응답 | 승인 요청 로그의 시간 초과 응답 | 평소보다 늘어남 |
| 환불 건수 | 취소·환불 API 호출 건 | 평소보다 급하게 늘어남 |
중단 기준은 판단을 미루지 않도록 미리 적어 둔다. 아래 표를 그대로 복사해서 써도 된다.
| 상황 | 판단 | 조치 |
|---|---|---|
| 금액이 맞지 않는 건이 나옴 | No-Go | 신규 결제 중단, 해당 주문 보류 |
| 승인은 있는데 웹훅 수신이 계속 빠짐 | No-Go | 웹훅 URL과 서명 검증부터 확인 |
| 승인율이 평소 대비 떨어지고 이유가 안 보임 | 보류 | 카드사 응답 코드를 묶어서 원인 찾기 전까지 확대하지 않음 |
| 환불이 평소보다 늘었음 | 확인 | 환불 사유와 주문 상태 전이를 함께 봄 |
| 지표가 흔들리지만 원인이 보임 | Go 유지 | 원인 수정 후 다음 날 같은 시간에 다시 기록 |
지표가 흔들릴 때 가장 참기 어려운 건 판단을 미루는 일이다. 나도 승인율이 떨어졌을 때 원인을 찾기 전에 결제 버튼을 열어 둘지 고민했다. 그래서 지금은 원인이 잡히기 전에는 신규 결제를 늘리지 않는 쪽으로 정해 두었다. 그 덕에 판단은 느려지지만 돈이 꼬이는 속도는 줄어든다.
1인 운영자를 위한 실결제 전환 체크리스트 요약
전환 전에 끝내 둘 항목은 아래와 같다.
- 가맹점과 사업자 상태, 정산 계좌를 확인했다.
- 웹훅 URL과 리다이렉트 URL을 운영 도메인으로 다시 등록했다.
- 결제수단, 통화, 최소·최대 금액을 확인했다.
- 코드에 테스트 키나 테스트 도메인이 남아 있지 않다.
- 금액은 서버에서 계산하고 클라이언트 값은 검증만 한다.
- 웹훅은 서명 검증과 중복 확인 후 결제 조회 API로 재확인한다.
- 주문 상태 전이 규칙을 한 방향으로 정해 두었다.
- 소액 결제 한 건을 결제, 웹훅, 부분 환불, 전액 환불, 정산까지 돌렸다.
전환 후 첫날에는 승인율, 웹훅 수신율, 불일치 건수, 환불 건수를 같은 시간에 기록한다. 불일치가 하나라도 금액 차이로 나오면 신규 결제를 멈추고 그 주문부터 본다.
이 체크리스트로도 못 잡는 것이 있다. 정기결제와 해외결제는 승인 흐름과 정산 방식이 달라서 별도로 점검해야 한다. 가상계좌나 간편결제처럼 응답이 늦게 오는 수단도 같다. 이 부분은 다음 글에서 따로 다룰 생각이다.
그래도 지금 당장 할 일은 하나다. 테스트 카드 말고 본인 카드로 소액 결제를 한 건 돌려 보는 것이다. 결제부터 정산 확인까지 한 바퀴 돌려 보면, 이 글에서 적은 지점 중 어디가 우리 서비스에서 실제로 걸리는지 바로 보인다. 만든 것들은 wallenstein.dev에 정리해 두었다.
1인 빌더 아일리고가 씁니다. 잘된 것도 망한 것도 적습니다. 영상은 제가 만든 ClipSquare 에서 나옵니다.
자주 묻는 질문
테스트 모드에서 결제가 잘 되면 실결제도 그대로 되나요?
테스트에서는 우리가 만든 흐름이 맞는지만 확인된다. 카드사 응답, 인증 화면 이탈, 정산 반영은 테스트 카드로 재현이 안 된다. 실결제 전에 팝업을 닫거나 뒤로 가기를 눌러 보는 식으로 중간 이탈 상황을 직접 만들어 두는 편이 안전하다.
실결제 후 결제는 됐는데 주문이 안 생기면 어디부터 봐야 하나요?
먼저 웹훅이 운영 도메인으로 실제 들어왔는지 수신 로그를 본다. 로그가 없으면 웹훅 URL에 테스트 주소가 남아 있는지부터 확인하고, 로그는 있는데 주문이 없으면 서명 검증이나 금액 비교에서 막혔는지 본다. 결제 조회 API로 승인 여부를 먼저 맞춰 두면 고객 문의에 바로 답할 수 있다.
웹훅이 진짜 결제 완료 신호인지 어떻게 믿을 수 있나요?
웹훅은 알림일 뿐이라 그 자체로 주문을 확정하면 안 된다. 서명을 먼저 검증하고, 결제 조회 API로 같은 주문의 금액과 상태를 다시 확인한 뒤 반영하는 순서로 처리한다. 이렇게 하면 위조 요청과 누락을 함께 막을 수 있다.
승인 응답이 늦어서 실패처럼 보이면 다시 결제 요청해도 되나요?
바로 재요청하면 카드사가 이미 승인한 상태에서 두 번 빠질 수 있다. 재시도 전에 결제 조회 API로 그 주문의 상태를 먼저 보고, 승인 기록이 없을 때만 다시 요청하는 것이 기본이다. 다만 조회 시점에 승인이 아직 끝나지 않았다면 판단이 한 번 더 늦어지니 완벽한 답은 아니다.
