은행 알림의 입금자명은 주문서에 적힌 이름과 자주 어긋납니다. 은행이 글자수를 잘라 보내고, 동명이인을 구분하려고 휴대폰 뒷자리를 붙이고, 외국인은 이름 순서가 뒤바뀌고, 부모가 대신 입금합니다. 스마트매칭은 이런 차이를 흡수하면서도 확실할 때만 자동으로 확정하고, 애매하면 사람에게 후보를 보여주는 것을 원칙으로 합니다.
이름 비교 규칙
비교 전에 양쪽 이름을 정규화합니다: 유니코드 정규화(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순위 후보의 이름 점수가 90점 이상 (조직 설정
auto_threshold) - 경쟁 후보가 없음 — 금액이 같고 1순위와 20점 이내인 다른 후보가 없어야 함
- 은행 알림 해석 확신도(
confidence)가 0.7 이상 - 입금액이 자동확정 금액 상한 이하 (
auto_max_amount를 설정한 경우) - 주문이 만료되지 않음
- 조직 설정에서 자동확정이 켜져 있음 (
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 과 똑같이 모든 규칙으로 비교됩니다.
{
"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자 잘림도 자동확정되지만, 짧은 이름이 흔한 업종에서는 오확정 위험이 커집니다.