조선익의 개발자 생활
← 목록으로

가맹점 주문 관리 시스템·설계·2026-11-07

결제 단말기와 전자서명 연동: 승인·등록 불일치와 취소 정합성

카드 단말기 결제에서 승인은 났는데 시스템에 등록되지 않는 문제를 원인별로 줄이고, 재시도·취소·환불 흐름이 실제 결제와 어긋나지 않게 고친 과정입니다.

기술
Spring Boot, MyBatis, React, TypeScript
결과
결제 후 미등록 문의 월 약 5건 → 조치 후 약 2개월간 1건 (운영 문의 건수)
  • 결제 연동
  • 전자서명
  • 운영 문제
  • 타임아웃
스킬Spring BootMyBatisReactTypeScript

가맹점 주문 관리 시스템에서 카드 단말기 결제와 전자서명을 연동했습니다. 가장 오래 붙잡은 문제는 "단말기에서는 결제가 끝났는데 시스템에는 등록되지 않았다"는 문의였습니다. 배포 시각을 옮기고 단말기 요청 대기 시간을 10분으로 늘린 뒤, 이 문의는 월 약 5건에서 약 2개월간 1건으로 줄었습니다. 같은 기간에 결제 요청이 두 번 나가거나 취소가 의도 없이 실행되지 않도록 결제와 취소 흐름도 함께 고쳤습니다. 백엔드는 Spring Boot와 MyBatis, 화면은 React와 TypeScript입니다.

문제: 승인과 등록이 따로 일어난다

결제가 통과되면 보험 서류에 서명을 받는 흐름이었습니다. 결제는 두 단계로 나뉩니다.

  • 승인: 브라우저가 PC에서 도는 단말기 연동 프로그램(localhost 포트)에 결제를 요청하면, 단말기가 VAN사와 승인을 처리합니다.
  • 등록: 브라우저가 단말기의 결과를 받아 백엔드의 결제 등록 API를 호출합니다.

두 단계 사이에서 연결이 끊기거나 브라우저가 먼저 기다리기를 그만두면, 카드 승인은 났는데 시스템에는 결제가 없는 상태가 됩니다. 가맹점은 고객 앞에서 결제를 다시 할 수도, 그냥 보낼 수도 없게 됩니다.

원인과 조치

아래 건수는 운영 중에 받은 문의를 센 값이고, 같은 기간의 전체 결제 건수는 함께 기록하지 않았습니다.

원인 1: 배포 시간과 영업 시간이 겹침

운영 초기에는 배포 시각이 합의되지 않았습니다. 오후 6시로 합의한 뒤에도 폐점 시간대에 손님을 맞아 결제하는 경우가 있었고, 그동안 백엔드는 등록 요청을 받지 못했습니다. 배포를 예약 스크립트로 오후 10시에 실행하도록 옮긴 뒤로는 배포 때문에 누락된 건이 없었습니다. 시간대를 대조해서 확인했습니다.

원인 2: 단말기 요청 대기 시간이 서명보다 짧았다 (월 약 5건 → 약 2개월간 1건)

단말기 요청을 기다리는 시간은 호출하는 곳마다 따로 적혀 있었습니다. 기본값은 35초였고, 결제와 취소 화면은 호출할 때마다 3분을 따로 지정하고 있었습니다. 고객이 카드를 늦게 꺼내거나 서명이 길어지면, 단말기는 VAN사에 승인을 요청했는데 브라우저는 시간 초과로 처리하는 일이 생깁니다. 승인은 끝났는데 등록이 빠지는 경우입니다.

이 원인은 처음에는 가설이었습니다. 2026년 6월에 대기 시간을 한 파일의 값으로 모으고 결제와 취소 요청을 모두 3분으로 맞췄습니다. 그 뒤에도 문의가 이어져서 8월에 10분으로 늘렸습니다. 늘린 뒤 약 2개월 동안 미등록 문의는 1건이었습니다. 그전에는 월 5건 정도였습니다.

재현되지 않는 문제를 구간별 로그로 좁히기

에러가 재현되지 않아서 프론트, 단말기 연동 프로그램, 백엔드 세 구간에 로그를 넣었습니다. 브라우저는 파일을 만들 수 없어서, 문제가 생기면 클라이언트에서 백엔드로 로그를 바로 보내는 방식으로 운영했습니다.

설계 선택: 요청은 한 번만, 취소는 확인한 뒤에

단말기는 한 번 요청하면 실제 카드 승인이나 취소로 이어집니다. 그래서 화면이 알아서 다시 보내거나 대신 취소하는 동작을 줄였습니다.

  • 단말기 결제 요청의 자동 재시도를 껐습니다. 재시도가 켜져 있으면, 화면에서 실패로 처리된 요청이 단말기로 한 번 더 나갈 수 있습니다.
  • 결제 실패 안내 창에서 단말기 취소는 확인 버튼을 눌렀을 때만 실행합니다. 의도하지 않은 자동 취소 요청을 막기 위해서입니다.
  • 결제 화면을 떠나면 남아 있는 콜백을 정리해서, 화면을 떠난 뒤 취소가 중복으로 나가지 않게 했습니다.

대가도 있습니다. 일시적인 통신 오류에도 사용자가 직접 다시 눌러야 하고, 실패 안내 창을 확인하지 않고 닫으면 취소가 실행되지 않습니다.

취소와 환불 흐름

취소와 환불에서도 시스템과 실제 결제가 어긋나지 않게 맞췄습니다. 결제는 두 종류입니다. 고객이 매장에서 카드 단말기로 내는 결제와, 가맹점이 본사에 주문하면서 예치금으로 내는 결제입니다.

고객 결제(카드 단말기)

  • 현금 결제를 취소할 때 현금영수증 발급 여부를 확인하고, 발급된 건이면 단말기에 현금영수증 취소를 함께 요청합니다.
  • 과세로 결제한 건은 과세로, 영세로 결제한 건은 영세로 취소되도록 맞췄고, 판매 이력에 취소 일시를 남깁니다.
  • 고객이 카드사에서 직접 취소한 건은 VAN사도 알 수 없어서, 화면에서 취소 사실을 반영하는 버튼을 따로 만들었습니다.

가맹점 주문 결제(예치금)

  • 주문 결제 창에서 뒤로 나가면 만들던 주문을 지웁니다. 결제 내역이 있는 주문은 지우지 못하게 막았습니다. 진행되지 않은 채 남은 주문은 매시 정각에 도는 스케줄러가 정리합니다.
  • 반품 환불은 은행 API 이체에서 내부 예치금 적립으로 바꿨습니다. 정산을 단순하게 하기 위해서입니다.

결과, 한계, 배운 점

미등록 문의는 월 약 5건에서 약 2개월간 1건으로 줄었습니다. 남은 한계는 다음과 같습니다.

  • 대기 시간을 늘린 것은 창을 넓힌 것이고, 승인과 등록이 브라우저를 사이에 두고 나뉜 구조는 그대로입니다. 누락을 없애려면 결제를 요청하기 전에 서버에 요청 건을 남기고, 응답이 없는 건을 나중에 맞추는 장치가 필요합니다. 이 장치는 아직 만들지 않았습니다.
  • 미등록 건은 가맹점에서 결제 정보를 받아, 호출됐어야 할 API를 직접 파라미터를 만들어 호출하는 식으로 복구합니다.
  • 대기 시간을 늘린 뒤에도 남은 건의 원인은 확정하지 못했고, 조치마다 전후 건수를 따로 세지 않았습니다.

배운 점은 두 가지입니다. 승인과 등록이 나뉜 구조에서는 중간 단계가 실패한다고 보고 설계해야 하고, 대기 시간은 현장의 실제 행동(카드 꺼내기, 서명)을 기준으로 잡아야 합니다.

전체 글경력소개
  • 최적화4
  • 설계5
  • 연구0

태그

  • 성능 최적화4
  • 운영 문제4
  • 데이터베이스3
  • 멀티테넌트2
  • 스키마2
  • 이벤트 처리2
  • 가상화1
  • 결제 연동1
  • 공공 API1
  • 데이터 정제1
  • 로깅1
  • 마이그레이션1
  • 멀티스레드1
  • 배치 처리1
  • 엑셀1
  • 이벤트 순서1
  • 전자서명1
  • 타임아웃1
  • AI 연동1

스킬

  • React4
  • Spring Boot3
  • C#2
  • Apache POI1
  • DataTables1
  • Django1
  • Docker1
  • JPA1
  • LLM API1
  • MyBatis1
  • MySQL1
  • PostgreSQL1
  • Spring1
  • TypeScript1
문의

댓글 0

    조회 0