결제 정산 API

PHP Java curl Python Ruby ASP

토스 정산 API 소개

토스 결제 서비스를 통한 매출과 정산 금액 확인을 위한 API 입니다.
페이징 개념을 적용하였고 페이징의 단위는 1,000 건으로 다음 페이징이 존재하면 nextCursor 라는 응답값이 리턴됩니다.
그 후 nextCursor 를 포함하여 호출하면 바로 다음의 페이징 데이터가 리턴됩니다.

용어

용어 및 정의

지급일

결제 금액을 가맹점의 결제 계좌로 입금한 날입니다.

거래 승인일

결제, 환불 등 거래가 실제로 일어난 날입니다.

정산 API

endpoint

(POST)

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

parameters

apiKey string

가맹점 key
Test apiKey도 입력은 가능하나 테스트 결제는 실제 지급되지 않기 때문에 정산 대상이 아니라서 수수료 계산(0원)이나 지급일자(빈값) 등 계산을 건너뛰게 됩니다.

dateType string

조회 시 기준 날짜의 형태

DUE	지급일 (정산 계좌에 입금된 또는 입금될 날짜)
SETTLE	거래 승인일 (유저가 결제한 시점의 날짜)

baseDate string

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

payMethod string

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

TOSS_MONEY	토스머니
CARD	카드
RESELLER_CARD	리셀러 카드(리셀러 가맹점에만 해당)

nextCursor string

호출할 페이징의 cursor 값을 나타냅니다. 정산 API 호출 후 리턴되는 응답값을 다음의 정산 API 호출 시 파라미터로 사용하면 됩니다.
해당 파라미터가 추가되지 않고 API 가 호출되면 무조건 첫 페이징 데이터가 리턴됩니다. (index : 0 ~ 999)

OPTION PARAMETERS

includeSettleDateTime

응답으로 '거래 처리 일시' 가 필요한 경우 URI query string 으로 includeSettleDateTime=true 를 넘겨주시면 됩니다.
호출 URI 예시) https://pay.toss.im/pay/api/v2/settlement-details?includeSettleDateTime=true

RESPONSE

transactionList json

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

transactionType: 거래종류

PAY: 결제

REFUND: 환불

transactionId: 거래 고유 번호

결제 및 환불 시의 거래 고유 번호

동일 결제 건의 부분 환불을 여러번 할 때, 각각의 부분 환불건을 구분하기 위함

settleDate: 거래 승인일

dueDate: 정산일 (지급일)

payToken: 토스 결제 토큰

orderNo: 가맹점의 상품 주문번호

productDesc: 상품 설명

payMethod : 결제 수단

TOSS_MONEY : 토스머니

CARD : 카드

RESELLER_CARD : 리셀러 카드

amount: 금액
결제는 '+',
환불은 '-'로 표시됨

fee: 수수료
수수료 부과는 '-',
전액 환불 등 사유로 수수료를 돌려드리는 경우 '+'로 표시됨

vat: 부가세
부가세 부과는 '-',
전액 환불 등 사유로 부가세를 돌려드리는 경우 '+'로 표시됨

feeVatSum: 수수료 + 부가세

nextCursor string

API 호출 이후 다음 페이징 영역에 데이터가 존재하면 커서 값이 리턴됩니다.
마지막 페이징이었다면 빈 스트링이 리턴됩니다.

totalAmount Integer

총 금액 합산
(페이징별 합산금액이 아닌) 조회된 전체 건에 대한 총 금액 합산

totalFee Integer

총 수수료 합산
(페이징별 합산금액이 아닌) 조회된 전체 건에 대한 총 수수료 합산

totalVat Integer

총 부가세 합산
(페이징별 합산금액이 아닌) 조회된 전체 건에 대한 총 부가세 합산

totalFeeVatSum Integer

총 수수료 + 부가세의 합산 (totalFee + totalVat)
(페이징별 합산금액이 아닌) 조회된 전체 건에 대한 총 수수료+부가세 합산

settleDateTime string

거래 처리 일시
최종 거래 상태가 승인(PAY) 일 경우는 승인 처리 시각, 환불(REFUND) 일 경우는 환불 처리 시각이 yyyyMMddHHmmss 형태로 리턴됩니다.
단, includeSettleDateTime=true 를 포함해서 호출한 경우에만 리턴합니다.

Definition

POST https://pay.toss.im/pay/api/v2/settlement-details

Example Request

{ 
    "apiKey": "(example) sk_test_1234567...",
    "dateType": "DUE",
    "baseDate": "20240314",
    "payMethod": "TOSS_MONEY"
 // "nextCursor": "99ElA9EGCTJwXpYygHsBnA=="  // call with nextCursor
}

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,
            "payMethod": "TOSS_MONEY",
            "feeVatSum": -44,
            "settleDate": "20240313",
            "dueDate": "20240314"
        },
        {
            "transactionType": "PAY",
            "transactionId": "7ba71e5c-28d2-4d8b-946e-6f6b5b3a3205",
            "payToken": "example-payToken",
            "productDesc": "상품 2",
            "orderNo": "order2",
            "payMethod": "TOSS_MONEY",
            "amount": 33000,
            "fee": -132,
            "vat": -13,
            "payMethod": "TOSS_MONEY",
            "feeVatSum": -145,
            "settleDate": "20240313",
            "dueDate": "20240314"
        },
        {     
             .....
        }
    ],
    "nextCursor": "",
    "totalAmount": 407000,
    "totalFee": -1628,
    "totalVat": -163,
    "totalFeeVatSum": -1791
}