무통장입금 입금 확인 자동화 시작하기
회원가입부터 워크스페이스 생성, API 키·웹훅 설정, 계좌 등록, 주문 등록, 입금 자동 매칭, 웹훅 로그 확인까지 전체 흐름
1. 회원가입
- •이름, 이메일, 비밀번호(8~72자)를 입력하고 이메일로 회원가입합니다.
- •가입 직후에는 워크스페이스가 없는 상태입니다. 계좌·주문·입금을 관리하려면 다음 단계에서 워크스페이스를 먼저 만들어야 합니다.
2. 워크스페이스 생성
- •대시보드에 처음 접속하면 워크스페이스가 없다는 안내와 함께 워크스페이스 생성 화면을 열 수 있습니다.
- •워크스페이스 이름(필수)과 설명(선택)을 입력하고 생성을 누르면 계좌·주문·입금을 관리할 최상위 단위가 만들어집니다.
- •여러 사업이나 브랜드를 운영한다면 워크스페이스를 분리해 계좌, API 키, 웹훅을 각각 독립적으로 관리할 수 있습니다.
3. 워크스페이스 설정: API 키·웹훅 등록
- •설정의 API 키 카드에서 API 키를 발급합니다. 이 키는 로그인으로 발급되는 사용자 access token과는 별개이며, 외부 연동 전용(v1 /orders, /bank-accounts, v2 /deposits, /orders, /matches 등)입니다. 대시보드 화면 자체는 계속 사용자 access token으로 동작합니다.
- •API 키를 재발급하면 기존 키는 즉시 폐기되고, 그 키로 서명하던 아웃바운드 웹훅 HMAC 서명도 함께 바뀝니다. 연동 중인 서비스가 있다면 새 키를 반영할 때까지 인증과 웹훅 서명 검증이 함께 실패할 수 있습니다.
- •웹훅 설정 카드에 입금 매칭 결과를 받을 URL을 등록합니다. deposit.matched(입금-주문 매칭 완료), order.expired(입금 기한 초과로 대기 주문 취소) 이벤트가 이 URL로 전송되며, 발송 이력과 실패 건 재전송은 웹훅 로그 메뉴에서 확인합니다.
- •API 키는 절대 외부에 노출하지 마세요. 대시보드/워크스페이스 조회는 사용자 access token, 외부 시스템 연동은 워크스페이스 API 키로 역할이 분리되어 있으므로 둘을 혼용하지 않아야 합니다.
4. 계좌 등록
- •계좌 관리에서 계좌 추가를 눌러 은행을 선택하고 계좌번호와 예금주를 입력합니다.
- •등록 방식은 은행마다 다릅니다. 계좌 인증 없이 SMS 알림만 연결하는 은행(하나 081, 우체국 071), 계좌 등록 후 은행 SMS 인증번호 확인이 필요한 은행(IBK기업 003, 신한 088, NH농협 011, 우리 020), SMS 연동이 아니라 빠른계좌조회 자격정보로 등록하는 KB국민은행(004)이 있습니다.
- •SMS로 연동하는 은행은 계좌 등록 후 화면에 표시되는 그 계좌 전용 SMS 수신번호로 은행 앱의 입금 알림 수신번호를 바꿔야 합니다. 수신번호는 계좌마다 다르게 배정될 수 있으므로 항상 등록 화면에 표시된 번호를 그대로 사용하세요.
- •계좌를 등록한 것만으로는 입금 알림이 시작되지 않습니다. 은행에 맞는 SMS 알림·계좌 인증·빠른계좌조회 설정을 모두 마쳐야 입금 SMS(또는 빠른계좌조회 결과)가 LunePay로 전달됩니다. 설정이 끝나지 않은 상태로 다음 단계(주문 등록)를 진행해도 자동 매칭은 이루어지지 않으므로, 아래 링크에서 해당 은행 설정을 먼저 완료하세요.
5. 주문 등록
- •주문 관리에서 주문 추가를 눌러 금액과 입금자명을 입력합니다. 주문번호와 메모는 선택 항목입니다.
- •외부 서비스에서 자동으로 주문을 만들려면 대시보드 대신 워크스페이스 API 키로 POST /orders(v1) 또는 POST /api/v2/orders를 호출하고, 재시도 안전성을 위해 Idempotency-Key 헤더를 함께 보내세요.
- •자동 매칭은 금액과 입금자명을 함께 확인합니다. 주문의 입금자명은 실제 입금 시 사용할 이름과 정확히 같게 입력하고, 같은 워크스페이스에서 동시에 대기 중인 주문끼리 금액+입금자명 조합이 겹치지 않게 관리하세요. 지원 은행 SMS가 입금자명 위치에 정확히 8자리 숫자를 표시하는 경우 이 숫자도 입금자명으로 인식되므로, 그 값을 오탈자 없이 그대로 입력해야 합니다.
6. 입금 확인 및 자동 매칭
- •SMS로 연동된 계좌(농협·우리·하나·우체국·신한·기업은행)는 입금 알림 SMS가 도착하면 금액과 입금자명을 기준으로 자동 매칭을 시도합니다.
- •KB국민은행(004)은 SMS가 아니라 빠른계좌조회 방식으로 기본 30분 간격으로 입금 내역을 조회하며, 은행 응답 상황에 따라 더 지연될 수 있습니다. 매칭까지 걸리는 시간은 은행과 조회 방식에 따라 다르며, 모든 계좌에서 즉시 매칭이 이루어지는 것은 아닙니다.
- •자동 매칭은 금액과 입금자명이 모두 맞아야 이루어집니다. 금액이 같은 대기 주문이 여러 건이면 입금자명이 정확히 일치(또는 유사)하는 주문을 찾아 매칭하며, 일치하는 이름이 없으면 금액만으로는 자동 매칭되지 않습니다. 이런 입금은 입금 내역에서 수동매칭으로 직접 연결하거나, 잘못 매칭된 건은 매칭해제로 되돌릴 수 있습니다.
7. 웹훅 로그 확인
- •웹훅 로그의 발송 내역에서 상태(성공/실패/대기), 응답코드, 재시도 횟수, 발송·완료 시간을 확인할 수 있습니다.
- •실패한 발송은 목록에서 재전송할 수 있으며, 재전송에도 이벤트 ID(X-LunePay-Event-Id)는 최초 발송과 동일하게 유지되므로 수신 서버는 이 값으로 중복 처리를 방지해야 합니다.
- •타임아웃이나 오류 응답은 30초·2분·10분 뒤 자동 재시도되며, 최초 발송을 포함해 최대 4회까지 시도합니다.