82bank API 문서
은행 계좌의 입출금 내역을 바로 조회하거나, 82bank 가 주기적으로 모아 둔 저장 내역을 가져가고, 쇼핑몰 주문을 등록해 입금을 자동으로 확인하는 API 입니다. 새 입금·출금은 웹훅으로 받을 수 있습니다.
SH, 간편조회서비스 이용자 ID 로그인)을 누구나 쓸 수 있습니다. 농협·하나은행(빠른조회)도 누구나 쓸 수 있습니다. 국민·우리은행은 시험 중, 기업은행은 준비 중입니다(지원 은행). 관리 화면에서 계좌를 먼저 등록한 뒤 API 를 부르세요. 처음 시험하는 순서는 API 테스트에 있습니다.시작하기
| 주소 | https://82bank.app/v1 |
|---|---|
| 인증 | 모든 요청에 Authorization: Bearer {API 키}:{시크릿} 헤더. API 키는 bk_ + 16진수 24자, 시크릿은 sk_ + 16진수 48자입니다. 관리 화면 API 키에서 소유자가 만들고, 시크릿은 만들 때 한 번만 보입니다. |
| 형식 | 요청·응답 모두 JSON (UTF-8). POST 는 Content-Type: application/json |
| 날짜 | 실시간 조회 기간 startDate·endDate 는 YYYYMMDD(한국 날짜). 저장 내역의 from·to 는 YYYY-MM-DD 와 YYYYMMDD 둘 다 받습니다. 거래의 date·time 은 한국 시각, createdAt 같은 기록 시각은 UTC ISO 8601(2026-11-18T05:00:00Z) |
| 금액 | 원 단위 정수 |
| 실패 응답 | 4xx·5xx 는 { "success": false, "code": "…", "message": "…", "error": "…" }(error 는 message 와 같음). 은행 쪽 실패는 HTTP 200 에 { "success": false, "code", "message" } 만 옵니다. code 로 판단하고 message 는 사람에게 보여 줄 설명입니다 |
curl -H "Authorization: Bearer bk_여기에_API_키:sk_여기에_시크릿" https://82bank.app/v1/ping
호출 한도와 이용 기간
- API 키 하나당 30분에 60회(기본값).
/v1/ping을 포함한 모든/v1호출이 셉니다. 넘으면429 TOO_MANY_REQUESTS와 함께 본문에retryAfterSec, 헤더에Retry-After(초)가 옵니다. - 은행에 바로 가는 실시간 조회(
/v1/transactions,/v1/transactions/login)와/v1/accounts/{id}/refresh는 같은 계좌 5분에 1회. 넘으면429 ACCOUNT_COOLDOWN. - 계좌 잠김 방지: 실제 은행에서 같은 은행·계좌번호로 인증정보 오류가 연달아 2번 나면(어느 가입 단위에서 났든) 그 계좌번호로는 은행에 더 보내지 않습니다(
429 VERIFY_LIMIT). 성공하면 풀리고, 그 계좌를 등록한 가입 단위는 24시간 뒤 한 번 더 시도할 수 있습니다. 새 계좌 등록 확인은 인증정보 오류가 한 번이라도 있던 계좌번호·이용자 ID 로는 보내지 않고, 가입 단위마다 하루 10번까지입니다. 은행이 저장된 인증정보를 거절한 계좌는 수집이 멈추고/v1/accounts/{id}/refresh가409 CREDENTIAL_BLOCKED입니다(관리 화면에서 새 인증정보를 저장하면 풀립니다). - 저장 내역 조회는 은행에 가지 않으므로 계좌 제한이 없습니다. 자주 확인해야 한다면 저장 내역이나 웹훅을 쓰세요.
- 이용 기간이 끝나면
/v1/ping말고는 모두402 PAYMENT_REQUIRED입니다(호출 수는 그래도 셉니다). 저장된 자료는 지우지 않습니다.
연결 확인 GET /v1/ping
키가 맞는지만 확인합니다. 응답: { "success": true, "pong": true }
실시간 조회 POST /v1/transactions
요청할 때 은행에 가서 그 기간의 거래를 받아 옵니다. 결과는 저장하지 않습니다(계좌를 등록해 두면 저장 내역은 따로 쌓입니다). 계좌 비밀번호로 조회하는 은행(mode: "account")에 씁니다. stage 가 ready 인 은행만 부를 수 있습니다. 실제 은행은 이 가입 단위가 관리 화면에서 먼저 등록한(은행 확인을 통과한) 계좌만 조회할 수 있습니다(아니면 400 ACCOUNT_NOT_REGISTERED) — 남의 계좌번호에 틀린 비밀번호를 넣어 계좌를 잠그지 못하게 하려는 것입니다. 지금 이 방식으로 열린 은행은 농협(NH)·하나(HN)입니다(국민·우리 시험 중, 기업 준비 중). 신한은행은 아래 로그인 방식 조회를 씁니다.
| 항목 | 설명 |
|---|---|
bankCode | 은행 코드 (은행 목록). 계좌번호 방식 은행(mode: "account") |
accountType | personal(개인) 또는 business(사업자). 생략하면 personal. 은행이 받지 않는 유형이면 INVALID_ACCOUNT_TYPE |
accountNumber | 계좌번호 (- 는 빼고 씁니다) |
accountPassword | 계좌 비밀번호 |
residentNumber | 계좌번호 방식 은행(농협·국민·우리·기업)만 받습니다. 개인은 생년월일 6자리(YYMMDD), 사업자는 사업자등록번호 10자리. 하이픈·공백은 지우고 받습니다. 자릿수나 사업자등록번호 검증 숫자가 틀리면 은행에 보내지 않고 400 INVALID_BIRTH_DATE / INVALID_BUSINESS_NUMBER |
startDate · endDate | 조회 기간 YYYYMMDD, 시작일이 종료일보다 늦으면 안 됩니다 |
sortOrder | 선택. asc(기본, 오래된 순) 또는 desc(최신 순) |
curl -X POST https://82bank.app/v1/transactions \
-H "Authorization: Bearer bk_여기에_API_키:sk_여기에_시크릿" \
-H "Content-Type: application/json" \
-d '{
"bankCode": "KB",
"accountType": "personal",
"accountNumber": "123456789012",
"accountPassword": "1234",
"residentNumber": "900101",
"startDate": "20261111",
"endDate": "20261118"
}'
성공 응답 (accountHolder 는 은행이 알려 줄 때만 있습니다):
{
"success": true,
"accountInfo": { "accountNumber": "123456789012", "balance": 1254000, "accountHolder": "홍길동" },
"transactions": [
{
"date": "2026-11-18", "time": "09:12:40",
"type": "deposit", "amount": 55000, "balance": 1254000,
"description": "타행이체", "counterparty": "김민수",
"memo": "", "branch": ""
}
]
}
| 거래 항목 | 설명 |
|---|---|
date · time | 거래 날짜 YYYY-MM-DD · 시각 HH:MM:SS (한국 시각) |
type | deposit(입금) · withdrawal(출금) |
amount · balance | 거래 금액 · 거래 뒤 잔액 (원) |
description · counterparty | 적요 · 보낸 분(받는 분) 이름. 은행이 주는 대로 옮기며, 은행에 따라 이름이 잘려 올 수 있습니다 |
memo · branch | 은행 메모 · 거래 지점 (없으면 빈 문자열) |
은행이 조회를 거절하거나 응답하지 않으면 HTTP 상태는 200 이고 본문의 success 가 false 입니다. 요청 형식 오류(400)·인증 오류(401)·한도 초과(429)와 구분하세요.
HTTP/1.1 200 OK
{ "success": false, "code": "BANK_REJECTED", "message": "계좌 정보가 올바르지 않습니다." }
Node.js
// Node.js 18 이상 (fetch 내장)
const KEY = process.env.BANK82_KEY; // bk_…
const SECRET = process.env.BANK82_SECRET; // sk_…
const res = await fetch("https://82bank.app/v1/transactions", {
method: "POST",
headers: {
"Authorization": "Bearer " + KEY + ":" + SECRET,
"Content-Type": "application/json",
},
body: JSON.stringify({
bankCode: "KB",
accountType: "personal",
accountNumber: "123456789012",
accountPassword: "1234",
residentNumber: "900101",
startDate: "20261111",
endDate: "20261118",
}),
});
const data = await res.json();
if (res.status === 429) {
console.log("잠시 뒤 다시:", data.retryAfterSec, "초");
} else if (!data.success) {
console.log("실패:", res.status, data.code, data.message);
} else {
for (const t of data.transactions) {
console.log(t.date, t.time, t.type, t.amount, t.counterparty);
}
}
Python
# Python 3 + requests
import os, requests
KEY = os.environ["BANK82_KEY"] # bk_…
SECRET = os.environ["BANK82_SECRET"] # sk_…
res = requests.post(
"https://82bank.app/v1/transactions",
headers={"Authorization": "Bearer " + KEY + ":" + SECRET},
json={
"bankCode": "KB",
"accountType": "personal",
"accountNumber": "123456789012",
"accountPassword": "1234",
"residentNumber": "900101",
"startDate": "20261111",
"endDate": "20261118",
},
timeout=90,
)
data = res.json()
if res.status_code == 429:
print("잠시 뒤 다시:", data["retryAfterSec"], "초")
elif not data["success"]:
print("실패:", res.status_code, data["code"], data["message"])
else:
for t in data["transactions"]:
print(t["date"], t["time"], t["type"], t["amount"], t["counterparty"])
로그인 방식 조회 POST /v1/transactions/login
이용자 ID·비밀번호로 로그인해 조회하는 은행(mode: "login")용입니다. 지금 이 방식은 신한은행(SH, 간편조회서비스)이며 누구나 쓸 수 있습니다. 다른 은행 코드는 400 INVALID_BANK_CODE 입니다. /v1/transactions 에 이 은행을 보내면 400 USE_LOGIN_ENDPOINT 입니다.
조회할 수 있는 것은 관리 화면에서 먼저 등록(은행 확인 통과)했고 인증정보 오류로 멈추지 않은 계좌뿐입니다. accounts 의 모든 계좌가 그렇고, loginId 가 등록할 때 넣은 이용자 ID 와 같아야 합니다. 하나라도 어긋나면 아무것도 조회하지 않고 400 ACCOUNT_NOT_REGISTERED 로 답하며, 어느 쪽이 틀렸는지는 알려 주지 않습니다. loginId 는 공백 없이 4~20자(INVALID_LOGIN_ID), loginPassword 는 1~64자이고 앞뒤 공백도 비밀번호로 그대로 씁니다. accounts 는 1~10개이며 계좌마다 accountNumber 와 accountPassword 가 필요하고, 결과는 계좌마다 따로 옵니다.
은행 로그인 비밀번호를 틀리면 은행 계정이 잠길 수 있습니다. 같은 이용자 ID 로 은행이 비밀번호 오류를 연달아 2번 거절하면, 계좌번호와 상관없이 그 ID 로는 은행에 더 보내지 않고 VERIFY_LIMIT 으로 답합니다. 계좌를 새로 등록할 때는 그 ID 에 오류가 한 번이라도 있으면 보내지 않습니다.
{
"bankCode": "SH",
"loginId": "간편조회서비스 이용자 ID",
"loginPassword": "간편조회서비스 비밀번호",
"accounts": [
{ "accountNumber": "110012345678", "accountPassword": "1234" },
{ "accountNumber": "110098765432", "accountPassword": "5678" }
],
"startDate": "20261111",
"endDate": "20261118",
"sortOrder": "asc"
}
응답의 success 는 모든 계좌가 성공했을 때만 true 입니다. 5분 안에 다시 조회한 계좌는 HTTP 429 가 아니라 그 계좌의 결과에 ACCOUNT_COOLDOWN 과 retryAfterSec 가 들어갑니다.
{
"success": false,
"results": [
{ "accountNumber": "110012345678", "success": true,
"accountInfo": { "accountNumber": "110012345678", "balance": 3820000 },
"transactions": [ … ] },
{ "accountNumber": "110098765432", "success": false,
"code": "ACCOUNT_COOLDOWN", "message": "…", "retryAfterSec": 212 }
]
}
은행 목록 GET /v1/banks
은행 코드와 준비 단계, 조회에 필요한 항목을 돌려줍니다. 화면으로 보려면 지원 은행.
| 항목 | 설명 |
|---|---|
stage | ready 지원(누구나 등록·조회) · admin 시험 중(운영자가 실제 계좌로 확인하는 중, 가입자는 아직 등록·조회할 수 없음) · soon 준비 중 |
ready | stage === "ready" 와 같은 값 |
mode | account(계좌 비밀번호로 조회) · login(인터넷뱅킹 로그인) |
quickName | 은행 사이트에서 미리 가입·등록할 조회 서비스 이름(농협·국민·우리·기업은행은 빠른조회, 신한은행은 간편조회서비스) |
fields | 계좌 유형별 필요 항목. 빈 배열이면 그 유형은 받지 않습니다. 신한은행은 loginId·loginPassword 를 받고 residentNumber(생년월일·사업자번호)는 받지 않습니다 |
{
"banks": [
{ "code": "KB", "name": "KB 국민", "stage": "admin", "ready": false, "mode": "account", "quickName": "빠른조회",
"fields": { "personal": ["accountNumber", "accountPassword", "residentNumber"],
"business": ["accountNumber", "accountPassword", "residentNumber"] } },
{ "code": "SH", "name": "SH 신한", "stage": "ready", "ready": true, "mode": "login", "quickName": "간편조회서비스",
"fields": { "personal": ["loginId", "loginPassword", "accountNumber", "accountPassword"],
"business": ["loginId", "loginPassword", "accountNumber", "accountPassword"] } },
…
]
}
계좌 목록 GET /v1/accounts
관리 화면에서 등록해 둔 계좌 목록입니다. 계좌 비밀번호 같은 인증정보는 어떤 응답에도 들어 있지 않습니다. 여기서 받은 id 로 저장 내역을 조회합니다.
{
"accounts": [
{ "id": "acc_…", "bankCode": "SH", "accountNumber": "110012345678", "alias": "운영 계좌",
"accountType": "personal", "status": "active", "balance": 1286000,
"lastCollectedAt": "2026-11-18T03:10:02Z" }
]
}
status: active 수집 중 · paused 사용자가 멈춤 · error 연속 5번 실패해 자동 수집이 멈춤
저장 내역 GET /v1/accounts/{id}/transactions
82bank 가 정해진 주기로 모아 저장한 거래를 최신순으로 돌려줍니다. 은행에 가지 않으므로 빠르고, 계좌 5분 제한이 없습니다.
| 매개변수 | 설명 |
|---|---|
from · to | 거래 날짜 범위 (한국 날짜, YYYY-MM-DD 또는 YYYYMMDD) |
type | deposit 또는 withdrawal. 생략하면 모두 |
min · max | 금액 범위 (원) |
q | 적요·보낸 분·은행 메모·내 메모에서 찾을 글자 (50자 이하) |
match | 자동입금확인 상태 none·matched·candidate·ignored |
limit | 한 번에 받을 건수 (기본 100, 최대 500) |
cursor | 앞 응답의 nextCursor. 이것으로 끝까지 넘기면 빠짐·중복 없이 전체를 받습니다. 마지막 쪽이면 nextCursor 가 null |
curl -H "Authorization: Bearer bk_…:sk_…" \
"https://82bank.app/v1/accounts/acc_…/transactions?from=2026-11-18&to=2026-11-18&type=deposit&limit=100"
{
"success": true,
"items": [
{ "id": "tx_…", "accountId": "acc_…", "bankCode": "SH", "accountAlias": "운영 계좌",
"accountNumber": "110012345678",
"date": "2026-11-18", "time": "12:10:05", "type": "deposit",
"amount": 32000, "balance": 1286000,
"description": "타행이체", "counterparty": "홍길동", "memo": "", "branch": "",
"userMemo": null, "matchStatus": "matched", "orderNo": "A20261118-0012" }
],
"nextCursor": "2026-11-18T03:10:05Z|tx_…"
}
id 는 거래 고유 id 라 중복 확인에 쓰면 됩니다. userMemo 는 관리 화면에서 단 메모, matchStatus 는 자동입금확인 상태, orderNo 는 붙은 주문번호(없으면 null)입니다.
지금 수집 POST /v1/accounts/{id}/refresh
다음 주기를 기다리지 않고 그 계좌를 수집 대기열에 넣습니다. 수집은 5분마다 도는 작업이 처리하므로 몇 분 안에 저장 내역과 웹훅으로 확인합니다. 같은 계좌 5분에 1회, 일시중지한 계좌는 409 ACCOUNT_PAUSED, 은행이 인증정보를 거절해 멈춘 계좌는 409 CREDENTIAL_BLOCKED(관리 화면에서 새 인증정보를 저장해야 풀립니다).
{ "success": true, "jobId": "job_…", "queued": true }
이미 대기·실행 중인 수집이 있으면 새로 넣지 않고 그 jobId 와 "queued": false 를 돌려줍니다.
주문 등록 POST /v1/orders
자동입금확인용입니다. 무통장입금 주문을 등록해 두면, 입금이 수집될 때 입금자명과 금액이 같고, 입금 시각이 주문을 만든 뒤(10분 여유)이며 기한 안인 주문이 정확히 하나일 때 자동으로 붙이고 상점 콜백을 보냅니다. 후보가 둘 이상이거나 입금이 주문보다 먼저 들어왔으면 붙이지 않고 관리 화면 [매치작업]에 올려 사람이 고르게 합니다. 자동입금확인 가이드에 흐름을 정리해 두었습니다.
| 항목 | 설명 |
|---|---|
shopId | 관리 화면 [상점관리]의 상점 id. 상점이 하나뿐이면 생략할 수 있습니다(둘 이상이면 필요) |
orderNo | 상점의 주문번호, 100자 이하. 같은 상점 안에서 다시 쓰면 409 ORDER_EXISTS |
depositorName | 입금자명, 50자 이하 |
amount | 입금받을 금액(원, 1 이상의 정수). 1원이라도 다르면 붙지 않습니다 |
expiresAt | 선택. ISO 8601 시각. 은행 거래 시각이 이 시각까지인 입금만 붙입니다(수집이 늦어 주문이 expired 가 됐어도 기한 안 입금이면 붙고 matched 가 됩니다). 생략하면 상점에 정한 기한(기본 72시간) |
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" }'
HTTP/1.1 201 Created
{
"success": true,
"order": {
"id": "ord_…", "shopId": "shp_…", "orderNo": "A20261118-0012",
"depositorName": "홍길동", "amount": 32000,
"expiresAt": "2026-11-21T00:00:00Z", "status": "waiting",
"transactionId": null, "matchedAt": null, "createdAt": "2026-11-18T03:05:00Z"
}
}
이름은 공백·괄호 안 글자·주식회사를 빼고 전각을 반각으로 바꿔 비교합니다. 같거나, 입금자 이름이 주문 이름의 앞부분이고 3자 이상이면 같은 이름으로 봅니다(은행이 입금자 이름을 잘라 주는 경우). 반대로 입금자 이름이 더 길면 다른 사람으로 봅니다. 주문을 등록할 때 이미 들어온 미매칭 입금과도 맞춰 보지만, 자동으로 붙는 것은 주문 등록 직전 10분 안의 입금뿐입니다. 그보다 먼저 들어온 입금은 같은 이름·금액이어도 자동으로 붙이지 않고 [매치작업]에 후보로 올립니다(예전 입금이 새 주문에 붙어 돈을 받지 않고 발송하는 일을 막기 위해). 시각을 주지 않는 은행(거래 시각 00:00:00)은 날짜로 비교합니다. 비밀계좌의 입금은 매칭에 쓰지 않습니다.
주문 조회 GET /v1/orders/{orderNo} · 취소 DELETE /v1/orders/{orderNo}
상점이 둘 이상이면 ?shopId= 가 필요합니다. 응답은 등록과 같은 { "success": true, "order": { … } } 이고, status 로 상태(waiting 입금 대기 · matched 입금 확인 · expired 기한 지남 · canceled 취소)를 알 수 있습니다. 고객이 주문을 취소하면 DELETE 로 취소해 두세요. 이미 입금이 붙은 주문은 409 ALREADY_MATCHED 로 취소되지 않습니다.
curl -H "Authorization: Bearer bk_…:sk_…" \
"https://82bank.app/v1/orders/A20261118-0012"
curl -X DELETE -H "Authorization: Bearer bk_…:sk_…" \
"https://82bank.app/v1/orders/A20261118-0012?shopId=shp_…"
입금이 붙으면 상점 콜백 주소로 다음이 갑니다. 웹훅과 달리 id·data 없이 이벤트 이름과 내용이 한 단계로 옵니다.
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": "타행이체" }
}
웹훅
관리 화면 [데이터전송]에서 받을 주소와 이벤트를 고르면, 일이 생길 때마다 82bank 가 그 주소로 POST 합니다. 웹훅은 가입 단위마다 10개까지 만들 수 있고, 웹훅마다 서명용 시크릿이 만들어집니다.
| 이벤트 | 보내는 때 | data |
|---|---|---|
transaction.deposit | 새 입금이 처음 저장됐을 때 | 거래 하나: id, accountId, bankCode, accountAlias, date, time, type, amount, balance, description, counterparty, memo, matchStatus, orderNo |
transaction.withdrawal | 새 출금이 처음 저장됐을 때 | |
order.matched | 입금이 주문에 붙은 그때 | 상점 콜백과 같은 orderNo, amount, depositorName, matchedAt, transaction |
order.unmatched | 관리 화면에서 매칭을 풀어 주문이 다시 waiting 이 됐을 때(상점 콜백으로도 갑니다) | orderNo, amount, depositorName, status, unmatchedAt, transaction |
account.error | 계좌 수집이 연속 5번 실패하거나 은행이 인증정보를 거절해 자동 수집을 멈췄을 때 (한 번) | accountId, bankCode, accountAlias, errorCode |
POST /hooks/82bank HTTP/1.1
Content-Type: application/json
User-Agent: 82bank-webhook/1
X-82bank-Event: transaction.deposit
X-82bank-Signature: 5f0c3a…(본문을 웹훅 시크릿으로 HMAC-SHA256 한 16진수 64자)
{
"id": "whd_…",
"event": "transaction.deposit",
"createdAt": "2026-11-18T03:12:41Z",
"data": {
"id": "tx_…", "accountId": "acc_…", "bankCode": "SH", "accountAlias": "운영 계좌",
"date": "2026-11-18", "time": "12:10:05", "type": "deposit",
"amount": 32000, "balance": 1286000,
"description": "타행이체", "counterparty": "홍길동", "memo": "",
"matchStatus": "matched", "orderNo": "A20261118-0012"
}
}
- 신규 거래만 보냅니다. 계좌를 등록할 때 가져오는 지난 30일 치는 보내지 않고, 거래 날짜(한국 날짜)가 계좌 등록일 이후인 거래가 처음 저장될 때 한 번 보냅니다. 같은 거래를 다시 수집해도 다시 보내지 않습니다.
- 헤더:
X-82bank-Event(이벤트 이름),X-82bank-Signature(서명). 관리 화면의 [시험 전송]은webhook.test이벤트로 옵니다. - 받는 서버는 10초 안에 2xx 로 답해야 합니다. 3xx 리다이렉트는 따라가지 않고 실패로 봅니다. 실패하면 1분·5분·30분·2시간·12시간 뒤를 다음 시도 시각으로 잡고, 처음까지 6번 실패하면 멈춥니다. 재시도는 5분마다 도는 작업이 처리하므로 실제로는 그 시각 뒤 5분 안에 갑니다.
- 한 번 수집에서 바로 보내는 전송은 웹훅·상점 콜백을 합쳐 20건까지이고, 나머지는 대기열에 남아 다음 5분 주기에 갑니다.
- 재시도 때문에 같은 알림이 두 번 올 수 있습니다. 본문의
id로 이미 처리했는지 확인하세요. 실패로 끝난 전송은 관리 화면 전송 기록에서 [다시 보내기]로 다시 보낼 수 있습니다. - 웹훅 전송이 실패해도 수집과 매칭은 그대로 끝납니다. 놓친 거래는 저장 내역으로 다시 받을 수 있습니다.
- 주소 규칙(웹훅·상점 콜백 같음):
https://만, 500자 이하. IP 주소,localhost·.local·.internal같은 내부 이름, 점이 없는 이름, 82bank 자신의 주소, 아이디·비밀번호가 든 주소는 받지 않습니다.
서명 검증
X-82bank-Signature 는 받은 본문 그대로를 웹훅 시크릿으로 HMAC-SHA256 한 값(소문자 16진수 64자)입니다. JSON 을 파싱한 뒤 다시 문자열로 만들면 값이 달라지니, 원래 바이트로 계산하고 시간 차이가 없는 비교 함수를 쓰세요. 상점 콜백도 같은 방식이고 상점 콜백 시크릿을 씁니다.
Node.js
// Node.js + Express — 서명은 "받은 그대로의 본문"으로 계산해야 하므로 raw 로 받는다
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.BANK82_WEBHOOK_SECRET;
app.post("/hooks/82bank", express.raw({ type: "application/json" }), (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"));
// evt.id 로 이미 처리한 알림인지 먼저 확인한다 (재시도로 같은 알림이 다시 올 수 있다)
console.log(evt.event, evt.data);
res.status(200).end(); // 10초 안에 2xx 로 답한다. 오래 걸리는 일은 답한 뒤에.
});
app.listen(3000);
Python
# Python + Flask
import hmac, hashlib, os
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["BANK82_WEBHOOK_SECRET"].encode()
@app.post("/hooks/82bank")
def hook():
body = request.get_data() # 받은 그대로의 바이트
want = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
got = request.headers.get("X-82bank-Signature", "")
if not hmac.compare_digest(got, want):
abort(401)
evt = request.get_json()
print(evt["event"], evt["data"])
return "", 200
오류 코드
| code | HTTP | 뜻과 할 일 |
|---|---|---|
MISSING_FIELDS | 400 | 필수 항목이 빠졌거나 형식이 틀렸습니다(날짜·accountType·sortOrder·expiresAt·shopId 포함). message 에 어느 항목인지 있습니다. |
INVALID_BANK_CODE | 400 | 지원하지 않는 은행 코드입니다(은행 코드는 농협 NH·국민 KB·우리 WR·기업 IBK·신한 SH 뿐입니다). /v1/transactions/login 에 로그인 방식이 아닌 은행을 줘도 이 코드입니다. |
INVALID_LOGIN_ID | 400 | 로그인 방식 은행의 이용자 ID(loginId)가 형식에 맞지 않습니다(앞뒤 공백을 지운 뒤 공백 없이 4~20자). 은행에는 보내지 않았습니다. |
USE_LOGIN_ENDPOINT | 400 | 로그인 방식 은행(mode: login, 신한 SH)을 /v1/transactions 로 불렀습니다. /v1/transactions/login 으로 조회해 주세요. |
BANK_UNAVAILABLE | 400 | 아직 조회할 수 없는 은행입니다(준비 중이거나, 운영자만 시험 중인 은행 — 지금은 국민·우리가 시험 중, 기업이 준비 중). |
INVALID_ACCOUNT_TYPE | 400 | 이 은행이 받지 않는 계좌 유형입니다(/v1/banks 의 fields 가 빈 배열인 유형). 지금 지원 은행은 개인·사업자 모두 받습니다. |
INVALID_BUSINESS_NUMBER | 400 | 사업자등록번호(residentNumber, accountType: business)가 숫자 10자리가 아니거나 검증 숫자가 맞지 않습니다. 하이픈·공백은 지워서 받습니다. 은행에는 보내지 않았습니다. |
INVALID_BIRTH_DATE | 400 | 생년월일(residentNumber, accountType: personal)이 YYMMDD 6자리가 아니거나 월·일이 틀렸습니다. 은행에는 보내지 않았습니다. |
ACCOUNT_NOT_REGISTERED | 400 | 실제 은행의 실시간 조회는 관리 화면에서 먼저 등록(은행 확인 통과)하고 인증정보 오류로 멈추지 않은 계좌만 됩니다. 로그인 방식 은행(/v1/transactions/login)은 accounts 의 모든 계좌가 그렇고 loginId 도 등록할 때 넣은 것과 같아야 하며, 어느 쪽이 틀렸는지는 알려 주지 않고 같은 오류를 돌려줍니다. |
INVALID_AMOUNT | 400 | 주문 금액(amount)은 1 이상의 정수(원)여야 합니다. |
INVALID_PARAM | 400 | 저장 내역 조회의 from·to·type·min·max·match 값이 틀렸습니다. |
INVALID_QUERY | 400 | 검색어 q 가 50자를 넘었습니다. |
INVALID_CURSOR | 400 | cursor 는 앞 응답의 nextCursor 값을 그대로 넣어야 합니다. |
UNAUTHORIZED | 401 | Authorization 헤더가 없거나, 키·시크릿이 틀렸거나, 폐기된 키입니다. |
PAYMENT_REQUIRED | 402 | 이용 기간이 끝났습니다. /v1/ping 말고는 모두 이 응답입니다. 관리 화면 [이용료]에서 결제를 신청하세요. |
NOT_FOUND | 404 | 없는 주소·계좌·주문·상점이거나, 다른 가입 단위의 자료입니다. |
METHOD_NOT_ALLOWED | 405 | 주소는 맞고 메서드(GET·POST·DELETE)가 틀렸습니다. |
ORDER_EXISTS | 409 | 같은 상점에 같은 orderNo 가 이미 있습니다. 재시도라면 이미 등록된 것으로 보면 됩니다. |
ALREADY_MATCHED | 409 | 입금이 이미 붙은 주문은 취소할 수 없습니다. |
ACCOUNT_PAUSED | 409 | 일시중지한 계좌는 지금 수집을 요청할 수 없습니다. 관리 화면에서 수집을 다시 켜세요. |
CREDENTIAL_BLOCKED | 409 | 은행이 저장된 인증정보를 거절해 이 계좌의 수집을 멈췄습니다(계좌 잠김 방지). 은행에서 비밀번호를 확인한 뒤 관리 화면에서 새 인증정보를 저장해야 다시 수집합니다. |
VERIFY_LIMIT | 429 | 계좌 잠김 방지로 은행에 보내지 않았습니다. 세 가지 경우입니다. (1) 이 은행·계좌번호(로그인 방식 은행은 이용자 ID 도)로 인증정보 오류가 연달아 2번 났습니다(어느 가입 단위에서 났는지와 무관). 그 계좌를 이미 등록한 가입 단위의 조회·수집·인증정보 변경은 24시간 뒤 한 번 더 시도할 수 있고(retryAfterSec), 성공하면 풀립니다. (2) 새 계좌 등록 확인(관리 화면 계좌 등록, 인증정보 변경으로 이용자 ID 를 바꿀 때)은 그 계좌번호·이용자 ID 에 인증정보 오류가 한 번이라도 있으면 보내지 않습니다. 시간이 지나도 풀리지 않으니 은행에서 정보를 확인한 뒤 관리 화면의 [초기화 요청]을 누르세요. 5분 뒤 다시 시도할 수 있습니다(같은 계좌번호·이용자 ID 마다 30일에 2번까지, 그 뒤에는 help@2nd-korea.com). 응답에 resettable: true 가 있으면 초기화 요청으로 풀 수 있는 경우입니다(retryAfterSec 없음). (3) 가입 단위마다 실제 은행 확인(등록·인증정보 변경)은 하루(한국 날짜) 10번까지입니다(retryAfterSec 는 자정까지). |
ACCOUNT_COOLDOWN | 429 | 같은 계좌를 5분 안에 다시 조회·수집 요청했습니다. retryAfterSec 초 뒤에 다시 부르세요(로그인 방식 조회는 계좌별 결과 안에 HTTP 200 으로 옵니다). |
TOO_MANY_REQUESTS | 429 | API 키 하나의 호출 한도(기본 30분 60회)를 넘었습니다. retryAfterSec 와 Retry-After 헤더를 보세요. |
INTERNAL | 500 | 서버 오류입니다. 잠시 뒤 다시 시도하세요. |
BANK_REJECTED | 200 | 은행이 조회를 거절했습니다. 계좌번호·비밀번호·생년월일(사업자번호)을 확인하세요. |
BANK_TIMEOUT | 200 | 은행 응답이 60초 안에 오지 않았습니다. 잠시 뒤 다시 시도하세요. |
CRAWLER_UNAVAILABLE | 200 | 수집 서버에 연결하지 못했습니다. 잠시 뒤 다시 시도하세요. |
KEYPAD_FAILED | 200 | 은행 화면의 보안 키패드 입력에 실패했습니다. 다시 시도하세요. |
HTTP 200 인 코드는 은행 쪽 결과라서 본문의 success: false 로 옵니다. 실제 은행의 인증정보 오류는 같은 은행·계좌번호(로그인 방식 은행은 이용자 ID 도)로 연달아 2번이면 실시간 조회·자동 수집·인증정보 변경 모두 은행에 더 보내지 않고, 새 계좌 등록 확인은 오류가 한 번이라도 있으면 보내지 않습니다(VERIFY_LIMIT, 429) — 틀린 비밀번호가 반복돼 실제 은행 계좌가 잠기지 않게 하려는 것입니다.