목차

매출에서 정산 주기, 수수료율 등에 따라 금액을 계산해 지급하는 것을 정산이라고 합니다. 토스페이먼츠 정산내역을 조회하고 싶다면 정산 조회 API를 사용하세요. 특정 날짜 범위 내에서 일어난 결제의 정산 정보를 조회할 수 있습니다.

조회된 정산 정보로 지급 받을 금액 및 날짜, 수수료 정보 등을 확인한 뒤 내 상점의 데이터와 일치하는지 확인할 수 있습니다. 이렇게 정산 기록을 비교하는 일을 '정산 대사'라고 부르기도 합니다. '대사'란 기록을 비교・대조해서 데이터를 검증하고 일치시키는 과정을 뜻합니다.

샘플 프로젝트정산 조회 API 샘플 프로젝트입니다.

정산 조회 API 사용하기

정산 조회 API를 사용할 때 dateType을 설정하면 정산 매출일과 정산 지급일 중 원하는 기준으로 조회할 수 있습니다.

  • soldDate(정산 매출일): 이 날까지의 결제 매출을 정산하겠다는 정산 기준 날짜를 의미합니다. 하루 단위의 일정산이라면 결제일, 한 주 단위의 주정산이라면 해당 주의 일요일, 한 달 단위의 월정산이라면 해당 월의 마지막 날이 정산 매출일입니다.
  • paidOutDate(정산 지급일): 정산한 금액이 실제로 지급된 날짜를 의미합니다. 정산 매출일을 기준으로 계산합니다.

정산 매출일과 정산 지급일에 대한 더 자세한 설명은 용어사전 - 정산에서 확인하세요.

dateType 설정해서 조회하기

Query 파라미터로 dateType을 설정한 뒤 정산할 결제를 조회할 수 있습니다. 아래 요청은 dateTypepaidOutDate로 설정한 뒤 조회했기 때문에 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": "xLpgeoO7410238740297423RBKEzMjPJyG",
"transactionKey": "497BF239847238947B0491D84B4",
"orderId": "EjBNtZK7j8q2TlGFLJ-9T",
"currency": "KRW",
"method": "카드",
"fees": [
{
"type": "BASE",
"fee": -2250
},
{
"type": "ETC",
"fee": 0
}
],
"approvedAt": "2021-12-30T13:03:39+09:00",
"soldDate": "2021-12-30",
"paidOutDate": "2022-01-01",
"card": {
"issuerCode": "11",
"acquirerCode": "11",
"number": "55704251****800*",
"installmentPlanMonths": 3,
"isInterestFree": true,
"interestPayer": "CARD_COMPANY",
"approveNo": "30024234",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"amount": 99800
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"easyPay": null,
"cancel": {
"transactionKey": "497BF239847238947B0491D84B4",
"cancelReason": "주문취소",
"taxExemptionAmount": 0,
"canceledAt": "2021-12-30T13:40:03+09:00",
"easyPayDiscountAmount": 0,
"receiptKey": null,
"cancelAmount": 99800,
"taxFreeAmount": 0,
"refundableAmount": 0
},
"amount": -99800,
"interestFee": 0,
"fee": -2250,
"supplyAmount": -2045,
"vat": -205,
"payOutAmount": -97550
},
{
"mId": "tosspayments",
"paymentKey": "jvX2KBP9Q21349087239084706yLYlaEJ7",
"transactionKey": "70CEDA72394802394F24AD80C6",
"orderId": "EoSLagnG8KmcmetaUrEna",
"currency": "KRW",
"method": "간편결제",
"fees": [
{
"type": "BASE",
"fee": 1195
},
{
"type": "ETC",
"fee": 116
}
],
"approvedAt": "2021-12-30T23:58:41+09:00",
"soldDate": "2021-12-30",
"paidOutDate": "2022-01-01",
"card": {
"issuerCode": "41",
"acquirerCode": "41",
"number": "51073761****913*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "47042234",
"useCardPoint": false,
"cardType": "체크",
"ownerType": "개인",
"acquireStatus": "READY",
"amount": 53030
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"easyPay": {
"provider": "네이버페이",
"amount": 0,
"discountAmount": 0
},
"cancel": null,
"amount": 53030,
"interestFee": 0,
"fee": 1311,
"supplyAmount": 1192,
"vat": 119,
"payOutAmount": 51719
},
{
"mId": "tosspayments",
"paymentKey": "oYwn6qbDZOAQ1239472398vdk4El1Bp0J5",
"transactionKey": "4E202B23498729847322CA68371CB3",
"orderId": "LNnUye-w3A44V2iLmHLFK",
"currency": "KRW",
"method": "카드",
"fees": [
{
"type": "BASE",
"fee": 935
},
{
"type": "ETC",
"fee": 0
}
],
"approvedAt": "2021-12-30T09:34:34+09:00",
"soldDate": "2021-12-30",
"paidOutDate": "2022-01-01",
"card": {
"issuerCode": "41",
"acquirerCode": "41",
"number": "54287966****537*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "36284234",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"amount": 41500
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"easyPay": null,
"cancel": null,
"amount": 41500,
"interestFee": 0,
"fee": 935,
"supplyAmount": 850,
"vat": 85,
"payOutAmount": 40565
},
{
"mId": "tosspayments",
"paymentKey": "evl2J94098172430982374mA1QXRyZ4gLw",
"transactionKey": "EDAD0A8F2349048230948460F533B",
"orderId": "Dri1BWRA8Le-ezwDseJYJ",
"currency": "KRW",
"method": "계좌이체",
"fees": [
{
"type": "ETC",
"fee": 26
}
],
"approvedAt": "2021-12-30T13:54:05+09:00",
"soldDate": "2021-12-30",
"paidOutDate": "2022-01-01",
"card": null,
"virtualAccount": null,
"transfer": {
"bankCode": "92",
"settlementStatus": "INCOMPLETED"
},
"mobilePhone": null,
"giftCertificate": null,
"easyPay": null,
"cancel": null,
"amount": 2000,
"interestFee": 0,
"fee": 26,
"supplyAmount": 24,
"vat": 2,
"payOutAmount": 1974
},
//...
]
JSON

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

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를 활용해서 기록을 비교하는 작업을 '정산 대사'라고 부르기도 합니다.

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

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