결제 승인 및 취소 기록 조회하기

하나의 결제에 대해 발생하는 승인과 취소 각각을 '거래'라고 합니다.

토스페이먼츠에서 제공하는 거래 조회 API를 통해 승인과 취소 건 각각의 정보, 거래 상태 등을 조회한 뒤 내 상점의 데이터와 일치하는지 확인할 수 있습니다. 이렇게 거래 기록을 비교하는 일을 '거래 대사'라고 부르기도 합니다. '대사'란 기록을 비교/대조해서 데이터를 검증하고 일치시키는 과정을 뜻합니다.

거래 조회 API 사용하기

Query 파라미터 startDateendDate로 조회할 기간을 설정해서 거래 기록을 조회할 수 있습니다. 거래 기록은 거래가 처리된 시점(transactionAt)을 기준으로 조회합니다. 거래가 일어난 당일부터 거래 기록을 조회할 수 있습니다.

예를 들어 아래 요청은 2022년 1월 1일부터 1월 10일까지 일어난 거래를 조회합니다.

요청
curl --request GET \
  --url 'https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00&endDate=2022-01-10T23:59:59' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

조회한 기간 동안의 거래 기록이 응답으로 돌아옵니다. 같은 paymentKey를 가지고 있는 거래가 transactionKey로 구분됩니다.

응답
[
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"amount": 10000,
"status": "DONE",
"transactionAt": "2022-01-03T12:11:34+09:00"
},
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"amount": 10000,
"status": "DONE",
"transactionAt": "2022-01-06T11:53:08+09:00"
}
]
JSON

Case 1. 하루 동안의 거래 기록을 조회하고 싶을 때

하루 동안의 거래 기록을 조회하려면 startDateendDate에 초 단위까지 시간 정보에 포함해서 요청해야 합니다.

예를 들어 2022년 1월 1일 하루 동안의 기록 전체를 조회하려면 아래와 같이 startDate2022-01-01T00:00:00로, endDate2022-01-01T23:59:59로 설정해야 합니다.

요청
curl --request GET \
  --url 'https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00&endDate=2022-01-01T23:59:59' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

응답으로 2022-01-01T00:00:00 부터 2022-01-02T00:00:00 전까지의 기록이 돌아옵니다.

만약 거래 기록 조회의 Query 파라미터에 날짜 정보만 있다면 시간은 자동으로 00:00:00으로 설정된다는 점을 유의하세요.

요청
curl --request GET \
  --url 'https://api.tosspayments.com/v1/transactions?startDate=2022-01-01&endDate=2022-01-01' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

위와 같이 startDateendDate가 시간 정보 없이 같은 날짜로 설정되어 있다면 자동 시간 설정으로 인해 동일한 날짜와 시간을 가리키게 됩니다. 따라서 위 2022년 1월 1일 0시 0분 0초 정각에 난 거래만 조회됩니다.

Case 2. 특정 거래 기록 이후부터 조회하고 싶을 때

특정 거래 기록 이후부터 조회하고 싶다면 startingAfter에 특정하고 싶은 거래의 transactionKey 값을 넣어주면 됩니다.

예를 들어 아래 요청은 2022년 1월 1일부터 1월 10일 사이의 거래 기록 중 paymentKey가 '5OhJr1hOealGAknFDLN16'인 기록 다음 건부터 거래 기록을 조회합니다.

요청
curl --request GET \
  --url 'https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00&endDate=2022-01-10T23:59:59&startingAfter=5OhJr1hOealGAknFDLN16' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

Case 3. 같은 paymentKey를 가진 거래 기록이 있을 때

거래 조회 응답에서 paymentKey가 같고 transactionKey는 다른 여러 개의 거래 기록이 배열로 들어올 수 있습니다. 하나의 결제 건에 대해 금액 지불, 결제 취소, 결제 부분 취소와 같이 여러 번의 거래가 일어날 수 있기 때문입니다.

응답으로 돌아온 객체의 status 값을 보면 어떤 거래가 이루어졌는지 알 수 있습니다.

응답
// paymentKey가 ''인 결제에 대해 각각 지불/취소된 거래 기록 응답 예시
[
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"amount": 1000,
"status": "DONE", // 결제 금액 지불 완료
"transactionAt": "2022-01-01T01:23:56+09:00"
},
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"amount": 1000,
"status": "CANCELED", // 결제 취소
"transactionAt": "2022-01-01T01:23:58+09:00"
}
]
JSON

거래 조회 API를 자세히 알아보세요

거래 조회 API를 직접 실행해보세요

내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기