개발자 센터

BankFlow은 은행 입출금 알림을 통합 관리하고, 실시간 입금 자동매칭을 제공하는 SaaS 플랫폼입니다.

API를 통해 다음 기능을 이용할 수 있습니다:

• 입출금 데이터 실시간 수신 — 계좌의 입출금 발생 시 Webhook으로 즉시 전달
• 주문-입금 자동매칭 — 쇼핑몰 주문을 등록하면, 입금 시 입금자명+금액으로 1초 자동매칭
• 거래 데이터 조회 — 저장된 거래 내역을 API로 조회

인증

모든 API 요청에는 다음 헤더가 필요합니다:

Content-Type: application/json
X-API-Key: your-api-key
X-Store-Id: your-store-key  (선택, 주문 API 사용 시 필요)

API Key는 대시보드 > 설정 > API 키에서 생성할 수 있습니다.

X-Store-Id는 여러 사이트를 운영할 때 어떤 사이트의 요청인지 구분하기 위한 헤더입니다. 대시보드 > 상점 관리에서 상점을 등록하면 Store Key가 발급됩니다.

오류 처리

모든 응답은 JSON 형식이며, success 필드로 성공 여부를 판단합니다:

성공 응답

{
  "success": true,
  "message": "주문이 등록되었습니다.",
  "data": { ... }
}

실패 응답

{
  "success": false,
  "message": "필수 항목이 누락되었습니다: amount"
}

입출금 데이터 실시간 수신

계좌에 입출금이 발생하면 알림전달앱 → BankFlow → 등록된 Webhook URL로 데이터를 전송합니다.

설정 방법

1. 대시보드 > 설정에서 Webhook URL과 Webhook Secret을 확인합니다.
2. 알림전달앱에 Webhook URL을 등록합니다.
3. 은행 앱에서 SMS 통지 서비스를 신청합니다.

수신 데이터 형식

알림전달앱에서 BankFlow로 전송하는 형식:

POST https://bankflow.co.kr/api/v1/webhook

인증 방식 (택 1)

요청 Body

{
  "message": "[입금] 홍길동 313,500원 1005-204-572***계좌 잔액 7,566,003원 04/17 16:29:16",
  "source": "macrodroid",
  "secret": "your-webhook-secret"
}

또는 상세 형식:

{
  "app": "알림전달앱이름",
  "title": "우리은행",
  "message": "[입금] 홍길동 313,500원 1005-204-572***계좌 잔액 7,566,003원 04/17 16:29:16",
  "timestamp": "2024-04-17 16:29:16",
  "secret": "your-webhook-secret"
}

주문 등록

무통장입금 주문을 등록합니다. 해당 금액+입금자명으로 입금이 발생하면 자동으로 매칭됩니다.

POST https://bankflow.co.kr/api/v1/order

Request Body

요청 예시

{
  "order_ref": "ORD-20240417-001",
  "amount": 50000,
  "depositor_name": "홍길동",
  "callback_url": "https://myshop.com/api/payment-confirm",
  "meta": {
    "product": "프리미엄 플랜",
    "user_id": 1234
  }
}

응답 예시

{
  "success": true,
  "message": "주문이 등록되었습니다.",
  "data": {
    "order_id": 1,
    "order_ref": "ORD-20240417-001",
    "status": "pending",
    "matched": false
  }
}

등록하자마자 매칭되는 경우 (역방향 매칭)

입금이 주문 등록보다 먼저 들어올 수 있습니다. 주문을 등록할 때 최근 일정 시간 안에 들어온, 아직 어느 주문에도 연결되지 않은 입금 중 금액과 입금자명(또는 별칭)이 맞는 것이 정확히 1건이면 바로 매칭하고 응답에 표시합니다. 2건 이상이면 매칭하지 않고 관리자 확인으로 넘깁니다.

범위는 기본 2시간이고, 관리자 화면(주문 관리 › 매칭 설정)에서 역방향 매칭을 끄거나 1~24시간으로 조절할 수 있습니다. 끄면 등록 응답은 항상 "matched": false 이고, 입금이 들어올 때의 매칭만 동작합니다. 범위를 길게 잡을수록 이미 손으로 처리한 입금이 새 주문에 다시 연결될 위험이 커집니다.

{
  "success": true,
  "message": "주문이 등록되었고, 먼저 들어온 입금과 바로 매칭되었습니다.",
  "data": {
    "order_id": 1,
    "order_ref": "ORD-20240417-001",
    "status": "pending",
    "matched": true,
    "match_type": "reverse",
    "matched_at": "2024-04-17 16:30:02"
  }
}

주문 매칭제외

특정 주문을 매칭 대상에서 제외합니다.

POST https://bankflow.co.kr/api/v1/order-exclude

Request Body

{
  "order_ref": "ORD-20240417-001"
}
// 또는
{
  "order_id": 1
}

주문 조회

등록된 주문 목록을 조회합니다.

GET https://bankflow.co.kr/api/v1/orders?status=pending&page=1&per_page=30

Query Parameters

매칭 완료 Webhook

주문이 입금과 매칭되면 등록된 callback_url로 다음 데이터가 전송됩니다:

WEBHOOK callback_url (고객사 서버)

{
  "event": "order.matched",
  "event_id": "evt_8fK2mQ9xLr4TzA7bN1cV5wYd",
  "order_id": 1,
  "order_ref": "ORD-20240417-001",
  "amount": 50000,
  "depositor_name": "홍길동",
  "transaction_id": 123,
  "matched_at": "2024-04-17 16:29:16",
  "balance_after": 7566003,
  "match_type": "auto",
  "meta": {
    "product": "프리미엄 플랜",
    "user_id": 1234
  }
}

응답 규격

콜백을 정상적으로 수신했으면 아래와 같이 응답해야 합니다. 미응답 또는 오류 시 최대 3회 재전송됩니다.

// PHP 예시
http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['status' => 'success']);

서명 검증

BankFlow가 보내는 콜백·웹훅에는 진짜 BankFlow 요청인지 확인할 수 있도록 서명 헤더가 붙습니다.

시크릿: 매칭 완료 콜백은 주문의 상점(Store) 시크릿, 알림 웹훅은 설정의 Webhook Secret입니다. 시크릿이 없는 상점은 서명 헤더 없이 전송됩니다. 주문 매칭 콜백 비밀값은 관리자 › 상점 관리에서 확인할 수 있습니다.

// PHP 검증 예시 — 본문은 json_decode 전에 받은 그대로 사용
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_BANKFLOW_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_BANKFLOW_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!ctype_digit($ts) || abs(time() - (int) $ts) > 300 || !hash_equals($expected, $sig)) {
    http_response_code(401);  // 5분 넘은 요청이나 서명 불일치는 거절
    exit;
}
$data = json_decode($raw, true);

이벤트 ID · 재전송

모든 콜백·웹훅(order.matched, transaction.alert, transaction.flagged)에는 이벤트 고유 ID가 붙습니다.

재전송: 끝내 실패한 이벤트는 관리자가 BankFlow 관리자 › Webhook 로그 › 발신 로그에서 「재전송」으로 다시 보낼 수 있습니다. 재전송은 event_id 와 본문 내용은 그대로, X-BankFlow-Timestamp·X-BankFlow-Signature 는 보내는 시각으로 새로 만들고, X-BankFlow-Attempt 는 이어서 늘어납니다. 이미 성공한 이벤트는 다시 보내지 않습니다.

상점 (Store)

여러 사이트를 운영하는 경우, 각 사이트를 상점(Store)으로 등록하여 독립적으로 관리할 수 있습니다.

상점별 분리 항목

사용 예시

// BlogMate에서 주문 등록
POST /api/v1/order
Headers:
  X-API-Key: bf_xxxxx
  X-Store-Id: blogmate

// Work ERP에서 주문 등록 (같은 API Key, 다른 Store)
POST /api/v1/order
Headers:
  X-API-Key: bf_xxxxx
  X-Store-Id: work-erp

상점 전용 API 키

API 키를 만들 때 범위를 회사 전체 또는 상점 하나로 고릅니다(대시보드 > 설정 > API 키, 또는 상점 관리 카드의 「이 상점 전용 API 키 만들기」). 상점 전용 키는 그 상점의 계좌·거래·주문만 다룹니다. 다른 회사·다른 서버에서 운영하는 사이트에는 상점 전용 키를 두세요.

상점이 비활성이면 그 상점 전용 키는 403, 상점을 삭제하면 그 상점 전용 키도 함께 지워집니다.

// 다른 서버의 사이트 — 상점 전용 키 (X-Store-Id 없이도 그 상점 주문으로 등록)
POST /api/v1/order
Headers:
  X-API-Key: bf_yyyyy

거래 내역 조회

저장된 거래 내역을 조회합니다.

GET https://bankflow.co.kr/api/v1/transactions?from=2024-01-01&to=2024-12-31&type=deposit

Query Parameters

계좌 목록 조회

등록된 계좌 목록을 조회합니다.

GET https://bankflow.co.kr/api/v1/accounts

현금영수증 발행 API

외부 서비스에서 API로 현금영수증을 발행할 수 있습니다. 팝빌 연동이 완료되어 있어야 합니다.

POST https://bankflow.co.kr/api/v1/cashbill

요청 헤더

요청 Body

{
  "amount": 11000,
  "trade_type": "income",
  "identity_num": "01012345678",
  "buyer_name": "홍길동",
  "item_name": "포인트 충전",
  "transaction_id": 123
}

응답

{
  "success": true,
  "message": "현금영수증이 발행되었습니다.",
  "data": {
    "approval_num": "TB0000043",
    "mgt_key": "BF260320143025abc1"
  }
}

세금계산서 발행 API

외부 서비스에서 API로 전자세금계산서를 발행할 수 있습니다. 팝빌 연동 + 공인인증서 등록이 필요합니다.

POST https://bankflow.co.kr/api/v1/taxinvoice

요청 Body

{
  "amount": 110000,
  "invoicee_corp_num": "1234567890",
  "invoicee_corp_name": "거래처상호",
  "invoicee_ceo_name": "대표자명",
  "invoicee_email": "tax@example.com",
  "item_name": "서비스 이용료",
  "write_date": "20260320",
  "transaction_id": 123
}

응답

{
  "success": true,
  "message": "세금계산서가 발행되었습니다.",
  "data": {
    "mgt_key": "BF260320143025abc1"
  }
}

알림 웹훅 수신

알림 규칙에서 "외부 웹훅"을 선택하면, 조건에 매칭되는 거래 발생 시 지정한 URL로 POST 요청을 보냅니다.

설정 방법

1. 대시보드 > 알림 규칙 > 규칙 추가
2. 조건 설정 (예: 입금/출금 전체, 금액 초과 등)
3. 알림 방식: "외부 웹훅" 또는 "웹 알림 + 외부 웹훅" 선택
4. 웹훅 URL 입력 + 데이터 형식 선택 (JSON / 메시지)

요청 형식

POST 지정한 웹훅 URL

JSON 형식 (API 연동용)

헤더: Content-Type: application/json, X-BankFlow-Event: transaction.alert, 서명 헤더 X-BankFlow-Timestamp·X-BankFlow-Signature (설정의 Webhook Secret으로 서명 — 서명 검증 참고), 이벤트 ID 헤더 X-BankFlow-Event-Id

{
  "event": "transaction.alert",
  "event_id": "evt_Q3wErT6yUi9oPa2sDf5gHj8k",
  "type": "deposit",
  "amount": 880000,
  "counterpart": "홍길동",
  "balance_after": 8761172,
  "transacted_at": "2026-03-19 08:49:25",
  "rule_name": "모든 입금 알림",
  "transaction_id": 2345,
  "account_id": 1
}

메시지 형식 (사람 읽기용)

헤더: Content-Type: text/plain; charset=utf-8

[입금] 880,000원
홍길동 · 880,000원 · 잔액 8,761,172원

수신 측 구현 예시 (PHP)

// 웹훅 수신 엔드포인트
$raw = file_get_contents('php://input');
$data = json_decode($raw, true);

if ($data['event'] === 'transaction.alert' && $data['type'] === 'deposit') {
    // 입금 알림 처리
    $amount = $data['amount'];
    $counterpart = $data['counterpart'];
    $balance = $data['balance_after'];

    // 예: DB 기록, 슬랙 알림, 포인트 충전 등
    logDeposit($amount, $counterpart, $balance);
}

// 200 OK 응답 (필수)
http_response_code(200);
echo 'OK';

응답 규격

웹훅을 정상 수신했으면 아래와 같이 응답합니다. 미응답 시 최대 3회 재전송됩니다.

거래 데이터 동기화 가이드

BankFlow의 거래 데이터를 자체 서비스 DB에 동기화하여 사용할 수 있습니다.

권장 테이블 구조

CREATE TABLE bankflow_transactions (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    bf_id BIGINT UNSIGNED NOT NULL COMMENT 'BankFlow 거래 ID',
    bank_account_id INT UNSIGNED DEFAULT NULL,
    type VARCHAR(20) NOT NULL DEFAULT 'deposit',
    amount BIGINT UNSIGNED NOT NULL DEFAULT 0,
    balance_after BIGINT DEFAULT NULL,
    counterpart VARCHAR(100) DEFAULT NULL,
    memo VARCHAR(500) DEFAULT NULL,
    transacted_at DATETIME NOT NULL,
    source VARCHAR(20) DEFAULT 'notification',
    is_flagged TINYINT(1) NOT NULL DEFAULT 0,
    synced_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_bf_id (bf_id),
    INDEX idx_type (type),
    INDEX idx_date (transacted_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

필드 설명

동기화 방식

거래 내역 조회 API를 주기적으로 호출하여 bf_id 기준으로 없는 데이터만 INSERT합니다.

최초 전체 동기화

// 100건씩 페이지네이션으로 전체 데이터 수집
GET /api/v1/transactions?from=2020-01-01&to=2026-12-31&page=1&per_page=100

// 응답
{
  "success": true,
  "data": {
    "transactions": [...],
    "total": 2246,      // 전체 건수
    "page": 1,          // 현재 페이지
    "per_page": 100     // 페이지당 건수
  }
}

// total_pages = ceil(total / per_page) = 23
// page 1~23까지 반복 호출

증분 동기화 (크론탭)

// 최근 3일만 조회하여 새로운 것만 INSERT
GET /api/v1/transactions?from=2026-03-15&to=2026-03-18&per_page=100

// bf_id UNIQUE KEY로 중복 자동 방지
// 5분 간격 크론탭 권장

자주 묻는 질문

자동매칭되는 기준은 무엇인가요?

입금 내역의 입금자명과 금액이 대기 중인 주문의 입금자명, 금액과 정확히 일치하는 주문이 1건일 때 자동매칭됩니다. 일치하는 주문이 없거나 2건 이상이면 매칭되지 않습니다.

매칭이 안 되는 경우는?

• 주문이 입금보다 나중에 등록된 경우 (주문을 먼저 등록해야 합니다)
• 입금자명에 공백이 포함되어 정확히 일치하지 않는 경우
• 주문 만료 시간(기본 14일)이 지난 경우
• 동일 입금자명+금액의 주문이 2건 이상인 경우

Webhook이 오지 않아요

• 등록한 Webhook URL이 외부에서 접근 가능한 HTTPS 주소인지 확인하세요.
• 서버 방화벽에서 외부 요청을 차단하고 있지 않은지 확인하세요.
• 유효한 SSL 인증서가 설치되어 있는지 확인하세요.
• 대시보드 > Webhook 로그에서 전송 내역을 확인할 수 있습니다.

API 호출 제한이 있나요?

구독 플랜에 따라 시간당 요청 수가 제한됩니다. 기본 1,000건/시간입니다.