정산 조회 API

매출에서 정산 주기, 수수료율 등에 따라 금액을 계산해 지급하는 것을 정산이라고 합니다. 정산 조회 API를 사용하면 특정 날짜 범위 내에서 일어난 결제의 정산 정보를 soldDate 기준으로 조회할 수 있습니다. 조회된 정산 정보를 통해 지급 받을 금액 및 날짜, 수수료 정보 등을 확인해보세요.

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

정산 조회 API 사용하기

Query 파라미터 startDateendDate로 조회할 기간을 설정해서 정산 기록을 조회할 수 있습니다. 정산 기록은 soldDate 기준으로 쌓이므로 조회 기간 파라미터에는 날짜 정보만 넣으면 됩니다.

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

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/settlements?startDate=2022-01-01&endDate=2022-01-10"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

조회한 기간 동안의 정산 정보를 담은 객체의 배열이 응답으로 돌아옵니다.

응답
[
{
"mId": "tosspayments",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"amount": 34000,
"interestFee": 0,
"fees": [
{
"type": "BASE",
"fee": "800"
},
{
"type": "INSTALLMENT",
"fee": "60"
}
],
"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,
"fees": [
{
"type": "BASE",
"fee": "1124"
},
{
"type": "INSTALLMENT",
"fee": "240"
}
],
"supplyAmount": 1240,
"vat": 124,
"payOutAmount": 13636,
"approvedAt": "2022-01-08T12:31:43+09:00",
"soldDate": "2022-01-08",
"paidOutDate": "2022-01-10"
}
// ...
]
JSON

정산 기록은 결제가 일어난 다음 날부터 조회됩니다. 따라서 만약 오늘이 1월 11일이라면, 1월 11일 결제에 대한 정산 기록은 다음 날인 1월 12일에 startDate2022-01-11로, endDate2022-01-12로 요청해서 확인할 수 있습니다.

Case. 많은 양의 정산 기록을 나누어 조회하고 싶을 때

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

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

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

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/settlements?startDate=2022-01-01&endDate=2022-02-01&size=100&page=3"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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

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

정산 API를 활용해서 기록을 비교하는 작업을 '정산 대사'라고 부르기도 합니다.

'대사'란 기록을 비교/대조해서 데이터를 검증하고 일치시키는 과정입니다.


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

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

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