실시간 거래내역 조회와 조회 요청 웹훅 방식의 차이
요청 시점에 은행에서 직접 조회하는 방식과 조회 요청 후 웹훅으로 받는 방식의 차이, 선택 기준을 정리했습니다.
두 방식은 무엇이 다른가요?
화면을 열 때마다 은행에서 가져올지, 모아 두었다가 처리할지를 먼저 정해야 합니다. 정리하면, 실시간 거래내역 조회는 요청한 시점에 은행에서 직접 가져오는 방식이고, 조회 요청과 웹훅은 접수 후 비동기로 처리해 완료 시 결과를 받는 방식입니다. 둘 다 은행 거래내역을 가져오지만 응답 시점과 저장 여부가 다릅니다.
| 항목 | 실시간 거래내역 조회 | 조회 요청과 웹훅 |
|---|---|---|
| 응답 시점 | 요청한 시점에 은행에서 직접 조회해 응답합니다 | 요청하면 즉시 접수(202)되고 job_id를 받습니다. 은행 조회는 이후 비동기로 처리됩니다 |
| 저장 | 저장하지 않습니다 | 조회가 끝난 계좌와 거래내역이 저장되어 API로 다시 가져올 수 있습니다 |
| 소요 시간 | 은행 로그인이 일어나 수 초에서 수십 초가 걸릴 수 있습니다 | 접수 응답은 즉시 오고, 결과는 작업 완료 후에 받습니다 |
| 받는 정보 | 기간을 지정하고, 입금·출금 합계와 상대방별 요약을 함께 받습니다 | 저장된 계좌(계좌번호는 가려진 상태)와 거래내역을 받습니다 |
| 건수 계산 | 조회 1건으로 계산됩니다 | 요청 1건마다 조회 1건으로 계산됩니다. 일괄 요청은 한 번에 최대 500건까지 보낼 수 있습니다 |
웹훅은 거래가 생기면 알려 주나요?
아닙니다. 웹훅은 조회 작업이 끝났을 때 결과를 보내 주는 기능이며 거래 발생이나 잔액 변동을 알려 주지 않습니다. 새 거래를 확인하려면 조회를 요청해야 합니다.
웹훅 전송에 실패하면 여러 번 다시 시도하므로 같은 작업의 알림이 중복될 수 있습니다. 받는 쪽에서 job_id로 구분해 한 번만 처리하세요. 자세한 수신 방법은 웹훅·결과 수신 안내에 있습니다.
어떤 상황에 어느 방식을 고르나요?
화면에서 지금 시점의 내역을 보여 줘야 할 때: 실시간 거래내역 조회가 맞습니다. 수 초에서 수십 초 걸릴 수 있으니 로딩 표시를 함께 설계하세요.
여러 계좌를 모아서 처리할 때: 조회 요청을 일괄로 보내고 웹훅으로 완료를 받는 방식이 맞습니다.
이미 조회된 내역을 다시 볼 때: 저장된 결과 조회를 쓰세요. 거래내역은 정해진 기간만 보관하므로, 그 이전 내역은 실시간 거래내역 조회로 가져옵니다.
요청 방법과 응답 형식은 실시간 거래내역 조회 API 안내에서 확인하세요.
실시간 거래내역 조회는 어떻게 요청하고 무엇을 돌려주나요?
최종 사용자와 은행, 계좌번호, 기간을 지정해 요청합니다. 기간은 from_date와 to_date에 YYYY-MM-DD 형식으로 넣고, 계좌번호는 하이픈이 있어도 없어도 됩니다. 응답은 거래 목록과 기간 요약으로 나뉩니다. 값은 모두 예시입니다.
{
"transactions": [
{
"txn_at": "2026-11-03T14:05:00",
"type": "입금",
"amount": 1200000,
"balance_after": 8450000,
"memo": "11월 용역비",
"counterparty": "예시상사",
"counterparty_name": "예시상사",
"counterparty_account": null
},
{
"txn_at": "2026-11-05T10:20:00",
"type": "출금",
"amount": -300000,
"balance_after": 8150000,
"memo": "사무용품",
"counterparty": "예시문구",
"counterparty_name": "예시문구",
"counterparty_account": null
}
],
"summary": {
"total_in": 1200000,
"total_out": 300000,
"count": 2,
"by_counterparty": [
{
"name": "예시상사",
"account_no": "",
"in_amount": 1200000,
"out_amount": 0,
"count": 1
},
{
"name": "예시문구",
"account_no": "",
"in_amount": 0,
"out_amount": 300000,
"count": 1
}
]
}
}
입금은 amount가 양수, 출금은 음수이고 type에는 입금 또는 출금이 담깁니다. summary의 by_counterparty는 상대방별 입금액, 출금액, 건수를 담은 목록입니다.
이 조회는 요청한 시점에 은행에 접속하므로 수 초에서 수십 초가 걸릴 수 있고, 조회 1건으로 계산됩니다. 은행의 정기점검 시간에는 호출이 실패할 수 있습니다. 사용자가 화면을 열고 기다리는 구조라면 대기 표시와 시간 초과 처리를 함께 설계하세요.
오류는 HTTP 응답으로 구분합니다. 400은 날짜 형식 오류이거나 등록된 인증서가 없는 경우, 402는 무료 한도 또는 크레딧 부족, 404는 사용자를 찾을 수 없는 경우, 500은 은행 조회 중 오류입니다.
두 방식을 함께 쓰면 어떤 구성이 되나요?
기본 수집: 정해진 시각에 일괄 요청을 보내고 웹훅 또는 저장된 결과 조회로 받아 둡니다.
화면 확인: 사용자가 최신 내역을 직접 확인하려는 순간에만 실시간 거래내역 조회를 씁니다.
보관 기간 밖의 내역: 저장된 거래내역은 정해진 기간만 보관하므로 그 이전 내역은 실시간 거래내역 조회로 가져옵니다.
무료 조회는 이벤트로 제공되며 사전 안내 없이 종료될 수 있고, 종료 후에는 요금이 바뀔 수 있습니다. 요금은 메인 페이지의 요금 안내를 확인하세요.
자주 묻는 질문
두 방식을 함께 써도 되나요?
됩니다. 정기 수집은 조회 요청과 웹훅으로 하고, 사용자가 화면에서 직접 확인하는 시점에는 실시간 거래내역 조회를 쓰는 식으로 나눌 수 있습니다.
실시간 거래내역 조회가 항상 빠른가요?
아닙니다. 요청한 시점에 은행 로그인이 일어나므로 수 초에서 수십 초가 걸릴 수 있습니다.