자동입금확인 가이드

독립몰·자체 주문 시스템용 · 2026년 11월 18일

무통장입금 주문을 82bank 에 등록해 두면, 계좌에서 새 입금이 수집될 때마다 입금자명과 금액이 같고, 주문을 만든 뒤 기한 안에 들어온 입금을 주문에 붙이고 상점 서버에 알려 줍니다. 상점 서버에서 할 일은 주문 등록과 콜백 받기 두 가지입니다.

입금을 받는 계좌가 [계좌관리]에 등록되어 있어야 합니다. 확인 속도는 그 계좌의 수집 주기(결제 뒤 최소 10분, 무료 체험 중 1시간)를 따릅니다. 비밀계좌로 표시한 계좌의 입금은 매칭에 쓰지 않습니다.

1. 상점 만들기

관리 화면 [상점관리]에서 상점 이름, 콜백 주소, 매칭 기한(1~720시간, 기본 72시간)을 정합니다. 상점 id(shp_…)와 콜백 시크릿이 만들어집니다. 콜백 주소는 웹훅과 같은 규칙입니다: https:// 만, IP 주소·localhost·내부 이름·82bank 자신의 주소는 받지 않습니다. 상점이 하나뿐이면 API 에서 shopId 를 생략할 수 있습니다.

2. 주문 등록 POST /v1/orders

curl -X POST https://82bank.app/v1/orders \
  -H "Authorization: Bearer bk_…:sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "orderNo": "A20261118-0012",
        "depositorName": "홍길동", "amount": 32000,
        "expiresAt": "2026-11-21T00:00:00Z" }'

응답은 201 과 { "success": true, "order": { … } } 입니다. orderNo 는 100자, depositorName 은 50자까지입니다. 같은 상점에서 같은 orderNo 를 다시 등록하면 409 ORDER_EXISTS 입니다. 등록할 때 이미 들어온 미매칭 입금과도 맞춰 보지만, 자동으로 붙는 것은 등록 직전 10분 안의 입금뿐이고 그보다 앞선 입금은 [매치작업] 후보로만 올립니다.

3. 맞추는 규칙

항목규칙
금액정확히 같아야 합니다 (1원 차이도 안 붙음)
입금 시각은행 거래 시각이 주문 생성 10분 전 이후인 입금만 자동으로 붙음(예전 입금이 새 주문에 붙지 않게). 시각을 주지 않는 은행(00:00:00)은 날짜로 비교. 그보다 앞선 입금은 [매치작업] 후보
기한은행 거래 시각이 주문의 expiresAt(없으면 상점 기한) 안인 입금만. 기한이 지나면 주문은 expired 가 되지만, 수집이 늦었을 뿐 기한 안에 입금했으면 나중에 들어와도 붙고 matched 가 됩니다
이름공백·괄호 안 글자·(주)·주식회사를 빼고, 전각은 반각으로 바꿔 비교. 같거나, 입금자 이름이 주문 이름의 앞부분이고 3자 이상이면 같은 이름(은행이 입금자 이름을 잘라 주는 경우). 예: 주문 홍길동 = 입금 홍길동(상점), 주문 주식회사가나다라 = 입금 가나다. 입금자 이름이 더 길면 다른 사람으로 봅니다
후보 수정확히 하나면 자동 매칭. 둘 이상이면 붙이지 않고 [매치작업]에 후보와 함께 올림. 없으면 그대로 둠

4. 콜백 받기

매칭되면(자동이든 [매치작업]에서 사람이 골랐든) 상점 콜백 주소로 POST 합니다. 본문은 웹훅과 달리 id 없이 { "event": "order.matched", …내용 } 한 단계입니다. X-82bank-Signature 를 상점 콜백 시크릿으로 검증하고 10초 안에 2xx 로 답하세요. 실패하면 웹훅과 같이 1분·5분·30분·2시간·12시간 뒤에(5분마다 도는 작업이 그 시각 뒤에) 다시 보내고 6번 실패하면 멈추므로, orderNo 로 이미 처리한 주문인지 보고 그냥 200 을 주면 됩니다. 같은 내용은 웹훅 order.matched 이벤트로도 받을 수 있습니다.

POST (상점에 등록한 콜백 주소)
Content-Type: application/json
X-82bank-Event: order.matched
X-82bank-Signature: (본문을 상점 콜백 시크릿으로 HMAC-SHA256 한 16진수)

{
  "event": "order.matched",
  "orderNo": "A20261118-0012",
  "amount": 32000,
  "depositorName": "홍길동",
  "matchedAt": "2026-11-18T03:41:09Z",
  "transaction": { "id": "tx_…", "date": "2026-11-18", "time": "12:40:51",
                   "amount": 32000, "counterparty": "홍길동", "description": "타행이체" }
}

서명 검증 (Node.js)

// Node.js + Express — 상점 콜백. 본문에 id 가 없으므로 orderNo 로 중복을 거른다
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.BANK82_CALLBACK_SECRET; // [상점관리]의 콜백 시크릿

app.post("/shop/callback", express.raw({ type: "application/json" }), async (req, res) => {
  const got = req.get("X-82bank-Signature") || "";
  const want = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const same = got.length === want.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
  if (!same) return res.status(401).end();

  const evt = JSON.parse(req.body.toString("utf8"));
  // 이미 결제 완료인 주문이면 아무것도 하지 않는다 (재시도로 같은 콜백이 다시 올 수 있다)
  await markPaidIfWaiting(evt.orderNo, evt.amount, evt.transaction.id);
  res.status(200).end();
});

5. 매치작업

같은 이름·금액의 주문이 둘 이상이거나, 주문보다 먼저 들어온 입금, 맞는 주문이 없는 입금은 관리 화면 [매치작업]에 모입니다. 입금일시와 주문 시각을 보고 후보 주문을 골라 [매칭]하면 콜백이 가고, 주문과 상관없는 입금은 [제외]합니다. 잘못 붙였다면 매칭을 풀 수 있고, 그때 상점 콜백으로 { "event": "order.unmatched", … } 가 갑니다(주문은 다시 waiting). 이미 발송을 준비했다면 멈추세요.

6. 주문 취소와 확인

입금 전에 취소된 주문은 DELETE /v1/orders/{orderNo} 로 취소해 두세요(상점이 둘 이상이면 ?shopId=). 남아 있으면 같은 이름·금액의 다른 주문이 자동으로 붙지 않습니다. 이미 입금이 붙은 주문은 409 ALREADY_MATCHED 로 취소되지 않습니다. 콜백을 놓쳤다면 GET /v1/orders/{orderNo} 로 상태를 확인합니다.

시험해 보기

  1. 입금을 받는 계좌(예: 신한은행 간편조회서비스 계좌)를 등록하고 상점을 만듭니다.
  2. POST /v1/orders 로 내 이름과 작은 금액(예: 1000) 주문을 등록합니다.
  3. 다른 내 계좌에서 그 이름·금액으로 입금한 뒤 관리 화면에서 그 계좌의 [지금 수집]을 누릅니다.
  4. 주문이 matched 가 되고 콜백이 오는지 확인합니다. 같은 이름·금액 주문을 하나 더 넣어 두면 [매치작업]에 뜨는 것도 확인할 수 있습니다.

더 긴 설명은 블로그 글 무통장입금 자동확인 만들기에 있습니다.