거래·정산 조회 API
특정 기간 동안의 거래·정산 기록을 조회합니다. 매출 기록과 토스페이먼츠의 거래·정산 기록을 비교할 때 사용합니다.
API를 사용할 때 필요한 키 정보와 인증 방식, 보안 정보는 API 사용하기에서 더 자세히 알아보세요.
거래 조회 API 사용하기
Query 파라미터 startDate와 endDate로 조회할 기간을 설정해서 거래 기록을 조회할 수 있습니다.
예를 들어 아래 요청은 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=='조회한 기간 동안의 거래 기록이 응답으로 돌아옵니다.
[
{
"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"
}
]
Case 1. 하루 동안의 거래 기록을 조회하고 싶을 때
하루 동안의 거래 기록을 조회하려면 startDate와 endDate에 밀리초(millisecond) 단위까지 시간 정보에 포함해서 요청해야 합니다.
예를 들어 2022년 1월 1일 하루 동안의 기록 전체를 조회하려면 아래와 같이 startDate를 2022-01-01T00:00:00로, endDate를 2022-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으로 설정된다는 점을 유의하세요. startDate와 endDate가 시간 정보 없이 같은 날짜로 설정되어 있다면 응답으로 돌아오는 기록은 없습니다.
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"
}
]
정산 조회 API 사용하기
Query 파라미터 startDate와 endDate로 조회할 기간을 설정해서 정산 기록을 조회할 수 있습니다.
정산 기록은 날짜 정보를 기준으로 쌓이기 때문에 날짜 정보만 있어도 기록을 조회할 수 있습니다.
예를 들어 아래 요청은 2022년 1월 1일부터 1월 10일 까지 일어난 거래 기록을 조회합니다.
curl --request GET \
--url 'https://api.tosspayments.com/v1/settlements?startDate=2022-01-01&endDate=2022-01-10' \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='조회한 기간 동안의 정산 기록이 응답으로 돌아옵니다.
[
{
"mId": "tosspayments",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"amount": 34000,
"interestFee": 0,
"fee": 860,
"supplyAmount": 782,
"vat": 78,
"payOutAmount": 33140,
"approvedAt": "2021-12-30T12:30:09+09:00",
"soldDate": "2021-12-30",
"paidOutDate": "2022-01-01"
},
// ...
{
"mId": "tosspayments",
"paymentKey": "",
"orderId": "",
"currency": "KRW",
"method": "카드",
"amount": 15000,
"interestFee": 0,
"fee": 1364,
"supplyAmount": 1240,
"vat": 124,
"payOutAmount": 13636,
"approvedAt": "2022-01-08T12:31:43+09:00",
"soldDate": "2022-01-08",
"paidOutDate": "2022-01-10"
}
// ...
]
Case. 많은 양의 정산 기록을 나누어 보여주고 싶을 때
많은 양의 정산 기록을 조회한다면 page와 size 파라미터를 사용해서 페이지 단위로 기록을 나누어 보여줄 수 있습니다.
아래와 같이 Query 파라미터로 page 와 size 값을 추가해보세요. 지정한 기간의 전체 기록 중 한 페이지 당 보여줄 기록의 개수를 size로, 나누어진 페이지 중 조회할 페이지를 page로 지정할 수 있습니다.
예를 들어 아래 요청은 설정한 기간 동안의 전체기록을 100개씩 나누어 보여주고, 전체 페이지 중 3페이지의 기록을 조회합니다.
curl --request GET \
--url 'https://api.tosspayments.com/v1/settlements?startDate=2022-01-01&endDate=2022-02-01&size=100&page=3' \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='만약 전체 기록이 1000개라면 기록을 100개씩 10페이지로 나누어 불러올 수 있고, 전체 10페이지 중 3페이지의 기록인 301번째 기록부터 400번째 기록까지 조회됩니다.
| page 값 | 설정한 기간 중 조회되는 기록 |
|---|---|
| 1 | 1번째 정산 기록 ~ 100번째 정산 기록 |
| 2 | 101번째 정산 기록 ~ 200번째 정산 기록 |
| 3 | 201번째 정산 기록 ~ 300번째 정산 기록 |
| ... | ... |
| 10 | 901번째 정산 기록 ~ 1000번째(마지막) 정산 기록 |
이 페이지에서 다루는 API의 용도를 '대사'라고 부르기도 합니다. '대사'란 거래·정산 기록을 조회해서 상세히 비교하는 작업을 뜻합니다.