거래 조회 API

하나의 결제에 대해 발생하는 승인과 취소 각각을 거래라고 합니다. 같은 paymentKey를 가지고 있는 거래에 대해서는 개별 거래 건을 특정하는 transactionKey로 구분할 수 있습니다.

거래 조회 API를 사용하면 특정 날짜 범위 내에서 일어난 모든 거래 정보를 transactionAt 기준으로 조회할 수 있습니다. 조회된 거래 기록을 매출 기록과 비교하며 확인해보세요.

API를 사용하기 위해 필요한 키 정보와 인증 방식, 보안에 대한 정보는 API 사용하기에서 자세히 알아보세요.

거래 조회 API 사용하기

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

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

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00.000&endDate=2022-01-10T23:59:59.999"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

조회한 기간 동안의 거래 기록이 응답으로 돌아옵니다.

응답
[
{
"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밀리초(millisecond) 단위까지 시간 정보에 포함해서 요청해야 합니다.

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

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00.000&endDate=2022-01-01T23:59:59.999"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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

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

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/transactions?startDate=2022-01-01&endDate=2022-01-01"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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

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

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

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

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00.000&endDate=2022-01-10T23:59:59.999&startingAfter=5OhJr1hOealGAknFDLN16"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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를 자세히 알아보세요

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

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