가이드

스마트매칭

AutoTransPay 스마트매칭 규칙입니다. 입금자명·금액으로 주문을 찾는 이름 비교와 자동확정 판정, 보호자·법인 입금, 역매칭, 텔레그램 1탭 승인을 설명합니다.

은행 알림의 입금자명은 주문서에 적힌 이름과 자주 어긋납니다. 은행이 글자수를 잘라 보내고, 동명이인을 구분하려고 휴대폰 뒷자리를 붙이고, 외국인은 이름 순서가 뒤바뀌고, 부모가 대신 입금합니다. 스마트매칭은 이런 차이를 흡수하면서도 확실할 때만 자동으로 확정하고, 애매하면 사람에게 후보를 보여주는 것을 원칙으로 합니다.

이름 비교 규칙

비교 전에 양쪽 이름을 정규화합니다: 유니코드 정규화(NFKC), 공백·특수문자 제거, 영문 소문자화, 법인 표기((주), ㈜, 주식회사, (유), 유한회사, (사), 사단법인) 제거. 그다음 아래 규칙 중 가장 높은 점수를 씁니다.

규칙 점수 예 (주문 → 입금)
정확 일치 100 홍길동 → 홍길동, (주)알파스포츠 → 알파스포츠
이름 + 휴대폰 뒷자리 97 홍길동(010-1234-5678) → 홍길동5678
어순 뒤바뀜 95 Daniel Tan → TAN DANIEL
잘림 (4자 이상) 90 대한팔씨름연맹협회 → 대한팔씨름연맹협
이름 + 숫자 (휴대폰 불일치) 85 홍길동 → 홍길동1111
잘림 (3자) 80 남궁민수 → 남궁민
포함 관계 70 알파스포츠 → 알파
오타 (편집거리 1) 65 홍길동 → 홍길둥
  • 휴대폰 뒷자리는 주문의 customer.phone 끝자리와 입금자명에 붙은 숫자가 같을 때만 97점입니다. 다르면 85점(이름+숫자)입니다.
  • 주문의 depositor_name 과 alt_names 를 모두 비교해 가장 높은 점수를 씁니다.
  • 이름이 60점 미만이어도 금액이 같은 주문은 "금액만 일치" 후보(30점)로 보여 줍니다. 이름을 전혀 모르는 사람이 대신 입금한 경우를 사람이 찾을 수 있게 하기 위해서입니다.
  • 이름은 90점 이상인데 금액이 다른 주문은 점수를 30점 깎아 후보로 보여 줍니다(amount_mismatch).

판정

입금 한 건마다 후보를 점수순으로 최대 5개 추린 뒤, 아래 조건을 모두 만족할 때만 자동확정합니다.

  1. 1순위 후보의 금액이 정확히 일치
  2. 1순위 후보의 이름 점수가 90점 이상 (조직 설정 auto_threshold)
  3. 경쟁 후보가 없음 — 금액이 같고 1순위와 20점 이내인 다른 후보가 없어야 함
  4. 은행 알림 해석 확신도(confidence)가 0.7 이상
  5. 입금액이 자동확정 금액 상한 이하 (auto_max_amount 를 설정한 경우)
  6. 주문이 만료되지 않음
  7. 조직 설정에서 자동확정이 켜져 있음 (auto_confirm)

하나라도 어긋나면 입금은 review(확인 필요)가 되고, 사유가 review_reason 에 기록됩니다.

review_reason 의미 흔한 원인
ambiguous 같은 조건의 후보가 여러 건 같은 사람이 같은 금액으로 주문을 두 번 넣음
weak_name 이름 점수가 자동확정 기준 미달 오타, 포함 관계, 이름+숫자
amount_mismatch 이름은 맞는데 금액이 다름 배송비 누락, 부분 입금, 수수료 차감
expired_order 일치하는 주문이 만료됨 입금 기한이 지난 뒤 입금
over_limit 자동확정 금액 상한 초과 고액 입금
low_confidence 은행 알림 해석이 불확실 처음 보는 형식의 알림
manual_mode 자동확정이 꺼져 있음 조직 설정 auto_confirm: false
merchant_rejected 가맹점이 웹훅을 거절 웹훅에 409·410·422 응답
quota_exceeded 이번 달 Free 한도(100건)를 모두 사용 (유료 요금제가 만료돼 7일 유예 뒤 Free 로 돌아간 경우 포함) 요금제 결제 시 최근 30일 동안 밀린 입금을 바로 다시 확인
suspicious 위조·조작 의심 신호가 있음 (flags 참고) 입금자명에 금액을 넣은 입금, 잔액 불연속, 개인 휴대폰에서 온 문자
reported_name 구매자가 결제 위젯에서 알린 입금자명으로만 맞음 가족 명의로 입금하고 위젯에서 이름을 알림 — 같은 금액의 다른 주문도 후보에 함께 남음

suspicious 입금은 반드시 통장 앱에서 실제 입금 내역을 확인한 뒤 확정하세요. flags 값의 의미는 다음과 같습니다.

flag 의미
sender_unverified 수집기에 발신번호 허용목록이 없음 — 070·웹문자 등 은행 사칭 문자를 가려낼 수 없어 자동확정하지 않습니다. 허용목록을 설정하세요
sender_mobile 은행 대표번호가 아닌 개인 휴대폰 번호에서 온 문자
intl_sender 해외에서 보낸 문자([국외발신])
multi_amount 입금 금액으로 읽히는 숫자가 여러 개 (입금자명에 "입금 50000" 같은 글자를 넣은 경우)
multi_balance 잔액으로 읽히는 숫자가 여러 개 (입금자명에 "잔액" 을 넣은 경우)
name_suspicious 입금자명에 입금·출금·잔액 같은 단어나 5자리 이상 숫자가 들어 있음
amount_unlabeled "입금"·"원" 표기와 붙어 있지 않은 숫자에서 금액을 추정함
balance_gap 직전 잔액 + 입금액 ≠ 새 잔액. 출금 알림도 함께 전달하면 오탐이 줄어듭니다(출금·결제 취소 알림은 잔액이 느는 쪽으로 셉니다)
account_unmatched 문자 속 은행·계좌가 등록한 계좌와 맞지 않거나 계좌를 특정할 수 없음
possible_duplicate 같은 거래로 보이는 알림이 이미 있음 — 재전송이면 무시, 실제로 한 번 더 입금했다면 확정
time_skew 문자 속 거래 시각이 수신 시각보다 미래이거나 3일 넘게 지남

후보가 하나도 없으면 입금은 unmatched 가 됩니다. 확인 필요 입금은 콘솔, 텔레그램 1탭 승인, API로 확정하거나 무시할 수 있습니다.

예시

대기 주문 입금 판정
홍길동 50,000 홍길동 50,000 ✅ 자동확정 (정확 일치)
홍길동 50,000 · 김철수 50,000 홍길동 50,000 ✅ 자동확정 (이름이 맞는 후보가 있으면 금액만 일치하는 김철수는 후보에서 빠짐)
홍길동 50,000 · 홍길둥 50,000 홍길동 50,000 ✅ 자동확정 (100 vs 65, 20점 이상 차이)
홍길동 50,000 × 2건 홍길동 50,000 ⚠️ ambiguous
홍길동 50,000 홍길동 45,000 ⚠️ amount_mismatch
김아들 50,000 (alt: 김엄마) 김엄마 50,000 ✅ 자동확정 (대체 이름 정확 일치)
박영희 50,000 이순신 50,000 ⚠️ weak_name (금액만 일치 후보)
홍길동 3,000,000 (상한 1,000,000) 홍길동 3,000,000 ⚠️ over_limit

구매자가 알린 입금자명

결제 위젯의 '입금자명 알리기'로 구매자가 알린 이름은 확인 필요 후보를 찾는 데에만 쓰고, 그 이름만으로는 절대 자동확정하지 않습니다. 링크를 가진 사람이면 누구나 이름을 알릴 수 있기 때문입니다.

  • 주문의 depositor_name·alt_names 로 후보가 되지 못하고 금액이 같을 때만 알린 이름을 비교합니다.
  • 알린 이름으로만 맞으면 reported_name 으로 확인 필요가 되고, 같은 금액의 다른 주문도 '금액만 일치' 후보로 함께 남깁니다.
  • 다른 주문이 원래 이름으로 맞으면 그 판정이 그대로입니다. 알린 이름 후보는 목록 뒤에 붙을 뿐 경쟁 후보로 세지 않으므로, 남의 이름을 알려 다른 주문의 자동확정을 가로채거나 막을 수 없습니다.
  • 후보 사유에는 '구매자가 알린 이름'만 남고 이름 자체는 API·웹훅에 싣지 않습니다(콘솔과 알림 채널에만 표시).
대기 주문 입금 판정
이영희 43,500 · 김구매 43,500 (알린 이름: 박순자) 박순자 43,500 ⚠️ reported_name (김구매·이영희 모두 후보)
박순자 43,500 · 김구매 43,500 (알린 이름: 박순자) 박순자 43,500 ✅ 자동확정 → 박순자 주문 (알린 이름은 판정을 바꾸지 않음)

보호자·법인 입금 (alt_names)

학원·체육관·학교처럼 주문자와 입금자가 다른 업종에서는 alt_names 에 실제로 입금할 사람의 이름을 넣어 두세요. 최대 5개까지 넣을 수 있고, depositor_name 과 똑같이 모든 규칙으로 비교됩니다.

JSON
{
  "order_number": "CLASS-2026-10-0081",
  "amount": 180000,
  "depositor_name": "김민준",
  "alt_names": ["김엄마", "이아빠"],
  "customer": { "phone": "010-2222-3333" }
}

법인 입금은 (주)·주식회사 같은 표기가 자동으로 무시되므로 "depositor_name": "알파스포츠" 만 넣어도 (주)알파스포츠, 주식회사 알파스포츠 입금과 정확 일치합니다. 은행이 법인명을 잘라 보내는 경우도 잘림 규칙으로 처리됩니다.

역매칭

고객이 주문서를 작성하기 전에 먼저 입금하는 경우가 있습니다. 이 입금은 처음에 unmatched(또는 review)로 남아 있다가, 나중에 주문이 등록되는 순간 다시 대조됩니다.

  • 주문 등록 시, 최근 7일 안에 들어온 unmatched·review 입금 중 금액이 같은 것을 다시 대조합니다.
  • 조건을 만족하면 주문 등록 응답에서 이미 status: "matched" 로 돌아오고, deposit.matched 웹훅도 즉시 발송됩니다.
  • 입금 시각보다 24시간 넘게 늦게 만들어진 주문은 그 입금의 후보가 되지 않습니다.
  • 이미 review 인 입금은 방금 등록된 그 주문에만 자동확정합니다. 다른(예전) 주문 하나만 후보로 남았더라도 붙이지 않고 review 로 둡니다 — 후보가 줄어든 이유가, 가맹점이 그 입금으로 다른 주문을 직접 확정하고 그 주문을 취소했기 때문일 수 있기 때문입니다.
팁

주문 등록 응답의 status 를 확인하면, 역매칭으로 바로 결제 완료 처리할 수 있습니다. 물론 웹훅만으로 처리해도 됩니다.

계좌 격리

  • 주문에 bank_account_id 를 지정하면, 다른 계좌로 들어온 입금은 후보에서 제외됩니다. 여러 계좌를 운영할 때 권장합니다.
  • 조직·모드가 다르면 절대 매칭되지 않습니다.

텔레그램 1탭 승인

콘솔에서 텔레그램 알림방을 연결하면 확인 필요 입금마다 후보 버튼이 달린 메시지가 옵니다. 버튼을 한 번 누르면 해당 주문으로 확정되고, 웹훅이 즉시 발송됩니다. "입금 무시" 버튼으로 주문과 무관한 입금을 정리할 수도 있습니다. 누가 눌렀는지는 감사 로그와 웹훅의 data.match.actor 에 남습니다.

권장 설정

단계 설정 이유
도입 첫 1~2주 auto_confirm: false 모든 입금을 사람이 1탭으로 승인하며 매칭 품질을 눈으로 확인
안정화 auto_confirm: true, auto_max_amount: 1000000 일상적인 금액은 자동, 고액은 사람 확인
운영 업종에 맞춰 auto_max_amount 조정 평균 객단가의 몇 배 수준이 적당

auto_threshold 는 기본값 90을 권장합니다. 80으로 낮추면 3자 잘림도 자동확정되지만, 짧은 이름이 흔한 업종에서는 오확정 위험이 커집니다.