본문으로 건너뛰기
페이싱크 개발자센터
Esc
↑↓이동↵열기⌘J미리보기
이 페이지에서

입금 내역 목록 조회

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 값이 목록에 없어요.

이 페이지가 도움이 되었나요?