개요
•
가맹점과 토스페이먼츠가 각각 저장하고 있는 거래정보 및 거래의 상태는 일치가 되는것이 이상적인 상태입니다
•
다만, 운영중 발생하는 여러가지 이슈에 의해 양사간의 거래건수 및 거래상태의 불일치가 발생할수가 있습니다. 불일치가 발생하는 경우는 여러가지가 있겠으나, 대표적으로
◦
결제진행중 시스템 및 네트워크 오류등으로 인해, 결제승인결과를 정상적으로 수신하지 못한 경우
◦
가맹점 시스템이 아닌 토스페이먼츠 상점관리자에서 주문상태 변경을 했을경우
◦
원천사 (카드사,은행등) 의 이슈로 거래상태가 변경되는 경우
와 같은 케이스가 있습니다
•
이러한 거래불일치를 보완하기 위해, API를 통해 거래정보를 수신하여 양사간 데이터를 비교검증하는 서비스를 거래조회 (대사) 서비스라고 합니다.
어떤경우에 서비스 이용이 필요한가
•
가맹점 자체 주문관리시스템을 운영하며, 가맹점-토스페이먼츠간 거래를 정확히 일치시켜야 하는 경우
•
가맹점관리자 내의 거래승인내역 다운로드의 자동화가 필요하거나, 대량의 거래발생으로 엑셀다운로드를 통한 거래내역 조회가 불편할 경우
거래조회(대사) 관련하여 반드시 이해해야하는 용어 및 개념
•
트랜잭션 (Transaction) , 트랜잭션 키 (transactionKey)
◦
트랜잭션 : 결제, 취소, 부분취소 등과 같이 최초 거래시작 , 거래상태의 변경과 관련한 흐름을 트랜잭션이라고 합니다.
ex) 결제완료상태인 주문은, 승인이라는 하나의 트랜잭션으로 이루어진 거래입니다.
취소완료상태인 주문은 , 두개의 트랜잭션 (승인트랜잭션, 취소트랜잭션)으로 이루어진 거
래입니다
결제완료 후 총 3회의 부분취소가 완료된 거래는
1회의 승인트랜잭션 + 3회의 취소트랜잭션 = 4회의 트랜잭션이 발생된 거래입니다.
◦
트랜잭션 키 : 거래 각각의 트랜잭션을 구분짓는 고유한 키입니다.
•
paymentKey :
◦
결제건에 대한 고유한 키값으로, 최초 결제승인 발생시에만 1회 생성됩니다.
◦
토스페이먼츠내에서 발생한 전체가맹점 전체거래에서, 개별 거래를 식별하는 유일한 키값입니다.
◦
결제상태가 변경되더라도 paymentKey는 변경되지 않으며 유지됩니다.
◦
paymentKey는 토스페이먼츠에서 생성하는 값입니다. 이와 유사한 개념으로 주문번호 (orderId) 가 있습니다. 주문번호는 최초 결제시 가맹점에서 생성하여 요청하는 값입니다.
◦
생성위치만 다를뿐, paymentKey 와 orderId는 모두 가맹점 내에서 발생된 거래를 식별할 수 있는 유일한 값이라는 성격을 가지고 있습니다. 이 특성을 이용하여, 거래대사(조회)시에는, orderId 를 키값으로, 가맹점과 토스페이먼츠의 거래를 매핑할 수 있습니다
◦
가맹점에서 결제요청을 하였고, 정상승인까지 되었으나 시스템문제로 승인결과를 받지 못했을경우, 양사 공통으로 저장한 paymentKey 및 주문번호로 거래상태를 조회하여, 거래오류를 보정할수 있습니다
단, 주문번호와 paymentKey를 일대일로 매칭하기 위해서는, 주문번호도 paymentKey처럼 반드시 중복되지 않는 고유한 값으로 설정해주셔야 합니다
•
paymentKey 와 transactionKey 의 관계
◦
paymentKey 는 최초 결제 발생시 생성되는 거래구분값입니다.
◦
transactionKey 는 최초 결제발생 또는 결제상태의 변경시 생성되는, 거래상태 생성,변경 흐름을 구분하는 값입니다.
ex) 결제완료 직후의 신용카드 거래가 있을때 이 거래는
paymentKey : 1234567890 , transactionKey : abcdefgh 가 생성됩니다.
이후 1회차 부분취소를 하게 되면, paymentKey 는 1234567890 으로 고정되나, transactionKey
는 ijklmnopqr 로 신규생성됩니다 (최초 승인 트랜잭션과 구분하기 위해)
다시 2회차 부분취소를 하게 되면, 마찬가지로 paymentKey 는 1234567890 으로 고정되나,
transactionKey는 stuvwxyzABCDE 로 신규생성됩니다 (최초 승인 트랜잭션 및 1회차 부분취소와 구분하기 위해)
•
거래일시 (transactionAt):
결제 트랜잭션이 발생한 일시를 의미합니다. 즉 결제일도 되고, 취소일도 됩니다.
API에서는 ISO8601 규격에 따라 yyyy-MM-dd'T'HH:mm:ss±hh:mm 로 응답합니다
ex) 거래일이 2022-02-01 인 거래 ⇒ 결제일 또는 취소일 (부분취소일 포함) 이 2022-02-01인 거래
를 의미합니다
•
거래조회 API 사용시 주의할점
◦
거래시작일 (startDate) 및 거래종료일 (endDate)
▪
API에 설정한 거래시작일과 거래종료일을 입력받으면, 거래조회 API에서는
startDate ≤ 거래일 AND endDate ≥ 거래일 의 조건으로 거래내역을 검색합니다. AND 조건이기 때문에 두 조건이 모두 만족해야 합니다. (따라서, 당연히 startDate 는 endDate 보다 과거 일시여야 합니다
또한 startDate 와 endDate 파라미터에 날짜 정보만 기재할경우 (ex: 2022-01-01) 시간은 자동으로 00:00:00.000으로 설정됩니다.
예를 들어 2022년 1월 1일 하루 동안의 기록 전체를 조회하려면
startDate를 2022-01-01T00:00:00.000 로, endDate를 2022-01-01T23:59:59.999로 설정합니다.
특정시간대 사이의 기록 전체를 조회하려면 (ex: 2022년 1월 1일 15시~16시까지 거래)
startDate를 2022-01-01T00:15:00.000 로, endDate를 2022-01-01T15:59:59.999로
설정 합니다.
•
limit 파라미터
API를 한번 호출했을때, 한꺼번에 내려받을수 있는 transaction 수 입니다
설정하지 않으면 기본값은 100이고 , 최대 10000 까지 설정가능합니다. 일종의 페이징 처리
개념으로 설정하는 값이라고 보시면 되겠습니다.
하루에 10000건 이상의 거래가 발생할 경우, 한꺼번에 많은 데이터를 다운로드 할 경우, 다운
로드 중간에 연결이 끊어지거나, 서버에 부하가 발생할수 있습니다. 거래시작일, 거래종료일
과 함께 limit 파라미터를 적절히 이용하시어, 적절한 건수의 데이터를 분할하여 다운로드하
는것을 권장합니다.
•
startingAfter 파라미터
이 파라미터에 특정 거래의 트랜잭션키 (transactionKey) 를 입력하면, 해당 거래 이후에 발생한 모든 거래를 거래시간 순서대로 출력합니다. 해당 거래건은 포함되지 않습니다.
거래건이 매우 많아 분할조회가 필요할때, startingAfter 와 limit 를 조합하여 사용하면, 많은 양의 기록을 페이지 단위로 나누어 처리할 수 있습니다.
거래조회가 가능한 시점
•
트랜잭션 (결제 및 취소)이 발생한 직후부터 조회가 가능합니다.
ex) 거래조회 API 를 2022-08-01 01:00:00 에 호출했을경우, 2022-08-01 01:00:00 이전에 트랜
잭션 (결제, 취소)이 발생한 주문은 모두 수집할 수 있습니다.
활용예시
•
거래기간으로 조회 (startDate, endDate)
◦
설정한 기간 사이에 발생한 모든 거래를 수집합니다.
◦
일단위 배치작업을 통해, 전일자 가맹점 발생 전체거래와 토스페이먼츠 전체거래를 일대일로 비교하고자 할때 유용합니다 (거래대사)
•
startingAfter 파라미터의 활용
ex) 2022-01-01 일 발생한 거래 전체를 다운로드 하려고 하는데, 이날 발생한 거래가 5만건일때
⇒ startDate = 2022-01-01T00:00:00 , endDate = 2022-01-01T23:59:59 만 설정하면, 최대 다운로드 건수인 1만건을 초과하기 때문에, 10001번째 거래부터는 수집이 불가하기 때문에 분할로 다운로드를 실행해야 합니다.
⇒ 이때 두번째 수집시, 10000만번째 수집 데이터의 transactionKey를 설정하게 되면, 직전 다운로드 거래 이후건부터 순차적으로 다운로드 할수 있습니다.
a.
startDate = 2022-01-01T00:00:00 , endDate = 2022-01-01T23:59:59 설정후 API호출
⇒ 1만건 다운로드 , 마지막 거래 트랜잭션 ID 저장
b. startDate = 2022-01-01T00:00:00 , endDate = 2022-01-01T23:59:59, a의 마지막 거래 트랜잭션 ID설정후 API호출 ⇒ 1만건 다운로드 , 마지막 거래 트랜잭션 ID 저장
c. startDate = 2022-01-01T00:00:00 , endDate = 2022-01-01T23:59:59, b의 마지막 거래 트랜잭션 ID설정후 API호출 ⇒ 1만건 다운로드 , 마지막 거래 트랜잭션 ID 저장
d. startDate = 2022-01-01T00:00:00 , endDate = 2022-01-01T23:59:59, c의 마지막 거래 트랜잭션 ID설정후 API호출 ⇒ 1만건 다운로드 , 마지막 거래 트랜잭션 ID 저장
e. startDate = 2022-01-01T00:00:00 , endDate = 2022-01-01T23:59:59, d의 마지막 거래 트랜잭션 ID설정후 API호출 ⇒ 1만건 다운로드 , 총 5만건 다운로드 완료
거래대사 결과의 주문상태
READY - 준비됨
IN_PROGRESS - 진행중
WAITING_FOR_DEPOSIT - 가상계좌 입금 대기 중
DONE - 결제 완료됨
CANCELED - 결제가 취소됨
PARTIAL_CANCELED - 결제가 부분 취소됨
ABORTED - 카드 자동 결제 혹은 키인 결제를 할 때 결제 승인에 실패함
EXPIRED - 유효 시간(30분)이 지나 거래가 취소됨