정산 조회하기
매출에서 정산 주기, 수수료율 등에 따라 금액을 계산해 지급하는 것을 정산이라고 합니다. 토스페이먼츠 정산내역을 조회하고 싶다면 정산 조회 API를 사용하세요. 특정 날짜 범위 내에서 일어난 결제의 정산 정보를 조회할 수 있습니다.
조회된 정산 정보로 지급 받을 금액 및 날짜, 수수료 정보 등을 확인한 뒤 내 상점의 데이터와 일치하는지 확인할 수 있습니다. 이렇게 정산 기록을 비교하는 일을 '정산 대사'라고 부르기도 합니다. '대사'란 기록을 비교・대조해서 데이터를 검증하고 일치시키는 과정을 뜻합니다.
정산 조회하는 방법
정산 조회 API를 사용할 때 dateType을 설정하면 정산 매출일과 정산 지급일 중 원하는 기준으로 조회할 수 있습니다.
soldDate(정산 매출일): 이 날까지의 결제 매출을 정산하겠다는 정산 기준 날짜를 의미합니다. 하루 단위의 일정산이라면 결제일, 한 주 단위의 주정산이라면 해당 주의 일요일, 한 달 단위의 월정산이라면 해당 월의 마지막 날이 정산 매출일입니다.paidOutDate(정산 지급일): 정산한 금액이 실제로 지급된 날짜를 의미합니다. 정산 매출일을 기준으로 계산합니다.
정산 매출일과 정산 지급일에 대한 더 자세한 설명은 용어사전 - 정산에서 확인하세요.
dateType 설정해서 조회하기
Query 파라미터로 dateType을 설정한 뒤 정산할 결제를 조회할 수 있습니다. 아래 요청은 dateType을 paidOutDate로 설정한 뒤 조회했기 때문에 2022년 1월 1일부터 1월 10일에 지급될 정산 데이터가 돌아옵니다.
dateType을 따로 설정하지 않으면 soldDate 기준으로 조회합니다. 2022년 1월 1일부터 1월 10일이 정산 매출일인 정산 데이터가 돌아옵니다.
curl --request GET \
--url 'https://api.tosspayments.com/v1/settlements?dateType=paidOutDate&startDate=2022-01-01&endDate=2022-01-10' \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='조회한 기간 동안의 정산 정보를 담은 객체의 배열이 응답으로 돌아옵니다.
[
{
"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"
}
// ...
]
정산 기록은 결제가 일어난 다음 날부터 조회됩니다. 따라서 만약 오늘이 1월 11일이라면, 1월 11일 결제의 정산 기록은 다음 날인 1월 12일에 startDate를 2022-01-11로, endDate를 2022-01-12로 요청해서 확인할 수 있습니다.
Case. 많은 양의 정산 기록을 나누어 조회하고 싶을 때
많은 양의 정산 기록을 조회한다면 page와 size 파라미터를 사용해서 페이지 단위로 기록을 나누어 조회할 수 있습니다.
아래와 같이 Query 파라미터로 page 와 size 값을 추가해보세요. 지정한 기간의 전체 기록 중 한 페이지 당 조회할 기록의 개수를 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 값 | 설정한 기간 중 조회되는 기록 |
|---|---|
| 1 | 1번째 정산 기록 ~ 100번째 정산 기록 |
| 2 | 101번째 정산 기록 ~ 200번째 정산 기록 |
| 3 | 201번째 정산 기록 ~ 300번째 정산 기록 |
| ... | ... |
| 10 | 901번째 정산 기록 ~ 1000번째(마지막) 정산 기록 |
정산 API를 활용해서 기록을 비교하는 작업을 '정산 대사'라고 부르기도 합니다.
'대사'란 기록을 비교/대조해서 데이터를 검증하고 일치시키는 과정입니다.