이체톡 API 문서

입금이 들어오면 이체톡이 가맹점 서버로 웹훅을 보내고, 놓친 거래는 조회 API로 가져올 수 있어요.

1. 시작하기

1. 가맹점 콘솔에 가입합니다.
2. 기기 연결 메뉴에서 6자리 코드를 받아 이체톡 앱에 입력합니다.
3. 설정 메뉴에서 웹훅 URL을 등록하고, 웹훅 서명키와 API 키를 확인합니다.

2. 웹훅

입금 알림이 파싱되어 parse_status = parsed가 되면 등록된 URL로 즉시 POST 합니다. 5초 안에 2xx로 응답해 주세요. 실패하면 1분 → 5분 → 15분 → 1시간 → 6시간 간격으로 최대 5번 재시도합니다.

헤더

본문

{
  "id": "tx_10293",                 // 거래 고유 ID (중복 처리에 사용)
  "event": "deposit.created",
  "type": "deposit",                // deposit | withdrawal
  "depositor": "김민지",             // 입금자명 (출금이면 받는 사람)
  "amount": 50000,
  "balance": 1250000,               // 없으면 null
  "bank": "KB국민",
  "account_hint": "123456**789",
  "parse_status": "parsed",         // parsed | review
  "parser": "gpt",                  // gpt | regex
  "device_id": 3,
  "notified_at": "2026-10-07T13:22:05+09:00",
  "received_at": "2026-10-07T13:22:06+09:00",
  "raw": { "title": "입금 50,000원", "text": "김민지 → 내 통장", "app": "KB스타뱅킹" }
}

같은 id가 재시도로 여러 번 올 수 있으니 id 기준으로 중복 처리해 주세요.

서명 검증 예제 - PHP

<?php
$secret = getenv('ICHETALK_WEBHOOK_SECRET');
$body   = file_get_contents('php://input');
$ts     = $_SERVER['HTTP_X_ICHETALK_TIMESTAMP'] ?? '';
$sig    = $_SERVER['HTTP_X_ICHETALK_SIGNATURE'] ?? '';
$expect = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);

if (!hash_equals($expect, $sig) || abs(time() - (int)$ts) > 300) { http_response_code(401); exit; }

$e = json_decode($body, true);
if ($e['event'] === 'deposit.created') {
    // 예) 입금자명 + 금액이 일치하는 '입금대기' 주문을 찾아 결제완료 처리
    // UPDATE orders SET status='paid' WHERE status='wait_deposit' AND depositor=? AND amount=? ORDER BY id LIMIT 1
}
http_response_code(200); echo 'ok';

서명 검증 예제 - Node.js (Express)

app.post('/ichetalk/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-IcheTalk-Timestamp');
  const sig = req.get('X-IcheTalk-Signature');
  const expect = 'sha256=' + crypto.createHmac('sha256', process.env.ICHETALK_WEBHOOK_SECRET)
                   .update(ts + '.' + req.body).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(expect), Buffer.from(sig || ''))) return res.sendStatus(401);
  const e = JSON.parse(req.body);
  // ... 주문 매칭
  res.send('ok');
});

서명 검증 예제 - Python (FastAPI)

@app.post("/ichetalk/webhook")
async def hook(request: Request):
    body = await request.body()
    ts = request.headers.get("x-ichetalk-timestamp", "")
    expect = "sha256=" + hmac.new(SECRET.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expect, request.headers.get("x-ichetalk-signature", "")):
        raise HTTPException(401)
    e = json.loads(body)
    return "ok"

3. 조회 API

GET /v1/transactions

since_id 이후의 거래를 오래된 순으로 가져옵니다. 웹훅을 놓쳤을 때 주기적으로 호출해 보완하세요.

curl -H "Authorization: Bearer {API_KEY}" \
  "https://api.ichetalk.com/v1/transactions?since_id=0&limit=50"

{ "ok": true, "data": [ { ...웹훅 본문과 동일... } ], "next_since_id": 10293 }

GET /v1/transactions/{id}

거래 1건을 조회합니다. tx_10293 또는 10293 모두 가능합니다.

4. 파싱 상태

5. 오류 응답

{ "ok": false, "error": { "code": "unauthorized", "message": "API 키가 올바르지 않습니다." } }