시작하기

핵심 개념

AutoTransPay 의 핵심 개념입니다. 주문·입금·이벤트 객체와 상태 전이, 테스트 모드와 운영 모드의 차이, 멱등성, 조직 설정을 설명합니다.

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)