정산 API

각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.

엔드포인트

POSThttps://pay.toss.im/api/v2/settlement-details

요청 파라미터

apiKeystring필수

가맹점 API Key

Test API Key도 입력은 가능하나 테스트 결제는 실제 지급되지 않으므로 정산 대상이 아닙니다.

dateTypestring필수

기준 날짜의 형태

조회 시 기준 날짜의 형태

값	설명
DUE	지급일 (정산 계좌에 입금된 날짜)
SETTLE	거래 승인일 (결제 시점의 날짜)

baseDatestring필수

조회 날짜

조회하고자 하는 날짜 (yyyyMMdd 형식)

payMethodstring

결제수단

조회하고자 하는 결제수단 (보내지 않거나 null로 보내면 모든 결제수단에 대해 응답)

값	설명
TOSS_MONEY	토스머니
CARD	카드
RESELLER_CARD	리셀러 카드

nextCursorstring

페이징 cursor 값

파라미터가 추가되지 않으면 첫 페이징 데이터가 리턴됩니다.

옵션 파라미터

includeSettleDateTimestring

거래 처리 일시 포함 여부

'거래 처리 일시'가 필요한 경우 URI query string으로 includeSettleDateTime=true를 추가합니다. 예: https://pay.toss.im/pay/api/v2/settlement-details?includeSettleDateTime=true

Example Request

{
  "apiKey": "(example) sk_test_1234567...",
  "dateType": "DUE",
  "baseDate": "20240314",
  "payMethod": "TOSS_MONEY"
}

응답 파라미터

transactionListjson

정산 내역 리스트

정산 내역 리스트 - 최대 1000개

필드	설명
transactionType	거래종류 (PAY: 결제, REFUND: 환불)
transactionId	거래 고유 번호 (부분 환불 구분)
settleDate	거래 승인일
dueDate	정산일 (지급일)
payToken	토스 결제 토큰
orderNo	가맹점의 상품 주문번호
productDesc	상품 설명
payMethod	결제 수단 (TOSS_MONEY, CARD, RESELLER_CARD)
amount	금액 (결제: '+', 환불: '-')
fee	수수료 (부과: '-', 환불 시 '+')
vat	부가세 (부과: '-', 환불 시 '+')
feeVatSum	수수료 + 부가세

nextCursorstring

커서 값

다음 페이징 데이터가 있으면 커서 값을 반환, 마지막 페이징일 경우 빈 스트링을 반환

totalAmountinteger

총 금액 합산

조회된 전체 건의 총 금액 합산

totalFeeinteger

총 수수료 합산

조회된 전체 건의 총 수수료 합산

totalVatinteger

총 부가세 합산

조회된 전체 건의 총 부가세 합산

totalFeeVatSuminteger

총 수수료 + 부가세 합산

총 수수료 + 부가세 합산 (totalFee + totalVat)

settleDateTimestring

거래 처리 일시

거래 처리 일시 (yyyyMMddHHmmss 형태) includeSettleDateTime=true로 호출한 경우에만 리턴

Example Response

{
    "transactionList": [
        {
            "transactionType": "REFUND",
            "transactionId": "3084ed5d-3267-4ea0-af1c-064bdf0b1462",
            "payToken": "example-payToken",
            "productDesc": "상품 1",
            "orderNo": "order1",
            "payMethod": "TOSS_MONEY",
            "amount": 10000,
            "fee": -40,
            "vat": -4,
            "feeVatSum": -44,
            "settleDate": "20240313",
            "dueDate": "20240314"
        },
        ...
    ],
    "nextCursor": "",
    "totalAmount": 407000,
    "totalFee": -1628,
    "totalVat": -163,
    "totalFeeVatSum": -1791
}

소개