차액정산
영세·중소 사업자라면 카드 결제에 대해 우대 수수료율이 적용됩니다.
차액정산 API를 이용해 환급할 수수료를 정산하고, 정산 기록을 조회해보세요.
SettlementDifference 객체
차액정산 정보가 담긴 객체입니다. 거래 건 별 수수료를 각각 정산합니다.
requestId string
차액정산 한 건을 특정할 수 있도록 상점에서 직접 설정한 ID입니다.
settlementDifferenceKey string
차액정산 한 건에 대한 고유한 키 값입니다.
status string
SUCCESS - 정산이 요청되었습니다.
FAILED - 정산에 실패했습니다.
failure nullable · object
차액정산 요청이 실패된 경우 보내주는 정보입니다.
ㄴ code string
오류 타입을 보여주는 에러 코드입니다.
ㄴ message string
에러 메시지입니다. 에러 발생 이유를 알려줍니다.
payment object
정산받을 결제 건의 정보입니다.
ㄴ paymentKey string
정산해야 하는 결제 건을 특정하는 값입니다.
ㄴ payment.orderId string
가맹점에서 주문건에 대해 발급한 고유 ID입니다.
ㄴ payment.amount number
결제한 금액입니다.
ㄴ payment.type string
정산할 거래 건이 승인된 거래(CONFIRM)인지 취소된 거래(CANCEL)인지 알려줍니다.
ㄴ payment.cardType string
결제한 카드 종류입니다. 신용(CREDIT), 체크(CHECK), 기프트(GIFT)중 하나입니다.
subMall object
차액을 정산 받을 상점 정보입니다.
ㄴ sumMall.businessNumber string
서브몰 사업자등록번호 입니다.
ㄴ sumMall.salesAmount number
차액 정산을 받을 거래에 대한 서브몰 매출 금액입니다.
ㄴ salesGrade string
매출액을 기준으로 구분되는 서브몰의 영세·중소 사업자 등급 정보입니다.
•
GRADE0 - 영세 사업자 (매출액 3억 원 미만인 가맹점)
•
GRADE1 - 중소1 사업자 (매출액 3억 원 이상~5억 원 미만인 가맹점)
•
GRADE2 - 중소2 사업자 (매출액 5억 원 이상~10억 원 미만인 가맹점)
•
GRADE3 - 중소3 사업자 (매출액 10억 원 이상~30억 원 미만인 가맹점)
•
GRADE4 - 일반 사업자 (매출액 30억 원 초과인 가맹점)
ㄴ feeRate number
영세·중소 사업자 등급별로 달라지는 카드 수수료율 정보입니다.
payoutDate string
정산 금액이 지급될 날짜 정보입니다.
payoutAmount number
지급할 금액입니다.
transactionKey string
정산해야 하는 거래 건을 특정하는 값입니다.
metadata object
서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다.
차액정산 요청하기
POST /v2/settlement-differences
여러 서브몰의 차액정산 정보를 배열에 담아 한 번에 요청할 수 있습니다. 최대 요청 개수는 1회에 100건 입니다. 100건 이상을 요청하면 요청 실패 에러가 내려갑니다.
차액정산 요청은 매일 00:30에서 03:00 사이에 이루어져야하며, 03:00 이후에 이루어진 요청은 누락되기 때문에 다음날 요청시간에 다시 요청이 필요합니다.
Request Body 파라미터
requestId 필수 · string
차액정산 한 건을 특정할 수 있도록 상점에서 직접 설정한 ID입니다.
paymentKey 필수 · string
정산해야 하는 결제 건을 특정하는 값입니다.
transactionKey 필수 · string
정산해야 하는 거래 건을 특정하는 값입니다.
type 필수 · string
승인된 거래인지 취소된 거래인지 알려주는 값입니다. 승인된 거래라면 CONFIRM, 취소된 거래라면 CANCEL이 돌아옵니다.
subMall 필수 · object
차액을 정산 받을 서브몰 정보입니다.
ㄴ businessNumber 필수 · string
서브몰 사업자등록번호 입니다.
ㄴ salesAmount 필수 · number
이 거래에 대한 서브몰 매출 금액입니다.
metadata object
서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 객체 안에 key-value 쌍은 여러 개 포함해서 요청할 수 있습니다. key와 value 모두 문자열 형식이어야 합니다.
요청 예시
curl --request POST \
--url https://api.tosspayments.com/v2/settlement-differences \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '
"settlementDifferences": [
{
"requestId": "a4CWyWY5m89PNh7xJwhk1",
"paymentKey": "m0t1XuLXQwkO_Hnnqghx4",
"transactionKey": "5J2GGf1IwRXsWFLcAEykw",
"type": "CONFIRM",
"subMall" : {
"businessNumber": "1234567890",
"salesAmount": 15000
}
},
{
"requestId": "Hi24cE5W0GErYp-kuB18F",
"paymentKey": "m0t1XuLXQwkO_Hnnqghx4",
"transactionKey": "2mMhFFhtxvtpEuyGbkAWY",
"type": "CANCEL",
"subMall" : {
"businessNumber": "1234567890",
"salesAmount": 15000
}
}
]'
Shell
복사
1. SUCCESS
요청한 차액정산 건에 대해 정산이 완료되었습니다.
{
"settlementDifferences": [
{
"requestId": "QFjHQ1i4bsaI1oBpDssMX",
"status": "SUCCESS",
"failure": null,
},
{
"requestId": "wBz52FGgJ3wj0CljtZFRE",
"status": "SUCCESS",
"failure": null
}
]
}
JSON
복사
2. FAILED
차액정산 조회 요청에 실패했습니다.
{
"settlementDifferences": [
{
"requestId": "Acd540alkdwj9dKDasloW",
"status": "FAILED",
"failure": {
"code": "INVALID_PAYMENT_KEY",
"message": "잘못된 결제 키 입니다."
}
}
]
}
JSON
복사
에러 관련 내용은 별도 문서를 확인해주세요.
응답 예시
{
"settlementDifferences": [
{
"requestId": "QFjHQ1i4bsaI1oBpDssMX",
"status": "SUCCESS",
"failure": null,
},
{
"requestId": "wBz52FGgJ3wj0CljtZFRE",
"status": "SUCCESS",
"failure": null
},
{
"requestId": "Acd540alkdwj9dKDasloW",
"status": "FAILED",
"failure": {
"code": "INVALID_PAYMENT_KEY",
"message": "잘못된 결제 키 입니다."
}
}
]
}
JSON
복사
차액정산 기록 조회하기
GET /v2/settlement-differences
지정한 날짜 정보로 차액정산 기록을 조회합니다.
Query 파라미터
startDate 필수 · string
조회를 시작하고 싶은 날짜 정보입니다. ISO 8601 형식인 yyyy-MM-dd를 사용합니다.
(e.g. 2022-01-01)
endDate 필수 · string
조회를 시작하고 싶은 날짜 정보입니다. ISO 8601 형식인 yyyy-MM-dd를 사용합니다.
(e.g. 2022-01-01)
startingAfter string
특정 차액정산 한 건 이후의 기록을 조회하고 싶을 때 사용합니다. 차액정산 한 건을 특정하는 settlementDifferenceKey를 전달합니다. 많은 양의 기록을 페이지 단위로 나누어 처리할 때 사용할 수 있습니다.
limit integer
한 번에 응답받을 기록의 개수입니다. 기본값은 1000이고 설정할 수 있는 최대값은 10000입니다.
요청 예시
curl --request GET \
--url https://api.tosspayments.com/v2/settlement-differences?startDate=2022-01-01&endDate=2022-01-10 \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json'
Shell
복사
응답 예시
요청 당일 조회 시 검증 실패 및 일반등급 처리 결과가, 요청 다음날 조회 시 검증 성공 건에 대한 계산 결과가 조회됩니다.
{
"settlementDifferences": [
{
"requestId": "QFjHQ1i4bsaI1oBpDssMX",
"settlementDifferenceKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv2M9ENjbeoPaZdL6",
"status": "SUCCESS",
"failure": null,
"payment": {
"paymentKey": "m0t1XuLXQwkO_Hnnqghx4",
"orderId": "order1234",
"type": "CONFIRM",
"amount": 15000,
"cardType": "CREDIT"
},
"subMall": {
"businessNumber": "1234567890",
"salesGrade": "GRADE0"
"salesAmount": 15000,
"feeRate": 0.005
},
"payoutDate": "2022-01-03",
"payoutAmount": 75,
},
{
"requestId": "wBz52FGgJ3wj0CljtZFRE",
"settlementDifferenceKey": "2WkABYDxNyJQbgMGZzorzYWwKBG9kVl5E1em4dKva7XL9njP",
"status": "SUCCESS",
"failure": null,
"payment": {
"paymentKey": "m0t1XuLXQwkO_Hnnqghx4",
"orderId": "order1234",
"type": "CANCEL",
"amount": 15000,
"cardType": "CREDIT" // CREDIT, CHECK, GIFT
},
"subMall": {
"businessNumber": "1234567890",
"salesGrade": "GRADE0" // GRADE0(영세), GRADE1(중소1), GRADE2(중소2), GRADE3(중소3), GRADE4(일반)
}
}
]
}
JSON
복사
