정산 API

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

엔드포인트

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

요청 파라미터

apiKeystring필수

가맹점 API Key

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

dateTypestring필수

기준 날짜의 형태

조회 시 기준 날짜의 형태

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

baseDatestring필수

조회 날짜

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

승인일 기준 최대 1년까지 조회 가능하며, 1년이 지난 데이터는 조회할 수 없습니다.
당일 자 데이터 조회는 제한됩니다.

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
}

소개