결제 및 거래 조회하기
토스페이먼츠 결제는 두 가지 방법으로 조회할 수 있습니다. 하나의 결제 건을 자세히 알아보고 싶다면 결제 기록을 조회하세요. 특정 기간에 일어난 모든 결제 승인 및 취소의 요약이 필요하다면 거래 내역을 조회하세요.
결제 기록 조회하기
결제 한 건의 결제 상태, 결제 취소 기록, 매출 전표, 현금영수증 정보 등을 자세히 확인해보세요.
결제 조회하는 방법
결제는 결제 키 또는 주문 ID로 조회할 수 있습니다.
결제 키로 조회하려면 아래와 같이 결제 조회 API 엔드포인트에 Path 파라미터로 paymentKey를 추가합니다. paymentKey는 토스페이먼츠에서 결제 승인과 함께 돌려주는 결제 키 값입니다.
curl --request GET \
--url https://api.tosspayments.com/v1/payments/aRHTdgVaxzXuqExbEuRuO \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='주문 ID로 조회하려면 아래와 같이 결제 조회 API 엔드포인트에 Path 파라미터로 orderId를 추가합니다. orderId는 상점에서 발급한 주문 ID입니다.
curl --request GET \
--url https://api.tosspayments.com/v1/payments/orders/VxNYqmy4pn9lVxfzsv4BA \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='응답 확인하기
응답으로 결제 키 또는 주문 ID에 해당하는 Payment 객체가 돌아옵니다.
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"orderId": "",
"transactionKey": "",
"lastTransactionKey":"",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "카드",
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"checkout": {
"url": "https://api.tosspayments.com/v1/payments//checkout"
},
"card": {
"issuerCode": "61",
"acquirerCode": "31",
"number": "43301234****123*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": null,
"cashReceipts": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0,
"taxExemptionAmount": 0
}
거래 내역 조회하기
결제 한 건에서 발생하는 승인과 취소 각각을 '거래'라고 합니다.
토스페이먼츠에서 제공하는 거래 조회 API로 승인과 취소 건 각각의 정보, 거래 상태 등을 조회한 뒤 내 상점의 데이터와 일치하는지 확인할 수 있습니다. 이렇게 거래 기록을 비교하는 일을 '거래 대사'라고 부르기도 합니다. '대사'란 기록을 비교/대조해서 데이터를 검증하고 일치시키는 과정을 뜻합니다.
거래 조회하는 방법
거래 조회 API에 Query 파라미터로 startDate와 endDate를 추가해서 특정 기간의 거래 기록을 조회할 수 있습니다. 거래 기록은 거래가 처리된 시점(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=='응답 확인하기
응답으로 조회한 기간 동안의 일어난 거래가 Transaction 객체로 돌아옵니다. 같은 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"
}
]
Case 1. 하루 동안의 거래 기록을 조회하고 싶을 때
하루 동안의 거래 기록을 조회하려면 startDate와 endDate에 초 단위까지 시간 정보에 포함해서 요청해야 합니다.
예를 들어 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으로 설정된다는 점을 유의하세요.
curl --request GET \
--url 'https://api.tosspayments.com/v1/transactions?startDate=2022-01-01&endDate=2022-01-01' \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='위와 같이 startDate와 endDate가 시간 정보 없이 같은 날짜로 설정되어 있다면 자동 시간 설정으로 인해 동일한 날짜와 시간을 가리키게 됩니다. 따라서 위 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"
}
]