입금 내역 목록 조회
GET /v2/transactions 로 워크스페이스 계좌에 들어온 입금을 계좌, 상태, 매칭 방식, 입금 날짜로 걸러 조회해요.
GET /v2/transactions
워크스페이스 계좌에 들어온 입금을 입금 시각(receivedAt) 최신순으로 조회해요. 계좌를 제한한 API 키로는 허용된 계좌의 입금만 나와요.
새 입금을 바로 처리해야 한다면 폴링보다 transaction.created나 invoice.paid 웹훅을 쓰세요. 이 API는 정산, 대사, 매칭되지 않은 입금 확인에 어울려요.
쿼리 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
offset |
integer | 예 | 건너뛸 항목 수예요. 0 이상이에요. |
limit |
integer | 예 | 가져올 항목 수예요. 1~100이에요. |
search |
string | 입금 ID, 계좌 ID, 매칭된 주문 ID나 주문번호(#1043)가 같거나, 입금자명이나 계좌번호에 검색어가 들어간 입금을 찾아요. 대소문자를 구분하지 않고, 계좌번호는 하이픈이 있어도 찾아요. |
|
bankAccountId |
string | 이 계좌(bac_...)들의 입금만 조회해요. 여러 개를 쉼표로 이어 보낼 수 있어요. API 키의 계좌 범위 밖이면 80002가 와요. |
|
status |
string | MATCHED, UNMATCHED, HIDDEN 중에서 골라요. 여러 개를 쉼표로 이어 보낼 수 있어요. |
|
matchMethod |
string | 매칭 방식으로 걸러요. EXACT, BRACKET_REMOVAL, NAME_PREFIX, CASE_INSENSITIVE, NORMALIZED, SPLIT_DEPOSITS, AMOUNT_TOLERANCE, MANUAL 중에서 골라요. AMOUNT_TOLERANCE는 2026년 10월 전에 매칭된 입금에만 있어요. |
|
dateFrom |
string | 이 날짜(KST)부터 들어온 입금만 조회해요. YYYY-MM-DD |
|
dateTo |
string | 이 날짜(KST)까지 들어온 입금만 조회해요. 그날도 포함해요. YYYY-MM-DD |
날짜 필터와 정렬은 은행 알림 기준 입금 시각(receivedAt)을 써요. v1 API는 페이싱크가 기록한 시각(createdAt)을 써요.
주문 하나에 매칭된 입금을 찾으려면 search에 주문 ID(ivc_...)를 넣거나 주문의 matchedTransactionId로 단건 조회하세요.
요청 예시
curl "https://api.paysync.kr/v2/transactions?offset=0&limit=20&status=UNMATCHED" \
-H "Authorization: Bearer $PAYSYNC_API_KEY"const params = new URLSearchParams({ offset: "0", limit: "20", status: "UNMATCHED" });
const res = await fetch(`https://api.paysync.kr/v2/transactions?${params}`, {
headers: { Authorization: `Bearer ${process.env.PAYSYNC_API_KEY}` },
});
const { items, totalItems } = await res.json();import os
import requests
res = requests.get(
"https://api.paysync.kr/v2/transactions",
headers={"Authorization": f"Bearer {os.environ['PAYSYNC_API_KEY']}"},
params={"offset": 0, "limit": 20, "status": "UNMATCHED"},
)
print(res.json())응답
items는 입금 객체 배열이고, totalItems는 조건에 맞는 전체 입금 수예요.
{
"code": "10001",
"items": [
{
"id": "trx_p4q5r6s7t8u9v0w1x2y3z4a5",
"bankAccount": {
"id": "bac_x9y8z7w6v5u4t3s2r1q0p9o8",
"alias": "대표 계좌",
"provider": "KB_KOOKMIN_BANK",
"type": "CORPORATE",
"number": "123456-01-234567"
},
"depositorName": "김철수",
"amount": 30000,
"receivedAt": 1777352560,
"status": "UNMATCHED",
"match": null,
"failureReason": "NO_CANDIDATE",
"candidateCount": 0,
"hidden": false,
"hiddenAt": null,
"unmatches": [],
"createdAt": 1777352561
}
],
"totalItems": 3
}
오류
| HTTP | code |
발생 조건 |
|---|---|---|
| 401 | 290006 |
API 키가 올바르지 않아요. |
| 403 | 40001 |
limit이 100을 넘어요. |
| 403 | 80002 |
bankAccountId가 API 키의 계좌 범위 밖이에요. |
| 422 | 30001 |
offset이 없거나 0보다 작아요. |
| 422 | 30002 |
limit이 없거나 0 이하예요. |
| 422 | 30004 |
dateFrom이나 dateTo가 YYYY-MM-DD 형식이 아니에요. |
| 422 | 30005 |
dateFrom이 dateTo보다 늦어요. |
| 422 | 200001 |
bankAccountId 형식이 틀렸어요. |
| 422 | 210002 |
status 값이 목록에 없어요. |
| 422 | 210003 |
matchMethod 값이 목록에 없어요. |