무통장입금 자동확인 만들기

2026. 11. 18. · 82bank

무통장입금을 받는 쇼핑몰은 하루에도 몇 번씩 은행 앱을 열어 입금자명과 금액을 주문 목록과 맞춰 봅니다. 82bank 의 자동입금확인은 이 일을 대신합니다. 상점이 주문을 등록해 두면, 82bank 가 계좌에서 새 입금을 수집할 때마다 맞는 주문을 찾아 붙이고 상점 서버에 알려 줍니다. 이 글은 상점 서버 쪽에서 무엇을 만들어야 하는지 순서대로 설명합니다.

준비: 상점과 계좌

관리 화면 [상점관리]에서 상점을 하나 만듭니다. 이때 정하는 것은 세 가지입니다. 상점 이름, 입금이 붙었을 때 82bank 가 호출할 콜백 주소, 그리고 주문을 얼마 동안 기다릴지 정하는 매칭 기한(기본 72시간)입니다. 상점을 만들면 상점 id(shp_…)와 콜백 서명용 시크릿이 나옵니다. 입금을 받는 계좌는 [계좌관리]에 등록되어 있어야 하고, 수집 주기가 짧을수록 확인도 빨라집니다. 10분 주기면 보통 입금 뒤 10분 남짓 안에 확인됩니다.

1. 주문이 생기면 등록

고객이 무통장입금으로 주문하면 상점 서버가 POST /v1/orders 를 부릅니다. 주문번호(100자 이하), 입금자명(50자 이하), 금액이 필요합니다. 상점이 하나뿐이면 shopId 는 생략해도 되고, 둘 이상이면 넣어야 합니다.

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" }'

expiresAt 을 생략하면 상점에 정한 기한이 적용됩니다. 성공하면 201 과 함께 등록된 주문(status: "waiting")이 옵니다. 같은 상점에서 같은 주문번호를 다시 등록하면 409 ORDER_EXISTS 가 오니, 재시도 코드에서는 이것을 "이미 등록됨"으로 다루면 됩니다.

2. 82bank 가 맞춰 보는 규칙

새 입금이 저장되면 같은 가입 단위의 waiting 주문 중에서 다음을 모두 만족하는 주문을 찾습니다.

후보가 정확히 하나일 때만 자동으로 붙입니다. 같은 이름, 같은 금액의 주문이 둘이면 어느 쪽인지 알 수 없으니 아무 쪽에도 붙이지 않고, 그 입금을 관리 화면 [매치작업]에 후보 두 개와 함께 올립니다. 사람이 하나를 골라 [매칭]하거나 [제외]합니다. 잘못 붙는 것보다 사람에게 묻는 편이 낫다고 보고 이렇게 정했습니다.

주문보다 입금이 먼저 들어오는 경우도 있습니다. 이때 주문 등록 직전 10분 안에 들어온 입금은 자동으로 붙지만(고객이 주문과 거의 동시에 보낸 경우), 그보다 앞선 입금은 자동으로 붙이지 않습니다. 예전에 다른 일로 들어온 같은 이름·같은 금액의 입금이 새 주문에 붙으면 돈을 받지 않고 물건을 보내게 되기 때문입니다. 대신 그 입금을 [매치작업]에 후보로 올려 사람이 입금일시를 보고 고르게 합니다. 계좌를 지웠다가 다시 등록해 옛 입금이 다시 들어와도 마찬가지입니다. 비밀계좌로 표시한 계좌의 입금과 출금은 매칭에 쓰지 않습니다.

[매치작업]에서 붙인 매칭을 풀면 상점 콜백과 웹훅으로 order.unmatched 를 보내고 주문은 다시 waiting 이 됩니다. 이미 발송을 준비했다면 이 알림을 받아 멈추세요.

3. 콜백 받기

주문에 입금이 붙으면(자동이든 [매치작업]에서 사람이 골랐든) 상점 콜백 주소로 다음 본문이 POST 됩니다. 웹훅과 달리 본문에 알림 id 가 없으니, 중복은 orderNo 로 거릅니다.

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": "타행이체" }
}

콜백을 받은 서버는 먼저 X-82bank-Signature 를 상점 콜백 시크릿으로 검증하고, 주문을 결제 완료로 바꾸고, 10초 안에 2xx 로 답합니다. 답이 없거나 2xx 가 아니면 1분, 5분, 30분, 2시간, 12시간 뒤에(5분마다 도는 작업이 그 시각 뒤에) 다시 보내고, 6번 실패하면 멈춥니다. 그래서 같은 콜백이 두 번 올 수 있습니다. 이미 결제 완료인 주문이면 아무것도 하지 않고 200 을 주면 됩니다.

// 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();
});

서명 계산 방법은 웹훅과 같고, 자세한 설명은 웹훅 받고 서명 검증하기에 있습니다.

4. 취소와 확인

고객이 입금 전에 주문을 취소하면 DELETE /v1/orders/{orderNo} 로 취소해 두세요(상점이 둘 이상이면 ?shopId= 를 붙입니다. 하나뿐이면 생략해도 됩니다). 남겨 두면 같은 이름·금액의 다른 주문과 겹쳐 자동으로 붙지 않는 원인이 됩니다. 이미 입금이 붙은 주문은 409 ALREADY_MATCHED 로 취소되지 않습니다. 콜백을 놓쳤는지 의심되면 GET /v1/orders/{orderNo} 로 상태(waiting·matched·expired·canceled)를 확인할 수 있습니다. 기한이 지난 주문은 자동으로 expired 가 됩니다.

시험해 보기

입금을 받는 계좌를 등록해 두고, 내 이름과 작은 금액(예: 1,000원)으로 주문을 등록한 뒤 다른 내 계좌에서 그 이름·금액으로 입금합니다. 관리 화면에서 그 계좌의 [지금 수집]을 누르면 주문이 matched 로 바뀌고 콜백이 갑니다. 같은 이름·금액 주문을 두 개 넣어 두면 [매치작업]에 뜨는 것도 확인할 수 있습니다.

다른 글