ZeroAPI · DocsGet StartedLogin
Documentation

Developer Reference

KB·하나 입금 알림 API

Overview

ZeroAPI는 본인 KB국민·하나 계좌 입금을 실시간 JSON으로 전달합니다. 결제·정산·환불 기능은 없습니다.

Base URL

URL
https://zeroapi.co.kr

지원 은행

  • KB국민은행
  • 하나은행
입금만 처리
출금·카드·자동이체·인증번호 등은 처리 대상이 아닙니다.

Authentication

모든 API 호출에 Authorization: Bearer <API_KEY> 헤더를 포함합니다.

curl
curl https://zeroapi.co.kr/api/v1/deposits \
  -H "Authorization: Bearer zapi_live_..."
Security
API 키를 클라이언트(브라우저·앱)에 노출하지 마세요. 백엔드 서버에서만 사용합니다.

Quickstart

1. 웹훅 URL 등록

curl
curl -X POST https://zeroapi.co.kr/api/v1/webhook \
  -H "Authorization: Bearer zapi_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.com/hook"}'

응답에 서명 검증용 시크릿이 1회 반환됩니다. 안전하게 보관하세요.

2. 웹훅 수신

JavaScript
app.post('/hook', (req, res) => {
  const { id, amount, counterparty, bank } = req.body;
  // 같은 id는 한 번만 처리 (중복 방지)
  if (alreadyProcessed(id)) return res.json({ ok: true });
  handleDeposit({ amount, counterparty, bank });
  res.json({ ok: true });
});

3. 응답 규약

10초 이내 2xx 응답 필수. 그 외는 자동 재시도됩니다.

Webhook · Deposit

입금 발생 시 등록한 URL로 POST 전송됩니다.

POSThttps://your-server.com/hook

Headers

Header설명
X-ZeroAPI-Signature서명 값 (시크릿으로 검증)
X-ZeroAPI-Timestamp발송 시각 (ISO 8601)
X-ZeroAPI-Signature-Version서명 버전 (v4.0)

Body

FieldType설명
idstring고유 식별자 (중복 방지 키)
typestring항상 "DEPOSIT"
bankstring"KB" 또는 "HANA"
bank_namestring"KB국민은행" 또는 "하나은행"
amountinteger입금액 (원)
counterpartystring|null입금자명 (누락 가능)
masked_accountstring마스킹 계좌
timestampstringISO 8601 입금 시각
balanceinteger|null잔액 (웹훅에만 포함)

Example

JSON
{
  "id": "01HZ8Y3K9X2W5N7P3T6Q8R4M2V",
  "type": "DEPOSIT",
  "bank": "KB",
  "bank_name": "KB국민은행",
  "amount": 12000,
  "counterparty": "김*",
  "masked_account": "392002**674",
  "timestamp": "2026-05-05T14:32:18.000Z",
  "balance": 854000
}

GET /api/v1/deposits

입금 이력 조회. 최신순.

GET/api/v1/deposits

Query Parameters

ParamType설명
limitint최대 100 (기본 20)
offsetint페이지네이션 (기본 0)
sinceISO 8601이후 입금만
untilISO 8601이전 입금만

Response

JSON
{
  "ok": true,
  "count": 2,
  "total": 147,
  "hasMore": true,
  "deposits": [
    {
      "id": "01HZ8Y3K...",
      "type": "DEPOSIT",
      "amount": 12000,
      "counterparty": "김지은",
      "bankName": "KB국민은행",
      "maskedAccount": "392002**674",
      "dateStr": "2026-05-05 14:32",
      "delivered": false,
      "createdAt": "2026-05-05T05:32:19Z"
    }
  ]
}

GET /api/v1/deposits/:id

특정 입금 1건 조회.

GET/api/v1/deposits/{id}

404 — 해당 id 없음.

GET /api/v1/status

계정 현황 조회.

GET/api/v1/status
JSON
{
  "ok": true,
  "account": {
    "maskedAccount": "392002**674",
    "bankName": "KB국민은행",
    "bank": "KB"
  },
  "today": {
    "depositCount": 42,
    "depositTotal": 524000
  },
  "webhook": {
    "url": "https://...",
    "active": true
  }
}

Errors

200OK
400필수 필드 누락
401API 키 없음·잘못됨
404리소스 없음
429요청 한도 초과
500서버 오류
Error JSON
{ "ok": false, "error": "invalid_api_key" }

Rate Limit

API 호출은 분당 120회로 제한됩니다. 초과 시 429가 반환됩니다.

참고
Retry-After 헤더에 재시도 가능 시점(초)이 포함됩니다.

Retry Policy

  • 웹훅 전달 실패 시 최대 8회 자동 재시도됩니다.
  • 지수 백오프: 30초 → 2분 → 10분 → 30분 → 2시간 → 8시간 → 24시간.
  • 영구 실패 (404, 410, 422 등 4xx)는 즉시 EXPIRED 처리됩니다.
  • EXPIRED 건은 대시보드에서 확인 및 수동 재전송 가능합니다.
Webhook 삭제
DELETE /api/v1/webhook으로 등록된 웹훅을 해제할 수 있습니다. 시크릿 회전이 필요하면 삭제 후 재등록하세요.

Limitations

  • 같은 금액의 동시 입금은 구분할 수 없습니다. 금액 끝자리를 차별화하세요.
  • counterparty가 null일 수 있습니다. 방어 로직을 구현하세요.
ZeroAPI © 2026