입출금 내역 조회

무엇을 조회하나요

볼타에 연결한 내 사업자의 입출금 계좌와 입출금 내역을 조회합니다. 볼타가 은행에서 가져와 적재한 내역을 그대로 돌려주고, 필요하면 동기화도 요청할 수 있습니다. 조회 대상은 API 키가 속한 사업자 한 곳입니다.

경로	용도
`GET /v1/bankAccounts`	연결된 입출금 계좌와 계좌별 동기화 상태
`GET /v1/bankAccounts/transactions`	적재된 입출금 내역 (cursor 기반)
`POST /v1/bankAccounts:sync`	입출금 내역 동기화 요청

이용 조건

포인트를 차감하지 않습니다. 대신 스탠다드 플랜 이상을 구독해야 합니다. 무료체험 중이어도 체험 중인 플랜이 스탠다드 이상이면 이용할 수 있습니다. 플랜이 모자라면 세 경로 모두 402와 PLAN_UPGRADE_REQUIRED를 반환합니다. 볼타 대시보드의 결제 메뉴에서 플랜을 업그레이드한 뒤 다시 호출하세요.

계좌는 볼타 대시보드에서 먼저 연결하세요. 연결 방법은 은행 계좌 연동/해지를 참고하세요.

세 경로 모두 발급자 등록, 공동인증서, 요청자 관리번호(Bolta-Client-Reference-Id)가 필요 없습니다. Authorization 헤더에 Basic {apiKey}만 넣으면 됩니다. 인증은 인증 가이드를 참고하세요.

주요 제한

항목	제한
동기화 요청	사업자마다 30분에 1번, 24시간에 12번
응답 반영	볼타에서 바뀐 뒤 약 5분
한 번에 받는 건수 (`limit`)	최대 500건, 기본 100건

계좌 목록

curl https://xapi.bolta.io/v1/bankAccounts \
  -H "Authorization: Basic {apiKey}"

{
  "items": [
    {
      "id": "1",
      "bankCode": "004",
      "bankName": "국민은행",
      "accountNumber": "123456-01-234567",
      "name": "운영자금",
      "currencyCode": "KRW",
      "lastSyncedAt": "2026-09-18T00:00:12Z",
      "syncStatus": "IDLE"
    }
  ]
}

필드	형식	설명
`id`	string	계좌 식별자
`bankCode`	string	금융결제원 3자리 은행코드. 아래 은행코드 표 참고
`bankName`	string	은행 이름
`accountNumber`	string	하이픈을 포함한 계좌번호
`name`	string	대시보드에서 붙인 별칭. 없으면 은행 계좌명
`currencyCode`	string	ISO 4217 통화 코드. `KRW`, `USD`, `JPY`
`lastSyncedAt`	string 또는 null	마지막으로 완료한 동기화 시각 (UTC)
`syncStatus`	string	`IDLE`, `IN_PROGRESS`, `FAILED`

은행코드

bankCode는 금융결제원 3자리 표준 은행코드입니다. 볼타가 연결을 지원하는 은행은 아래와 같습니다.

`bankCode`	은행
`002`	산업은행
`003`	기업은행
`004`	국민은행
`007`	수협은행
`011`	농협은행
`020`	우리은행
`023`	SC제일은행
`027`	씨티은행
`031`	iM뱅크(대구은행)
`032`	부산은행
`034`	광주은행
`035`	제주은행
`037`	전북은행
`039`	경남은행
`045`	새마을금고
`048`	신협
`071`	우체국
`081`	하나은행
`088`	신한은행
`089`	케이뱅크

지역농축협 계좌도 011로 내려옵니다.

입출금 내역

curl "https://xapi.bolta.io/v1/bankAccounts/transactions?limit=100" \
  -H "Authorization: Basic {apiKey}"

파라미터	필수	설명
`from`	X	거래일 시작. `YYYY-MM-DD` (KST, 포함)
`to`	X	거래일 끝. `YYYY-MM-DD` (KST, 포함)
`bankAccountId`	X	계좌 목록의 `id`
`transactionType`	X	`DEPOSIT`, `WITHDRAW`, `OTHER`
`cursor`	X	이전 응답의 `nextCursor`
`limit`	X	1부터 500까지. 기본 100

기간을 주지 않으면 적재된 전체 내역을 조회합니다.

{
  "items": [
    {
      "status": "ACTIVE",
      "id": "1",
      "bankAccountId": "1",
      "bankCode": "004",
      "accountNumber": "123456-01-234567",
      "transactionAt": "2026-09-01T00:30:00Z",
      "transactionType": "DEPOSIT",
      "amount": 1100000,
      "balanceAfterTransaction": 5100000,
      "description": "주식회사볼타",
      "currencyCode": "KRW"
    },
    {
      "status": "REMOVED",
      "id": "6"
    }
  ],
  "nextCursor": "djI6MTc4ODU3MDAwMDAwMDAwMDo2OjJ6OWZiOA",
  "hasMore": false
}

항목은 status에 따라 모양이 다릅니다.

`status`	뜻	담는 필드
`ACTIVE`	볼타 대시보드에 보이는 거래	아래 표의 모든 필드
`REMOVED`	계좌 연동 해제, 보관 등으로 대시보드에서 안 보이게 된 거래	`status`, `id`

필드	형식	설명
`items[].status`	string	`ACTIVE`, `REMOVED`
`items[].id`	string	거래 식별자
`items[].bankAccountId`	string	계좌 `id`
`items[].bankCode`	string	계좌의 은행코드. 계좌 목록의 `bankCode`와 같음
`items[].accountNumber`	string	하이픈을 포함한 계좌번호
`items[].transactionAt`	string	거래 시각 (UTC)
`items[].transactionType`	string	`DEPOSIT`, `WITHDRAW`, `OTHER`
`items[].amount`	number	거래 금액. 0 이상이며 방향은 `transactionType`으로 구분
`items[].balanceAfterTransaction`	number	거래 후 잔액
`items[].description`	string 또는 null	은행 적요
`items[].currencyCode`	string	계좌의 통화 코드
`nextCursor`	string	다음 호출에 넘길 cursor
`hasMore`	boolean	지금 바로 이어 받을 내역이 더 있는지 여부

OTHER는 은행이 입금액과 출금액을 모두 0으로 준 거래이며 amount가 0입니다.

순서와 cursor

API는 볼타에서 거래가 바뀐 순서로 돌려줍니다. 거래 시각 순서가 아닙니다. 화면에 최신순으로 보여 주려면 받은 뒤 transactionAt으로 정렬하세요. 같은 id가 여러 번 올 수 있습니다. 받은 순서대로 id 기준으로 반영하세요.

ACTIVE: 같은 id가 있으면 덮어쓰고, 없으면 추가하세요.
REMOVED: 같은 id가 있으면 지우고, 없으면 무시하세요.

수집 절차

cursor 없이 호출하고, hasMore가 false가 될 때까지 nextCursor로 이어 호출하세요.
마지막 nextCursor를 저장하세요. hasMore가 false여도 nextCursor는 항상 채워집니다. 조건을 여러 개 쓴다면 조건마다 따로 저장하세요.
다음 수집 때 저장한 cursor로 호출하세요. 그 사이 바뀐 거래만 받습니다.

items가 비어 있어도 hasMore가 true일 수 있습니다. items가 아니라 hasMore를 보고 이어 호출하세요.

동기화가 끝난 직후라면 5분쯤 기다린 뒤 이어 받으세요. cursor는 받은 값 그대로 보내세요. cursor는 받을 때의 조건(from, to, bankAccountId, transactionType)과 API 키에 묶입니다. 조건이나 API 키를 바꿨다면 cursor 없이 처음부터 받으세요. 예전 cursor를 보내면 API가 400과 INVALID_CURSOR를 반환합니다. limit은 페이지마다 바꿔도 됩니다.

동기화 요청

볼타는 입출금 내역을 주기적으로 가져옵니다. 그 전에 최신 내역이 필요할 때만 동기화를 요청하세요.

curl -X POST https://xapi.bolta.io/v1/bankAccounts:sync \
  -H "Authorization: Basic {apiKey}"

{
  "acceptedAt": "2026-09-18T03:00:00Z",
  "nextAvailableAt": "2026-09-18T03:30:00Z"
}

API가 202 Accepted로 접수만 하고 은행 조회는 비동기로 진행합니다. 진행 상황은 계좌 목록의 syncStatus로 확인하세요. IN_PROGRESS가 끝나면 저장한 cursor로 입출금 내역을 이어 받으면 됩니다. 요청 한도는 주요 제한을 참고하세요. nextAvailableAt은 30분 간격만 반영하고 24시간 횟수는 반영하지 않습니다.

상태 코드	에러 코드	뜻
`202`	-	접수
`409`	`SYNC_IN_PROGRESS`	이미 동기화가 진행 중. 끝난 뒤 다시 요청하세요
`422`	`BANK_ACCOUNT_NOT_CONNECTED`	연결된 입출금 계좌가 없음
`429`	`SYNC_RATE_LIMITED`	요청 한도 초과. `Retry-After` 초만큼 기다리세요
`503`	`SYNC_UNAVAILABLE`	일시적으로 판정할 수 없음. 잠시 후 다시 요청하세요

진행 중이라 거절한 요청(409)은 한도를 차감하지 않습니다.

테스트 키로 조회하기

테스트 키는 구독과 관계없이 고정 샘플을 돌려주고, 동기화 요청은 한도를 차감하지 않습니다.

계좌 `id`	`bankCode`	계좌번호
`1`	`004`	`123456-01-234567`
`2`	`088`	`110-123-456789`

거래 `id`	계좌	거래 시각 (UTC)	유형	금액	상태
`1`	`1`	2026-09-01T00:30:00Z	`DEPOSIT`	1,100,000	`ACTIVE`
`2`	`1`	2026-09-01T06:10:00Z	`WITHDRAW`	55,000	`ACTIVE`
`3`	`2`	2026-09-02T01:00:00Z	`DEPOSIT`	330,000	`ACTIVE`
`4`	`1`	2026-09-03T08:45:00Z	`WITHDRAW`	2,200,000	`ACTIVE`
`5`	`2`	2026-09-04T02:20:00Z	`DEPOSIT`	770,000	`ACTIVE`
`6`	`2`	2026-09-04T03:00:00Z	`WITHDRAW`	12,000	`REMOVED`

6번은 보관한 거래라 status와 id만 내려갑니다. limit=3으로 호출하면 cursor 넘김을 두 페이지로 확인할 수 있어요. 테스트 키는 5분 지연 없이 바로 돌려줍니다.

오류

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	날짜 형식 오류, `from`이 `to`보다 늦음, `transactionType`이나 `limit` 값 오류
`400`	`INVALID_CURSOR`	변조했거나 형식이 틀린 cursor, 조건이나 API 키가 cursor를 받을 때와 다름
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PLAN_UPGRADE_REQUIRED`	스탠다드 플랜 미만
`404`	`BANK_ACCOUNT_NOT_FOUND`	없거나 내 사업자의 것이 아닌 `bankAccountId`
`409`	`SYNC_IN_PROGRESS`	동기화가 이미 진행 중
`422`	`BANK_ACCOUNT_NOT_CONNECTED`	연결된 입출금 계좌가 없음
`429`	`SYNC_RATE_LIMITED`	동기화 요청 한도 초과. `Retry-After` 헤더 동반
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`SYNC_UNAVAILABLE`	동기화 요청을 일시적으로 판정할 수 없음
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

전체 에러 코드는 에러 코드에서 확인하세요.

API 소개

API 가이드

사용 사례

SDK/노코드 연동

무엇을 조회하나요

이용 조건

주요 제한

계좌 목록

은행코드

입출금 내역

순서와 cursor

수집 절차

동기화 요청

테스트 키로 조회하기

오류

관련 문서

​무엇을 조회하나요

​이용 조건

​주요 제한

​계좌 목록

​은행코드

​입출금 내역

​순서와 cursor

​수집 절차

​동기화 요청

​테스트 키로 조회하기

​오류

​관련 문서

무엇을 조회하나요

이용 조건

주요 제한

계좌 목록

은행코드

입출금 내역

순서와 cursor

수집 절차

동기화 요청

테스트 키로 조회하기

오류

관련 문서