---
title: 입금 내역 목록 조회
description: GET /v1/transactions 로 내 계좌에 들어온 입금을 페이지 단위로 조회해요.
sidebar:
  order: 1
  badge: GET
---

```http
GET /v1/transactions
```

API 키 계정의 계좌에 들어온 입금을 최신순으로 조회해요. 계좌, 매칭 여부, 받은 날짜로 거를 수 있어요. 계좌를 제한한 API 키로는 [허용된 계좌의 입금](/api-reference#api-키-계좌-제한)만 나와요.

새 입금을 바로 처리해야 한다면 폴링보다 [`invoice.paid`](/api-reference/webhooks/invoice-paid) 웹훅을 쓰세요. 이 API는 정산, 대사, 매칭되지 않은 입금 확인에 어울려요.

## 쿼리 파라미터

| 파라미터 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `offset` | integer | 예 | 건너뛸 항목 수예요. 0 이상이에요. |
| `limit` | integer | 예 | 가져올 항목 수예요. 1~100이에요. |
| `search` | string | | 입금 ID, 계좌 ID, 매칭된 주문 ID가 같거나, 계좌번호나 입금자명에 검색어가 들어간 입금을 찾아요. 대소문자를 구분하지 않고, 계좌번호는 하이픈이 있어도 찾아요. |
| `bankAccountId` | string | | 이 계좌(`bac_...`)의 입금만 조회해요. API 키의 접근 가능한 계좌 밖이면 `INSUFFICIENT_PERMISSIONS`가 와요. |
| `matched` | boolean | | `true`면 주문에 매칭된 입금, `false`면 매칭되지 않은 입금만 조회해요. |
| `hidden` | boolean | | `true`면 대시보드에서 숨긴 입금, `false`면 숨기지 않은 입금만 조회해요. |
| `dateAfter` | string | | 이 날짜(KST) 이후에 받은 입금만 조회해요. 그날도 포함해요. `YYYY-MM-DD` |
| `dateBefore` | string | | 이 날짜(KST) 이전에 받은 입금만 조회해요. 그날도 포함해요. `YYYY-MM-DD` |

날짜 필터와 정렬은 페이싱크가 입금 알림을 받은 시각(`createdAt`) 기준이에요.

주문 하나에 매칭된 입금을 찾으려면 `search`에 주문 ID(`ivc_...`)를 넣으세요.

## 요청 예시

```bash cURL
curl "https://api.paysync.kr/v1/transactions?offset=0&limit=20&matched=false" \
  -H "Authorization: Bearer $PAYSYNC_API_KEY"
```

```js Node.js
const params = new URLSearchParams({ offset: "0", limit: "20", matched: "false" });
const res = await fetch(`https://api.paysync.kr/v1/transactions?${params}`, {
  headers: { Authorization: `Bearer ${process.env.PAYSYNC_API_KEY}` },
});
const { totalItems, data } = await res.json();
```

```python Python
import os
import requests

res = requests.get(
    "https://api.paysync.kr/v1/transactions",
    headers={"Authorization": f"Bearer {os.environ['PAYSYNC_API_KEY']}"},
    params={"offset": 0, "limit": 20, "matched": "false"},
)
print(res.json())
```

## 응답

`data`는 [입금 객체](/api-reference/transactions/get#입금-객체) 배열이고, `totalItems`는 조건에 맞는 전체 입금 수예요.

```json 200 OK
{
  "code": "OK",
  "totalItems": 3,
  "data": [
    {
      "id": "trx_a1b2c3d4e5f6g7h8i9j0k1l2",
      "bankAccount": {
        "id": "bac_x9y8z7w6v5u4t3s2r1q0p9o8",
        "active": true,
        "ownerId": "acc_x9y8z7w6v5u4t3s2r1q0p9o8",
        "alias": "사업용 계좌",
        "provider": "KB_KOOKMIN_BANK",
        "type": "PERSONAL",
        "number": "12345678901234",
        "createdAt": "2026-04-01T02:00:00.000Z",
        "verifiedAt": "2026-04-01T02:05:00.000Z",
        "deletedAt": null
      },
      "matchedInvoiceId": null,
      "matchMethod": null,
      "amount": 30000,
      "description": "김철수",
      "hidden": false,
      "receivedAt": "2026-04-28T05:02:40.000Z",
      "matchedAt": null,
      "createdAt": "2026-04-28T05:02:41.000Z",
      "deletedAt": null
    }
  ]
}
```

## 오류

| HTTP | `code` | 발생 조건 |
| --- | --- | --- |
| 401 | `NOT_AUTHORIZED` | API 키가 없거나 올바르지 않아요. |
| 403 | `INSUFFICIENT_PERMISSIONS` | `bankAccountId`가 API 키의 접근 가능한 계좌 밖이에요. |
| 403 | `LIMIT_EXCEEDS_MAXIMUM` | `limit`이 100을 넘어요. |
| 422 | `INVALID_OFFSET` | `offset`이 0보다 작아요. |
| 422 | `INVALID_LIMIT` | `limit`이 0 이하예요. |
| 422 | `INVALID_DATE_RANGE_FORMAT` | `dateAfter`나 `dateBefore`가 `YYYY-MM-DD` 형식이 아니에요. |