정산 조회하기
매출에서 정산 주기, 수수료율 등에 따라 금액을 계산해 지급하는 것을 정산이라고 합니다. 토스페이먼츠 정산내역을 조회하고 싶다면 정산 조회 API를 사용하세요. 특정 날짜 범위 내에서 일어난 결제의 정산 정보를 조회할 수 있습니다.
조회된 정산 정보로 지급 받을 금액 및 날짜, 수수료 정보 등을 확인한 뒤 내 상점의 데이터와 일치하는지 확인할 수 있습니다. 이렇게 정산 기록을 비교하는 일을 '정산 대사'라고 부르기도 합니다. '대사'란 기록을 비교・대조해서 데이터를 검증하고 일치시키는 과정을 뜻합니다.
정산 조회 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": "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
},
//...
]
정산 기록은 결제가 일어난 다음 날부터 조회됩니다. 따라서 만약 오늘이 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를 활용해서 기록을 비교하는 작업을 '정산 대사'라고 부르기도 합니다.
'대사'란 기록을 비교/대조해서 데이터를 검증하고 일치시키는 과정입니다.