82bank API 문서

버전 v1 · 2026년 11월 18일

은행 계좌의 입출금 내역을 바로 조회하거나, 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

호출 한도와 이용 기간

연결 확인 GET /v1/ping

키가 맞는지만 확인합니다. 응답: { "success": true, "pong": true }

실시간 조회 POST /v1/transactions

요청할 때 은행에 가서 그 기간의 거래를 받아 옵니다. 결과는 저장하지 않습니다(계좌를 등록해 두면 저장 내역은 따로 쌓입니다). 계좌 비밀번호로 조회하는 은행(mode: "account")에 씁니다. stage 가 ready 인 은행만 부를 수 있습니다. 실제 은행은 이 가입 단위가 관리 화면에서 먼저 등록한(은행 확인을 통과한) 계좌만 조회할 수 있습니다(아니면 400 ACCOUNT_NOT_REGISTERED) — 남의 계좌번호에 틀린 비밀번호를 넣어 계좌를 잠그지 못하게 하려는 것입니다. 지금 이 방식으로 열린 은행은 농협(NH)·하나(HN)입니다(국민·우리 시험 중, 기업 준비 중). 신한은행은 아래 로그인 방식 조회를 씁니다.

항목설명
bankCode은행 코드 (은행 목록). 계좌번호 방식 은행(mode: "account")
accountTypepersonal(개인) 또는 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 (한국 시각)
typedeposit(입금) · 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

은행 코드와 준비 단계, 조회에 필요한 항목을 돌려줍니다. 화면으로 보려면 지원 은행.

항목설명
stageready 지원(누구나 등록·조회) · admin 시험 중(운영자가 실제 계좌로 확인하는 중, 가입자는 아직 등록·조회할 수 없음) · soon 준비 중
readystage === "ready" 와 같은 값
modeaccount(계좌 비밀번호로 조회) · 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)
typedeposit 또는 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"
  }
}

서명 검증

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

오류 코드

codeHTTP뜻과 할 일
MISSING_FIELDS400필수 항목이 빠졌거나 형식이 틀렸습니다(날짜·accountType·sortOrder·expiresAt·shopId 포함). message 에 어느 항목인지 있습니다.
INVALID_BANK_CODE400지원하지 않는 은행 코드입니다(은행 코드는 농협 NH·국민 KB·우리 WR·기업 IBK·신한 SH 뿐입니다). /v1/transactions/login 에 로그인 방식이 아닌 은행을 줘도 이 코드입니다.
INVALID_LOGIN_ID400로그인 방식 은행의 이용자 ID(loginId)가 형식에 맞지 않습니다(앞뒤 공백을 지운 뒤 공백 없이 4~20자). 은행에는 보내지 않았습니다.
USE_LOGIN_ENDPOINT400로그인 방식 은행(mode: login, 신한 SH)을 /v1/transactions 로 불렀습니다. /v1/transactions/login 으로 조회해 주세요.
BANK_UNAVAILABLE400아직 조회할 수 없는 은행입니다(준비 중이거나, 운영자만 시험 중인 은행 — 지금은 국민·우리가 시험 중, 기업이 준비 중).
INVALID_ACCOUNT_TYPE400이 은행이 받지 않는 계좌 유형입니다(/v1/banks 의 fields 가 빈 배열인 유형). 지금 지원 은행은 개인·사업자 모두 받습니다.
INVALID_BUSINESS_NUMBER400사업자등록번호(residentNumber, accountType: business)가 숫자 10자리가 아니거나 검증 숫자가 맞지 않습니다. 하이픈·공백은 지워서 받습니다. 은행에는 보내지 않았습니다.
INVALID_BIRTH_DATE400생년월일(residentNumber, accountType: personal)이 YYMMDD 6자리가 아니거나 월·일이 틀렸습니다. 은행에는 보내지 않았습니다.
ACCOUNT_NOT_REGISTERED400실제 은행의 실시간 조회는 관리 화면에서 먼저 등록(은행 확인 통과)하고 인증정보 오류로 멈추지 않은 계좌만 됩니다. 로그인 방식 은행(/v1/transactions/login)은 accounts 의 모든 계좌가 그렇고 loginId 도 등록할 때 넣은 것과 같아야 하며, 어느 쪽이 틀렸는지는 알려 주지 않고 같은 오류를 돌려줍니다.
INVALID_AMOUNT400주문 금액(amount)은 1 이상의 정수(원)여야 합니다.
INVALID_PARAM400저장 내역 조회의 from·to·type·min·max·match 값이 틀렸습니다.
INVALID_QUERY400검색어 q 가 50자를 넘었습니다.
INVALID_CURSOR400cursor 는 앞 응답의 nextCursor 값을 그대로 넣어야 합니다.
UNAUTHORIZED401Authorization 헤더가 없거나, 키·시크릿이 틀렸거나, 폐기된 키입니다.
PAYMENT_REQUIRED402이용 기간이 끝났습니다. /v1/ping 말고는 모두 이 응답입니다. 관리 화면 [이용료]에서 결제를 신청하세요.
NOT_FOUND404없는 주소·계좌·주문·상점이거나, 다른 가입 단위의 자료입니다.
METHOD_NOT_ALLOWED405주소는 맞고 메서드(GET·POST·DELETE)가 틀렸습니다.
ORDER_EXISTS409같은 상점에 같은 orderNo 가 이미 있습니다. 재시도라면 이미 등록된 것으로 보면 됩니다.
ALREADY_MATCHED409입금이 이미 붙은 주문은 취소할 수 없습니다.
ACCOUNT_PAUSED409일시중지한 계좌는 지금 수집을 요청할 수 없습니다. 관리 화면에서 수집을 다시 켜세요.
CREDENTIAL_BLOCKED409은행이 저장된 인증정보를 거절해 이 계좌의 수집을 멈췄습니다(계좌 잠김 방지). 은행에서 비밀번호를 확인한 뒤 관리 화면에서 새 인증정보를 저장해야 다시 수집합니다.
VERIFY_LIMIT429계좌 잠김 방지로 은행에 보내지 않았습니다. 세 가지 경우입니다. (1) 이 은행·계좌번호(로그인 방식 은행은 이용자 ID 도)로 인증정보 오류가 연달아 2번 났습니다(어느 가입 단위에서 났는지와 무관). 그 계좌를 이미 등록한 가입 단위의 조회·수집·인증정보 변경은 24시간 뒤 한 번 더 시도할 수 있고(retryAfterSec), 성공하면 풀립니다. (2) 새 계좌 등록 확인(관리 화면 계좌 등록, 인증정보 변경으로 이용자 ID 를 바꿀 때)은 그 계좌번호·이용자 ID 에 인증정보 오류가 한 번이라도 있으면 보내지 않습니다. 시간이 지나도 풀리지 않으니 은행에서 정보를 확인한 뒤 관리 화면의 [초기화 요청]을 누르세요. 5분 뒤 다시 시도할 수 있습니다(같은 계좌번호·이용자 ID 마다 30일에 2번까지, 그 뒤에는 help@2nd-korea.com). 응답에 resettable: true 가 있으면 초기화 요청으로 풀 수 있는 경우입니다(retryAfterSec 없음). (3) 가입 단위마다 실제 은행 확인(등록·인증정보 변경)은 하루(한국 날짜) 10번까지입니다(retryAfterSec 는 자정까지).
ACCOUNT_COOLDOWN429같은 계좌를 5분 안에 다시 조회·수집 요청했습니다. retryAfterSec 초 뒤에 다시 부르세요(로그인 방식 조회는 계좌별 결과 안에 HTTP 200 으로 옵니다).
TOO_MANY_REQUESTS429API 키 하나의 호출 한도(기본 30분 60회)를 넘었습니다. retryAfterSec 와 Retry-After 헤더를 보세요.
INTERNAL500서버 오류입니다. 잠시 뒤 다시 시도하세요.
BANK_REJECTED200은행이 조회를 거절했습니다. 계좌번호·비밀번호·생년월일(사업자번호)을 확인하세요.
BANK_TIMEOUT200은행 응답이 60초 안에 오지 않았습니다. 잠시 뒤 다시 시도하세요.
CRAWLER_UNAVAILABLE200수집 서버에 연결하지 못했습니다. 잠시 뒤 다시 시도하세요.
KEYPAD_FAILED200은행 화면의 보안 키패드 입력에 실패했습니다. 다시 시도하세요.

HTTP 200 인 코드는 은행 쪽 결과라서 본문의 success: false 로 옵니다. 실제 은행의 인증정보 오류는 같은 은행·계좌번호(로그인 방식 은행은 이용자 ID 도)로 연달아 2번이면 실시간 조회·자동 수집·인증정보 변경 모두 은행에 더 보내지 않고, 새 계좌 등록 확인은 오류가 한 번이라도 있으면 보내지 않습니다(VERIFY_LIMIT, 429) — 틀린 비밀번호가 반복돼 실제 은행 계좌가 잠기지 않게 하려는 것입니다.

문의: help@2nd-korea.com