Bank Account Transactions

What you can retrieve

Retrieve the bank accounts and transactions connected to your own business in Bolta. The API returns the transactions Bolta fetched from the bank as is, and you can request a sync when you need one. Each API key covers the one business it belongs to.

Path	Purpose
`GET /v1/bankAccounts`	Connected bank accounts and the sync status of each
`GET /v1/bankAccounts/transactions`	Loaded transactions (cursor based)
`POST /v1/bankAccounts:sync`	Request a transaction sync

Requirements

These calls deduct no points. Instead, you need a Standard plan or higher. A free trial also qualifies when the trial plan is Standard or higher. When your plan does not qualify, all three paths return 402 with PLAN_UPGRADE_REQUIRED. Upgrade your plan from the billing menu in the Bolta dashboard, then call again.

Connect bank accounts in the Bolta dashboard first.

None of the three paths needs issuer registration, a certificate, or Bolta-Client-Reference-Id. Send Basic {apiKey} in the Authorization header. See the authentication guide.

Key limits

Item	Limit
Sync request	Once every 30 minutes and 12 times in 24 hours per business
Visibility	About 5 minutes after the change in Bolta
Items per call (`limit`)	Up to 500. Defaults to 100

Account list

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"
    }
  ]
}

Field	Type	Description
`id`	string	Account identifier
`bankCode`	string	Three-digit KFTC bank code. See the bank code table below
`bankName`	string	Bank name
`accountNumber`	string	Account number with hyphens
`name`	string	Alias set in the dashboard. Falls back to the bank’s account name
`currencyCode`	string	ISO 4217 currency code. `KRW`, `USD`, `JPY`
`lastSyncedAt`	string or null	Time of the last completed sync (UTC)
`syncStatus`	string	`IDLE`, `IN_PROGRESS`, `FAILED`

Bank codes

bankCode is the three-digit standard bank code assigned by the Korea Financial Telecommunications & Clearings Institute (KFTC). Bolta supports connecting accounts at these banks:

`bankCode`	Bank
`002`	Korea Development Bank
`003`	IBK Industrial Bank of Korea
`004`	KB Kookmin Bank
`007`	Suhyup Bank
`011`	NH NongHyup Bank
`020`	Woori Bank
`023`	SC First Bank
`027`	Citibank Korea
`031`	iM Bank (formerly Daegu Bank)
`032`	Busan Bank
`034`	Kwangju Bank
`035`	Jeju Bank
`037`	Jeonbuk Bank
`039`	Kyongnam Bank
`045`	MG Community Credit Cooperatives
`048`	National Credit Union Federation of Korea
`071`	Korea Post
`081`	Hana Bank
`088`	Shinhan Bank
`089`	K Bank

Local NongHyup cooperative accounts also use 011.

Transactions

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

Parameter	Required	Description
`from`	No	Start of the transaction date range. `YYYY-MM-DD` (KST, inclusive)
`to`	No	End of the transaction date range. `YYYY-MM-DD` (KST, inclusive)
`bankAccountId`	No	Account `id` from the account list
`transactionType`	No	`DEPOSIT`, `WITHDRAW`, `OTHER`
`cursor`	No	`nextCursor` from the previous response
`limit`	No	1 to 500. Defaults to 100

Without a date range, the API returns every loaded transaction.

{
  "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
}

The item shape depends on status.

`status`	Meaning	Fields
`ACTIVE`	A transaction visible in the Bolta dashboard	Every field in the table below
`REMOVED`	A transaction hidden from the dashboard, for example by disconnecting the account or archiving it	`status`, `id`

Field	Type	Description
`items[].status`	string	`ACTIVE`, `REMOVED`
`items[].id`	string	Transaction identifier
`items[].bankAccountId`	string	Account `id`
`items[].bankCode`	string	Bank code of the account. Same as `bankCode` in the account list
`items[].accountNumber`	string	Account number with hyphens
`items[].transactionAt`	string	Transaction time (UTC)
`items[].transactionType`	string	`DEPOSIT`, `WITHDRAW`, `OTHER`
`items[].amount`	number	Transaction amount. Zero or greater; `transactionType` gives the direction
`items[].balanceAfterTransaction`	number	Balance after the transaction
`items[].description`	string or null	Bank memo
`items[].currencyCode`	string	Currency code of the account
`nextCursor`	string	Cursor to pass on the next call
`hasMore`	boolean	Whether more items are available right now

OTHER marks a transaction where the bank reported zero for both the deposit and withdrawal amounts, so amount is 0.

Order and cursor

The API returns transactions in the order they changed in Bolta, not in transaction time order. To show the newest transactions first, sort by transactionAt after you receive them. The same id can arrive more than once. Apply items by id in the order you receive them.

ACTIVE: Overwrite the item with the same id, or add it if none exists.
REMOVED: Delete the item with the same id, or ignore it if none exists.

Collection steps

Call without a cursor, then keep calling with nextCursor until hasMore is false.
Save the last nextCursor. The API fills nextCursor even when hasMore is false. If you use several sets of filters, save a cursor for each.
On your next collection, call with the saved cursor. You receive only the transactions that changed since then.

hasMore can be true even when items is empty. Decide whether to continue from hasMore, not from items.

Right after a sync finishes, wait about 5 minutes before you continue. Send the cursor exactly as received. A cursor is bound to the filters (from, to, bankAccountId, transactionType) and the API key it was issued for. After you change the filters or the API key, start over without a cursor. The API rejects an old cursor with 400 and INVALID_CURSOR. You can change limit on any page.

Sync request

Bolta fetches transactions periodically. Request a sync only when you need the latest transactions sooner.

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"
}

The API only accepts the request with 202 Accepted, and the bank lookup runs asynchronously. Check progress with syncStatus in the account list. When IN_PROGRESS ends, continue fetching transactions with your saved cursor. See Key limits for the request limits. nextAvailableAt reflects only the 30-minute interval, not the 24-hour count.

Status code	Error code	Meaning
`202`	-	Accepted
`409`	`SYNC_IN_PROGRESS`	A sync is already running. Request again after it ends
`422`	`BANK_ACCOUNT_NOT_CONNECTED`	No bank account is connected
`429`	`SYNC_RATE_LIMITED`	Request limit exceeded. Wait for the `Retry-After` seconds
`503`	`SYNC_UNAVAILABLE`	Temporarily unable to evaluate the request. Request again shortly

A request rejected because a sync is already running (409) does not count toward the limit.

Testing with a test key

Test keys return fixed samples regardless of your subscription, and sync requests use no quota.

Account `id`	`bankCode`	Account number
`1`	`004`	`123456-01-234567`
`2`	`088`	`110-123-456789`

Transaction `id`	Account	Transaction time (UTC)	Type	Amount	Status
`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`

Transaction 6 is archived, so only status and id come back. Call with limit=3 to see cursor paging across two pages. Test keys skip the 5-minute delay.

Errors

Status code	Error code	Condition
`400`	`INVALID_REQUEST`	Invalid date format, `from` later than `to`, or an invalid `transactionType` or `limit`
`400`	`INVALID_CURSOR`	Modified or malformed cursor, or filters or API key differ from when the cursor was issued
`401`	-	API key authentication failed. Empty response body
`402`	`PLAN_UPGRADE_REQUIRED`	Plan below Standard
`404`	`BANK_ACCOUNT_NOT_FOUND`	`bankAccountId` that does not exist or belongs to another business
`409`	`SYNC_IN_PROGRESS`	A sync is already running
`422`	`BANK_ACCOUNT_NOT_CONNECTED`	No bank account is connected
`429`	`SYNC_RATE_LIMITED`	Sync request limit exceeded. Comes with a `Retry-After` header
`500`	`INTERNAL_SERVER_ERROR`	Internal server error
`503`	`SYNC_UNAVAILABLE`	Temporarily unable to evaluate the sync request
`503`	`SERVICE_UNAVAILABLE`	Temporary internal API communication error

See Error codes for the full list.

API Introduction

API Guides

Use Cases

SDK / No-code

What you can retrieve

Requirements

Key limits

Account list

Bank codes

Transactions

Order and cursor

Collection steps

Sync request

Testing with a test key

Errors

​What you can retrieve

​Requirements

​Key limits

​Account list

​Bank codes

​Transactions

​Order and cursor

​Collection steps

​Sync request

​Testing with a test key

​Errors

​Related documents

What you can retrieve

Requirements

Key limits

Account list

Bank codes

Transactions

Order and cursor

Collection steps

Sync request

Testing with a test key

Errors

Related documents