정산조회(대사) 서비스

이 문서에 대한 내용에 대한 문의는 토스페이먼츠 디스코드 사이트(https://discord.gg/44w6tQkw8N) 를 통해 언제든 가능합니다.

개요

어떤경우에 서비스 이용이 필요한가

PG사에서 발생하는 모든 결제/취소 발생 거래와 그에따른 대금 입/출금 데이터 수집이 필요할 경우
PG사 가맹점 관리자 내의 정산데이터를 자동으로 다운로드 하여, 가맹점 자체 ERP시스템과 연계하고자 할때

정산조회(대사) 관련하여 반드시 이해해야하는 용어 및 개념

온라인 전자결제에서의 구매자 결제 및 가맹점 정산 흐름
- 구매자는 가맹점에서 결제를 하고, 원천지불사(카드사,은행등)는 구매자에게 대금을 청구합니다
- PG사는 가맹점에 PG수수료를 제외한 결제대금을 지급합니다.
지불수단별로 프로세스는 상이하나, 아래는 신용카드 결제시의 흐름을 예시로 들었습니다.

하나의 거래는 최초 구매자의 거래 (결제,취소) 로 시작해서 가맹점의 대금 지급을 끝으로 완료됩니다.

주요용어 설명
- 거래일 : 결제 또는 취소가 발생한 일자를 의미합니다. 정산조회 API 에서는 결제일을 approvedAt 로 표기합니다.
- 정산일 : 가맹점 대급지급의 기준이 되는 일자를 의미합니다. 정산조회 API에서는 soldDate 로 표기합니다.
  - 일반거래 : 신용카드,계좌이체,가상계좌는 거래일과 동일합니다
```
               휴대폰결제,상품권은 계약내용에 따라 달라지게 됩니다.
```
  - 에스크로 거래 : 구매확정일 (승인) 및 구매거절승인일(취소) 를 의미합니다.
  cf) 승인, 취소거래에 대한 정산조회 API에서의 날짜 표기
```
  승인거래 :

  `approvedAt`  = 결제일

  `soldDate`  =   승인정산일
                          신용카드, 계좌이체, 가상계좌는  `approvedAt` 와 동일날짜입니다 . 
                          휴대폰결제와 상품권은 계약에 따라 달라집니다.

  취소거래 :

  `approvedAt`  = 최초결제일

  `soldDate`  =  취소정산일
                         신용카드 계좌이체 가상계좌는 취소일자와 동일날짜입니다. 
                         휴대폰결제와 상품권은 계약에 따라 달라집니다.
```
- 정산지급일 : 가맹점의 계좌로 결제대금을 지급(취소거래는 차감) 하는 일자를 의미합니다. 정산조회API에서는 paidOutDate 로 표기합니다.
- 정산대금 : 결제대금에서 수수료를 차감한, 가맹점에서 PG사로부터 지급받는 금액을 의미합니다. 정산조회API에서는 paidOutAmount 로 표기합니다
- 정산주기 : 정산일을 기준으로 가맹점에게 대금을 지급(또는 차감)하는 시점을 의미합니다.
```
정산주기는 가맹점계약시 설정되며 가맹점별/지불수단별로 상이합니다.
```
- 통상적으로 “정산일 + 정산주기(영업일기준)” 으로 계약이 됩니다
- paidOutDate (정산지급일)은 soldDate (정산일) 과 정산주기에 따라 결정이 됩니다
ex) 신용카드의 정산주기가 정산일 (D) + 3 (영업일 기준)이라고 했을때, 만일 어떤 신용카드 거래의 soldDate(정산일) 이 2022-07-30 (토) 이면, paidOutDate(지급일)은 2022-08-03(수) 이 됩니다. (비영업일인 07-31은 제외)
- 수수료 : 결제금액에서 PG서비스 사용대가로 차감한 금액을 의미합니다. 정산조회 API에서는 fees 객체 - fee 로 표기합니다
  - 수수료는 보통 결제금액의 몇% 와 같은 비율로 차감되며, PG계약시 지불수단별로 비율을 결정하게 됩니다. 일부 지불수단은 몇%(정률) 가 아닌 . 결제건당 XX원(정액) 과 같이 계약이 될수도 있습니다. API에서 정산비율 정보를 리턴하지는 않습니다.
  거래상태에 따른 예시를 들면 아래와 같습니다.
  
  주문번호 123456 : 승인상태로, 가맹점에서는 지급일에 26700원을 지급받습니다
```
                            (결제금액에 수수료와 부가세 차감)
```
  주문번호 234567 : 동일한 날에 결제와 취소가 함께 발생한 거래로, 승인상태 : 17800원 지급,
  취소상태 : 17800원 차감으로, 결과적으로 지급받을 금액은 0원 입니다.
  
  주문번호 456789 : 8/1 에 결제되었으나, 8/2에 취소된 주문으로, 승인상태에 대한 지급은 위 표에는 없지만 8/4 에 지급받았습니다. 8/5에는 취소상태에 대한 차감만 받습니다
  
  위 네건을 총 합산하면, 가맹점은 8/5에 총 17800원의 대금을 지급받습니다.
  - 수수료의 종류 : 거래건별로 차감되는 수수료의 종류로, 정산조회 API 에서는 fees-type 으로 반환됩니다
    - 신용카드수수료 : 신용카드 결제에 대해 거래금액별, 거래건별로 공통적으로 부과되는 수수료입니다 .API 에서는 BASE 로 반환됩니다
    - 무이자할부수수료 : 신용카드 거래 중 무이자할부 거래에서 발생하는 항목으로, 이는 다시 상점부담 무이자수수료와 카드사부담 무이자수수료로 나뉩니다
      - 상점부담무이자 : 고객은 무이자로 결제하고, 할부수수료는 가맹점에서 부담하는 결제입니다. 별도의 특약을 맺어야 발생되는 거래로서, API에서는 INSTALLMENT 로 반환됩니다.
      - 카드사부담무이자 : 고객은 무이자로 결제하고, 할부수수료는 카드사 또는 토스페이먼츠에서 부담하는 거래입니다. 별도의 계약이 없어도 적용이 되고 있습니다. API에서는 INSTALLMENT_DISCOUNT 로 반환됩니다.
    - 카드사포인트적립 수수료 : 신용카드 거래중 카드+포인트 복합결제, 그 중 포인트 적립결제에서만 반환됩니다. 별도의 특약을 맺어야 발생되는 거래로서, API에서는 POINT_SAVING으로 반환됩니다
    - 기타수수료 : 신용카드 이외의 지불수단에 부과되는 기본수수료를 의미합니다. API에서는 ETC로 반환됩니다
  - 수수료의 부가세 (VAT) :
    - PG사에서 청구 및 차감하는 PG수수료는 부가세가 포함되어 청구됩니다.
    - 정산조회 API에서 공급가는 supplyAmount 로 표기하며 부가세는 vat 로 표기합니다
    - 수수료 계산식
      
      공급가액 = 건별 거래금액 X 수수료율(vat별도) _ 원단위 미만 첫째자리에서 내림
      
      부가세액 = 공급가액 X 10% _ 원단위 미만 첫째자리에서 반올림
      
      ex) 신용카드 결제금액이 10000원이고, 수수료가 4.0% 일때
      
      공급가액 = 10000 * 0.04 = 400원 (결제금액 * 수수료율이 공급가가 됨)
      
      부가세액 = 400원 * 0.1 = 40원
    총 수수료 = 440원
  - 취소거래의 수수료 처리
    - 신용카드, 휴대폰결제, 상품권과 같은 비현금성 결제는 승인당시 차감된 수수료가 그대로 반환됩니다
      - 부분취소의 경우 일정 비율 및 산식에 따라 반환됩니다.
    - 계좌이체, 가상계좌와 같은 현금성 결제는 거래를 취소하더라도 승인당시 차감된 수수료가 반환되지 않습니다.
  - 부분취소 거래의 수수료처리
    
    부분취소 계산식
    - 부분취소금액 ÷원 거래금액 = 부분취소비율(a)
    - (원거래금액 X 수수료율) X 부분취소비율(a) = 부분취소 수수료(b)_전단위 절사
    ex) 승인 : 100원, 2% → 수수료 2원 / 부분취소 : -50원, 부분취소율 50%(50/100), 2X50% = 1원
    
    → 부분취소율을 구한 후에, 부분취소금액에 부분취소율로 수수료율 산출
    
    ※ 위 계산로직으로 실제 확정된 수수료(공급가액, 부가세)와 정산 건별내역 생성시의 수수료(공급가액, 부가세)가 상이할 경우 거래금액이 큰 순서로 1원씩 보정
```
   승인시의 차감수수료 :  10000원 X 5% → 500원 (공급가) + 50원(vat) = 550원 
```
거래조회(대사) 와 연계하여 함께 이해해야하는 용어 및 개념

아래 용어를 거래조회 가이드에서 확인해 주시기 바랍니다.

⇒ paymentKey , transactionKey

⇒ soldOutDate (거래발생일, 지급금액 정산기준일)

: 지급금액 정산 기준일로, 결제일 및 취소일을 의미합니다.

케이스별로 보는 정산조회 API 응답결과 예시

(아래 예시는 API 버전 2022-06-08 이상 기준입니다.)
- 신용카드
- 계좌이체
- 가상계좌
- 휴대폰결제

개요

어떤경우에 서비스 이용이 필요한가

정산조회(대사) 관련하여 반드시 이해해야하는 용어 및 개념

거래조회(대사) 와 연계하여 함께 이해해야하는 용어 및 개념

케이스별로 보는 정산조회 API 응답결과 예시