API

잔액 변동내역

작성일 2026.03.11 | 수정일 2026.03.11

GET/cash/v1/balance/history

Query

startKey— 이전 응답의 nextKey를 전달하여 다음 페이지 조회

limit— 조회 건수 (기본값: 20, 최소: 1)

dateCreated— 생성일 필터. 지원 연산자 gte, lte, gt, lt

type— 변동 타입 필터

groupId— 메시지 그룹 ID 필터

rechargeMethod— 충전 수단 필터

serviceMethod— 서비스 수단 필터

balanceRecharge — 잔액 충전 내역 포함 여부 (기본값: true)

balanceDeduct— 잔액 차감 내역 포함 여부 (기본값: true)

pointRecharge— 포인트 충전 내역 포함 여부 (기본값: true)

pointDeduct— 포인트 차감 내역 포함 여부 (기본값: true)

masterAccountId— 마스터 계정 ID

targetAccountId— 조회 대상 하위 계정 ID

chat

지원 연사자를 사용하실 경우 Query Operator 가이드를 참조하세요

메시지 발송, 충전, 출금, 잔액이전 등으로 인해 발생한 잔액 변동 내역을 조회하는 API입니다.
커서 기반 페이지네이션을 제공하며, startKey를 이용하여 대량의 데이터를 효율적으로 조회할 수 있습니다.

Response

Name	Type	Required	Description
startKey	string\|null	*	현재 조회의 시작 키
nextKey	string\|null	*	다음 페이지 조회를 위한 키. null이면 더 이상 데이터가 없습니다.
limit	number	*	요청한 조회 건수
historyList	array	*	잔액 변동내역 목록
historyId	string	*	잔액 변동내역 고유 ID
accountId	string	*	계정 고유 ID
oldBalance	number	*	변동 전 잔액
newBalance	number	*	변동 후 잔액
oldPoint	number	*	변동 전 포인트
newPoint	number	*	변동 후 포인트
balanceAmount	number	*	잔액 변동 금액. 양수면 충전, 음수면 차감.
pointAmount	number	*	포인트 변동 금액. 양수면 충전, 음수면 차감.
paymentAmount	number	*	실제 결제 금액
type	string	*	변동 타입 (RECHARGE, REWARD, MANUAL, SYSTEM, TRANSFER, APP-PROFIT, SERVICE-CHARGE, WITHDRAW)
groupId	string\|null	*	연관된 메시지 그룹 ID
memo	string\|null	*	변동 사유 메모
rechargeMethod	string\|null		충전 수단 (type이 RECHARGE인 경우에만 존재)
serviceMethod	string\|null		서비스 수단 (type이 SERVICE-CHARGE인 경우에만 존재). 현재 MT(메시지 발송)만 지원.
chargedMethod	string\|null		충전 방식 (AUTO 또는 MANUAL)
paymentMethod	string\|null		결제 시 사용된 카드 정보
masterAccountId	string\|null		마스터 계정 ID (하위 계정 거래 시)
dateCreated	string	*	변동 일시 (ISO 8601)

Structure

json

{
  "startKey": null,
  "nextKey": "64a1b2c3d4e5f6789abcdef0",
  "limit": 20,
  "historyList": [
    {
      "historyId": "64a1b2c3d4e5f6789abcdef1",
      "accountId": "12345678901234",
      "oldBalance": 150000,
      "newBalance": 149980,
      "oldPoint": 3000,
      "newPoint": 2980,
      "balanceAmount": -20,
      "pointAmount": -20,
      "paymentAmount": 0,
      "type": "SERVICE-CHARGE",
      "groupId": "G4V20240701120000ABCDEFGHIJKLMNOPQ",
      "memo": "메시지 발송",
      "rechargeMethod": null,
      "serviceMethod": "MT",
      "chargedMethod": null,
      "paymentMethod": null,
      "masterAccountId": null,
      "dateCreated": "2024-07-01T12:00:00.000Z"
    }
  ]
}