토스페이 연동가이드

각 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

정산 내역 리스트 - 최대 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 Request

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

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
}

정산 API

엔드포인트

요청 파라미터

옵션 파라미터

응답 파라미터

예제

Example Request

Example Response

목차