AutoTransPay 의 API 는 세 가지 객체로 이루어져 있습니다. 주문(가맹점이 등록), 입금(은행 알림에서 생성), 이벤트(상태 변화 기록, 웹훅으로 전달).
주문 (order)
고객이 무통장입금으로 결제하겠다고 한 건입니다. 가맹점이 POST /api/v1/orders로 등록합니다.
| 필드 | 타입 | 설명 |
|---|---|---|
id |
string (uuid) | 주문 ID |
object |
"order" |
객체 종류 |
livemode |
boolean | true = 운영, false = 테스트 |
order_number |
string | 가맹점 주문번호. 조직·모드 안에서 유일 |
amount |
integer | 입금해야 할 금액(원) |
currency |
"KRW" |
통화 (원화만 지원) |
depositor_name |
string | 고객이 입력한 입금자명 |
alt_names |
string[] | 대체 입금자명(보호자·법인명 등, 최대 5개) |
customer |
object | { phone, email } — 휴대폰 뒷자리 매칭에 쓰입니다 |
bank_account_id |
string | null | 지정 시 이 계좌로 들어온 입금만 매칭 |
status |
string | pending · matched · canceled · expired |
expires_at |
string | null | 만료 시각(ISO 8601) |
matched_at |
string | null | 매칭 확정 시각 |
match_method |
string | null | auto · manual |
deposit_id |
string | null | 매칭된 입금 ID |
metadata |
object | 가맹점 임의 데이터 (웹훅에 그대로 실려 옴) |
created_at |
string | 생성 시각 |
widget_url |
string | null | 구매자 입금 안내 화면 주소 → 결제 위젯. 위젯이 꺼져 있으면 null |
입금 (deposit)
수집기가 올린 은행 알림을 해석해 만든 입금 1건입니다. 같은 알림이 여러 경로로 와도 한 건으로 합쳐집니다(중복 제거). 잔액이 적히지 않은 알림은 같은 사람이 같은 금액을 두 번 보낸 실제 입금일 수 있어, 다른 휴대폰·다른 원문으로 겹치면 버리지 않고 possible_duplicate 플래그를 달아 사람 확인으로 올립니다.
| 필드 | 타입 | 설명 |
|---|---|---|
id |
string (uuid) | 입금 ID |
object |
"deposit" |
객체 종류 |
livemode |
boolean | 운영/테스트 |
amount |
integer | 입금액(원) |
depositor_name |
string | 은행 알림에 찍힌 입금자명. 읽지 못하면 빈 문자열(자동확정 안 됨) |
bank_code |
string | null | 은행 코드 (WOORI, KB …) → 지원 은행 |
bank_account_id |
string | null | 입금된 계좌 |
occurred_at |
string | null | 알림에 적힌 거래 시각 |
received_at |
string | 서버 수신 시각 |
status |
string | unmatched · review · matched · ignored |
review_reason |
string | null | 확인 필요 사유 → 판정 표 |
order_id |
string | null | 매칭된 주문 ID |
candidates |
object[] | 후보 주문 (최대 5개, 점수순) |
confidence |
number | 알림 해석 확신도 0~1 |
flags |
string[] | 주의 신호 (balance_gap, account_ambiguous) |
created_at |
string | 생성 시각 |
candidates[] 의 각 항목은 order_id, order_number, depositor_name, amount, score(0~100), amount_match, reasons 를 가집니다.
이벤트 (event)
주문·입금의 중요한 상태 변화가 생길 때마다 이벤트가 하나 기록되고, 구독 중인 웹훅 엔드포인트로 전송됩니다.
| 이벤트 | 발생 시점 |
|---|---|
deposit.matched |
입금이 주문에 확정됨 (자동 또는 수동) |
deposit.review_required |
사람 확인이 필요한 입금이 들어옴 |
order.expired |
주문이 expires_at 을 지나 만료됨 |
이벤트 ID 는 evt_ 로 시작합니다. 웹훅이 유실되었을 때는 이벤트 API로 다시 조회할 수 있습니다.
상태 전이
주문
| 현재 | 다음 | 조건 |
|---|---|---|
pending |
matched |
입금이 자동 확정되거나 수동 매칭됨 |
pending |
expired |
expires_at 경과 (order.expired 이벤트) |
pending |
canceled |
주문 취소 API |
expired |
matched |
만료 뒤 들어온 입금을 사람이 확정 (자동확정은 하지 않음) |
expired |
canceled |
주문 취소 API |
matched |
canceled |
가맹점이 웹훅에 409·410·422 로 거절한 경우에만 |
matched 주문은 API 로 취소할 수 없습니다(409 order_already_matched).
입금
| 현재 | 다음 | 조건 |
|---|---|---|
| (수신) | matched |
자동확정 조건을 모두 충족 |
| (수신) | review |
후보가 있지만 확실하지 않음 → deposit.review_required |
| (수신) | unmatched |
대기 주문 중 후보가 없음 |
unmatched · review |
matched |
수동 매칭, 또는 나중에 등록된 주문과 역매칭 |
unmatched · review |
ignored |
입금 무시 (주문과 무관한 입금) |
matched |
review |
가맹점이 웹훅을 거절 (review_reason: merchant_rejected) |
테스트 모드와 운영 모드
API 키의 접두사가 모드를 결정합니다. 두 모드의 데이터는 완전히 분리되어 서로 보이지 않고 절대 매칭되지 않습니다.
테스트 (atp_test_) |
운영 (atp_live_) |
|
|---|---|---|
| 주문·입금·이벤트 | 테스트 데이터만 | 운영 데이터만 |
| 입금 발생 방법 | 샌드박스 API | 실제 은행 알림(수집기) |
| 웹훅 엔드포인트 | 테스트용 따로 등록 | 운영용 따로 등록 |
| 과금 | 무료·무제한 | 월 매칭 완료 건수 기준 |
수집기(휴대폰)로 들어오는 실제 입금은 항상 운영 모드 입금입니다. 테스트 모드에서 입금을 만들려면 샌드박스 API 를 쓰세요.
멱등성
네트워크는 실패합니다. AutoTransPay 는 재시도해도 안전하도록 설계되어 있습니다.
- 주문 등록 —
order_number가 멱등 키입니다. 같은 번호·같은 금액·같은 입금자명으로 다시 보내면 새로 만들지 않고 기존 주문을200으로 돌려줍니다(최초 생성은201). 금액이나 입금자명이 다르면409 order_number_conflict입니다. 주문 내용이 바뀌었다면 기존 주문을 취소하고 새 주문번호로 등록하세요. - 주문 취소 — 이미 취소된 주문을 다시 취소해도 오류 없이 현재 주문을 돌려줍니다.
- 입금 수신 — 같은 은행 알림이 여러 수집기·여러 번 들어와도 한 건만 생성됩니다.
- 웹훅 — 전송은 최소 한 번(at-least-once) 입니다. 같은 이벤트가 두 번 이상 올 수 있으니
AutoTransPay-Event-Id로 중복을 걸러 주세요 → 멱등 처리.
조직 설정
콘솔 → 설정에서 매칭 동작을 조정할 수 있습니다.
| 설정 | 기본값 | 설명 |
|---|---|---|
auto_confirm |
true |
false 면 확실한 매칭도 모두 사람 확인(manual_mode)으로 |
auto_threshold |
90 |
자동확정 최소 이름 점수 (80~100) |
auto_max_amount |
없음 | 이 금액을 넘는 입금은 자동확정하지 않음(over_limit) |
order_ttl_hours |
없음 | expires_at 을 주지 않은 주문의 기본 만료 시간 |
lookback_days |
30 |
입금과 대조할 대기 주문의 조회 범위(일, 최대 90) |