개발자 센터

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

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가 발급됩니다.

API Key는 회사별로 발급되며, 해당 회사의 데이터에만 접근할 수 있습니다. 하나의 API Key로 여러 상점의 주문을 관리할 수 있습니다.

오류 처리

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

성공 응답

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

실패 응답

{
  "success": false,
  "message": "필수 항목이 누락되었습니다: amount"
}
HTTP 코드의미
200성공
400잘못된 요청 (파라미터 오류)
401인증 실패 (API Key 오류)
403권한 없음
404리소스 없음
405허용되지 않는 메서드
409충돌 (중복 등)
500서버 오류

입출금 데이터 실시간 수신

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

설정 방법

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

수신 데이터 형식

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

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

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

주문 등록

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

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

Request Body

필드타입필수설명
order_refstringO쇼핑몰 주문번호 (고유)
amountintegerO주문 금액 (원)
depositor_namestringO예상 입금자명
buyer_namestring주문자명 (입금자와 다를 경우)
bank_account_idinteger특정 계좌만 매칭 (미지정 시 전체)
callback_urlstring매칭 완료 시 결과 전송할 URL
expires_hoursinteger매칭 대기 시간 (기본 336=14일)
metaobject추가 데이터 (콜백 시 함께 전달)

요청 예시

{
  "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"
  }
}
매칭 조건: 입금자명과 금액이 정확히 일치하는 pending 주문이 1건일 때 자동매칭됩니다. 일치하는 주문이 0건이면 무시, 2건 이상이면 관리자에게 알림이 발송됩니다.

주문 매칭제외

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

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

파라미터설명
statuspending, matched, excluded, expired, cancelled (선택)
page페이지 번호 (기본 1)
per_page페이지당 건수 (기본 30, 최대 100)

매칭 완료 Webhook

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

WEBHOOK callback_url (고객사 서버)

{
  "event": "order.matched",
  "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,
  "meta": {
    "product": "프리미엄 플랜",
    "user_id": 1234
  }
}
중요: 콜백 수신 시 HTTP 200을 반환해야 합니다. 실패 시 관리자에게 알림이 발송됩니다.

상점 (Store)

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

상점별 분리 항목

항목설명
Store KeyAPI 요청 시 X-Store-Id 헤더에 사용
콜백 URL주문별 미지정 시 상점의 기본 URL 사용
연결 계좌이 상점의 입금을 특정 계좌에서만 매칭
주문 네임스페이스상점별로 order_ref 독립 관리 (다른 상점과 겹쳐도 OK)

사용 예시

// 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
상점 미지정 시에도 주문 등록은 가능합니다. 단, 여러 사이트를 운영한다면 상점을 등록하는 것을 권장합니다.

거래 내역 조회

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

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

Query Parameters

파라미터설명
from시작일 (YYYY-MM-DD)
to종료일 (YYYY-MM-DD)
typedeposit, withdrawal (선택)
account_id특정 계좌 ID (선택)
page페이지 번호
per_page페이지당 건수 (최대 100)

계좌 목록 조회

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

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

자주 묻는 질문

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

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

매칭이 안 되는 경우는?

Webhook이 오지 않아요

API 호출 제한이 있나요?

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

© 2026 BankFlow. All rights reserved.