결제 및 거래 조회하기
토스페이먼츠 결제는 두 가지 방법으로 조회할 수 있습니다. 하나의 결제 건을 자세히 알아보고 싶다면 결제 기록을 조회하세요. 특정 기간에 일어난 모든 결제 승인 및 취소의 요약이 필요하다면 거래 내역을 조회하세요.
결제 기록 조회하기
결제 한 건의 결제 상태, 결제 취소 기록, 매출 전표, 현금영수증 정보 등을 자세히 확인해보세요.
결제 조회 API 사용하기
결제는 결제를 식별하는 paymentKey 또는 주문한 결제를 식별하는 주문 ID인 orderId로 조회할 수 있습니다. paymentKey는 최초 결제 승인 시점에 발급된 중복되지 않는 고유한 값이고, orderId는 결제를 요청할 때 가맹점에서 만들어서 사용한 값입니다. 두 값 모두 결제 데이터 관리를 위해 반드시 저장해야 하고, 결제 상태가 변해도 값이 유지됩니다.
결제 키로 조회하려면 아래와 같이 결제 조회 API 엔드포인트에 Path 파라미터로 paymentKey를 추가합니다. paymentKey는 토스페이먼츠에서 결제 승인과 함께 돌려주는 결제 키 값입니다.
curl --request GET \
--url https://api.tosspayments.com/v1/payments/Gir4uTTIM9T47VjpWRvm3 \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='주문 ID로 조회하려면 아래와 같이 결제 조회 API 엔드포인트에 Path 파라미터로 orderId를 추가합니다.
curl --request GET \
--url https://api.tosspayments.com/v1/payments/orders/cs79Cq9_RU5dlo9sUNGW4 \
--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 사용하기
거래 조회 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로 구분됩니다. transactionKey는 한 결제 건의 승인 거래와 취소 거래를 구분하는데 사용됩니다.
[
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"receiptUrl": "https://dashboard.tosspayments.com/receipt/redirection?transactionId=tosspayments&ref=PX",
"status": "DONE",
"transactionAt": "2022-01-03T12:11:34+09:00",
"currency": "KRW",
"amount": 10000
},
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"receiptUrl": "https://dashboard.tosspayments.com/receipt/redirection?transactionId=tosspayments&ref=PX",
"status": "DONE",
"transactionAt": "2022-01-06T11:53:08+09:00",
"currency": "KRW",
"amount": 10000
}
]
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": "",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"receiptUrl": "https://dashboard.tosspayments.com/receipt/redirection?transactionId=tosspayments&ref=PX",
"status": "DONE", // 결제 금액 지불 완료
"transactionAt": "2022-01-01T01:23:56+09:00",
"currency": "KRW",
"amount": 1000
},
{
"mId": "tosspayments",
"transactionKey": "",
"paymentKey": "",
"orderId": "",
"method": "카드",
"customerKey": "",
"useEscrow": false,
"receiptUrl": "https://dashboard.tosspayments.com/receipt/redirection?transactionId=tosspayments&ref=PX",
"status": "CANCELED", // 결제 취소
"transactionAt": "2022-01-01T01:23:58+09:00",
"currency": "KRW",
"amount": 1000
}
]