거래·정산 조회 API

특정 기간 동안의 거래·정산 기록을 조회합니다. 매출 기록과 토스페이먼츠의 거래·정산 기록을 비교할 때 사용합니다.

API를 사용하기 위해 필요한 키 정보와 인증 방식, 보안에 대한 정보는 API 사용하기에서 자세히 알아보세요.

거래 조회 API 사용하기

Query 파라미터 startDateendDate로 조회할 기간을 설정해서 거래 기록을 조회할 수 있습니다.

예를 들어 아래 요청은 2022년 1월 1일부터 1월 10일 까지 일어난 거래를 조회합니다.

요청
curl --request GET \
  --url 'https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00.000&endDate=2022-01-10T23:59:59.999' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

조회한 기간 동안의 거래 기록이 응답으로 돌아옵니다.

응답
[
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"amount": 10000,
"status": "DONE",
"transactionAt": "2022-01-03T12:11:34+09:00"
},
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"amount": 10000,
"status": "DONE",
"transactionAt": "2022-01-06T11:53:08+09:00"
}
]
JSON

Case 1. 하루 동안의 거래 기록을 조회하고 싶을 때

하루 동안의 거래 기록을 조회하려면 startDateendDate밀리초(millisecond) 단위까지 시간 정보에 포함해서 요청해야 합니다.

예를 들어 2022년 1월 1일 하루 동안의 기록 전체를 조회하려면 아래와 같이 startDate2022-01-01T00:00:00.000로, endDate2022-01-01T23:59:59.999로 설정해야 합니다.

요청
curl --request GET \
  --url 'https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00.000&endDate=2022-01-01T23:59:59.999' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

응답으로 2022-01-01T00:00:00 부터 2022-01-02T00:00:00 전까지의 기록이 돌아옵니다.

거래 기록 조회의 Query 파라미터에 날짜 정보만 있다면 시간은 자동으로 00:00:00.000으로 설정된다는 점을 유의하세요. startDateendDate가 시간 정보 없이 같은 날짜로 설정되어 있다면 응답으로 돌아오는 기록은 없습니다.

Case 2. 특정 거래 기록 이후부터 조회하고 싶을 때

특정 거래 기록 이후부터 조회하고 싶다면 startingAfter에 특정하고 싶은 거래의 transactionKey 값을 넣어주면 됩니다.

예를 들어 아래 요청은 2022년 1월 1일부터 1월 10일 사이의 거래 기록 중 paymentKey가 '5OhJr1hOealGAknFDLN16'인 기록 다음 건부터 거래 기록을 조회합니다.

요청
curl --request GET \
  --url 'https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00.000&endDate=2022-01-10T23:59:59.999&startingAfter=5OhJr1hOealGAknFDLN16' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

Case 3. 같은 paymentKey를 가진 거래 기록이 있을 때

거래 조회 응답에서 paymentKey가 같고 transactionKey는 다른 여러 개의 거래 기록이 배열로 들어올 수 있습니다. 하나의 결제 건에 대해 금액 지불, 결제 취소, 결제 부분 취소와 같이 여러 번의 거래가 일어날 수 있기 때문입니다.

응답으로 돌아온 객체의 status 값을 보면 어떤 거래가 이루어졌는지 알 수 있습니다.

응답
// paymentKey가 ''인 결제에 대해 각각 지불/취소된 거래 기록 응답 예시
[
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"amount": 1000,
"status": "DONE", // 결제 금액 지불 완료
"transactionAt": "2022-01-01T01:23:56+09:00"
},
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"amount": 1000,
"status": "CANCELED", // 결제 취소
"transactionAt": "2022-01-01T01:23:58+09:00"
}
]
JSON

거래 조회 API를 자세히 알아보세요

거래 조회 API를 직접 실행해보세요


정산 조회 API 사용하기

Query 파라미터 startDateendDate로 조회할 기간을 설정해서 정산 기록을 조회할 수 있습니다.

정산 기록은 날짜 정보를 기준으로 쌓이기 때문에 날짜 정보만 있어도 기록을 조회할 수 있습니다.

예를 들어 아래 요청은 2022년 1월 1일부터 1월 10일 까지 일어난 거래 기록을 조회합니다.

요청
curl --request GET \
  --url 'https://api.tosspayments.com/v1/settlements?startDate=2022-01-01&endDate=2022-01-10' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

조회한 기간 동안의 정산 기록이 응답으로 돌아옵니다.

응답
[
{
"mId": "tosspayments",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"amount": 34000,
"interestFee": 0,
"fee": 860,
"supplyAmount": 782,
"vat": 78,
"payOutAmount": 33140,
"approvedAt": "2021-12-30T12:30:09+09:00",
"soldDate": "2021-12-30",
"paidOutDate": "2022-01-01"
},
// ...
{
"mId": "tosspayments",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"amount": 15000,
"interestFee": 0,
"fee": 1364,
"supplyAmount": 1240,
"vat": 124,
"payOutAmount": 13636,
"approvedAt": "2022-01-08T12:31:43+09:00",
"soldDate": "2022-01-08",
"paidOutDate": "2022-01-10"
}
// ...
]
JSON

Case. 많은 양의 정산 기록을 나누어 보여주고 싶을 때

많은 양의 정산 기록을 조회한다면 pagesize 파라미터를 사용해서 페이지 단위로 기록을 나누어 보여줄 수 있습니다.

아래와 같이 Query 파라미터로 pagesize 값을 추가해보세요. 지정한 기간의 전체 기록 중 한 페이지 당 보여줄 기록의 개수를 size로, 나누어진 페이지 중 조회할 페이지를 page로 지정할 수 있습니다.

예를 들어 아래 요청은 설정한 기간 동안의 전체기록을 100개씩 나누어 보여주고, 전체 페이지 중 3페이지의 기록을 조회합니다.

요청
curl --request GET \
  --url 'https://api.tosspayments.com/v1/settlements?startDate=2022-01-01&endDate=2022-02-01&size=100&page=3' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

만약 전체 기록이 1000개라면 기록을 100개씩 10페이지로 나누어 불러올 수 있고, 전체 10페이지 중 3페이지의 기록인 301번째 기록부터 400번째 기록까지 조회됩니다.

page 값설정한 기간 중 조회되는 기록
11번째 정산 기록 ~ 100번째 정산 기록
2101번째 정산 기록 ~ 200번째 정산 기록
3201번째 정산 기록 ~ 300번째 정산 기록
......
10901번째 정산 기록 ~ 1000번째(마지막) 정산 기록

이 페이지에서 다루는 API의 용도를 '대사'라고 부르기도 합니다. '대사'란 거래·정산 기록을 조회해서 상세히 비교하는 작업을 뜻합니다.


정산 조회 API를 자세히 알아보세요

정산 조회 API를 직접 실행해보세요

내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기