거래/정산조회 API

특정 기간의 거래/정산기록을 조회합니다. 가맹점의 기록과 토스페이먼츠의 거래/정산기록을 비교하고 싶은 가맹점에서 사용합니다.

API 사용하기에서 API 사용에 필요한 인증 정보를 구성해두세요.

거래조회 API 사용하기

날짜 설정에 유의하세요

Query 파라미터로 조회하고자 하는 기간을 설정해서 원하는 기간의 거래기록을 확인할 수 있습니다. 시간 정보가 포함된 transactionAt을 기준으로 조회합니다.

조회를 시작하고자 하는 날짜를 startDate로, 마치고 싶은 날짜는 endDate로 설정합니다. 시간은 자동으로 00:00:00이 설정됩니다. 따라서 두 값이 같으면 응답에 돌아오는 기록이 없습니다.

하루 동안의 거래기록을 확인하려면 endDate는 반드시 startDate 다음 날로 설정해야 정상적으로 조회됩니다. 예를 들어 2021년 1월 1일의 기록 전체를 조회하려면 startDate2021-01-01 로, endDate2021-01-02 로 설정해서 조회해야 2021-01-01T00:00:00 부터 2021-01-02T00:00:00 이전까지의 기록이 응답으로 돌아옵니다.

# 2021년 1월 1일의 전체 거래를 조회하는 요청 Query 파라미터
https://api.tosspayments.com/v1/transactions?startDate=2021-01-01&endDate=2021-01-02

특정 기록 이후부터 확인하고 싶다면

특정 거래 건이 이후부터 조회하고 싶은 경우, startingAftertransactionKey 값을 지정하면 해당 거래 건 다음 기록부터 조회할 수 있습니다. 기본적으로 한 번에 응답되는 개수는 100개지만, limit 에 값을 넣으면 개수를 늘릴 수 있습니다.

같은 거래 건에 대해 결제 관련 처리는 여러 번 일어날 수 있기 때문에, 아래 예시와 같이 paymentKey가 같고 transactionKey는 다른 여러 개의 기록이 배열로 들어오게 됩니다. 응답으로 돌아온 객체의 status 값으로 결제 상태를 알 수 있습니다.

응답
[
{
"mId": "tosspayments",
"transactionKey": "8B4F646A829571D870A3011A4E13D640",
"paymentKey": "R9o5gEq4k6YZ1aOwX7K8mlwo4YQYPryQxzvNPGenpDAlBdbM",
"orderId": "8796779a-0819-4604-b73f-1069421177f7",
"currency": "KRW",
"method": "카드",
"customerKey": "cG_EdskNV1JgX7Y16S6vo",
"useEscrow": false,
"amount": 1000,
"status": "DONE",
"transactionAt": "2021-07-27T01:23:56+09:00"
},
{
"mId": "tosspayments",
"transactionKey": "2270CDE5C5F26336CE8201ED43F06FF2",
"paymentKey": "R9o5gEq4k6YZ1aOwX7K8mlwo4YQYPryQxzvNPGenpDAlBdbM",
"orderId": "8796779a-0819-4604-b73f-1069421177f7",
"currency": "KRW",
"method": "카드",
"customerKey": "cG_EdskNV1JgX7Y16S6vo",
"useEscrow": false,
"amount": 1000,
"status": "CANCELED",
"transactionAt": "2021-07-27T01:23:58+09:00"
}
]

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

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


정산조회 API 사용하기

정산조회 API도 마찬가지로 원하는 기간을 지정해서 정산기록을 조회할 수 있습니다. 결제승인 시점이 아니라 정산이 된 시점인 soldDate값을 기준으로 조회합니다.

거래기록 조회와 달리 날짜 정보만으로 조회하기 때문에 startDateendDate가 같은 날짜라도 해당 날짜에 정산된 기록을 조회할 수 있습니다.

페이지별로 볼 수 있는 기능을 알아보세요

많은 양의 정산기록을 조회할 때는 아래와 같이 Query 파라미터로 pagesize 를 추가해보세요. 지정한 기간의 전체 기록 중 한 페이지에 보여줄 기록의 개수를 size로, 조회할 페이지 값을 page로 지정할 수 있습니다.

https://api.tosspayments.com/v1/settlements?startDate=2021-01-01&endDate=2021-06-01&size=100&page=3

예를 들어 설정한 기간 동안의 전체 기록이 1,000개일 때, 한 페이지에서 볼 기록의 개수인 size 를 100으로 설정하면 기록을 100개씩 10페이지로 나누어 볼 수 있습니다. page 를 3으로 설정하면 전체 10페이지 중 3페이지의 기록인 301번째 기록부터 400번째 기록까지만 조회됩니다.

정산기록을 페이지 단위로 불러오는 기능을 구현할 때 편리하게 사용할 수 있습니다.

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


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

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

  • 더 궁금한 내용이 있나요?자주 묻는 질문
  • 코드 샘플을 참고하세요TossPayments GitHub
  • 기술지원이 필요한가요?디스코드 채팅|이메일 보내기