결제 조회 API
결제 조회 API를 사용해서 승인·취소된 특정 결제 기록을 다시 확인하거나 해당 결제의 세부 정보를 활용할 수 있습니다.
한 건의 결제에 대해 결제 상태, 결제 취소 기록, 매출 전표, 현금영수증 정보 등을 자세히 확인해보세요.
API를 사용하기 위해 필요한 키 정보와 인증 방식, 보안에 대한 정보는 API 사용하기에서 자세히 알아보세요.
결제 기록을 조회하는 두 가지 방법
결제 기록을 조회하는 방법에는 결제 키로 조회하는 방법과 주문 ID로 조회하는 방법 두 가지가 있습니다.
paymentKey는 토스페이먼츠에서 결제 승인과 함께 돌려주는 결제 키 값이고, orderId는 상점에서 주문 건을 구분하기 위해 직접 발급한 고유 ID입니다. 응답은 동일하게 Payment 객체가 돌아옵니다.
원하는 방법으로 결제 기록을 조회해보세요.
결제 키로 조회하기
결제 키로 조회하려면 아래와 같이 결제 조회 API 엔드포인트에 Path 파라미터로 paymentKey를 추가합니다.
요청
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.tosspayments.com/v1/payments/ZYl4kNYSFX-i2q9xqWhGg"))
.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());응답으로 paymentKey에 매칭되는 Payment 객체가 돌아옵니다.
응답
{
"mId": "tosspayments",
"version": "1.4",
"paymentKey": "",
"orderId": "",
"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,
"card": {
"company": "현대",
"number": "433012******1234",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": 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
}
JSON
paymentKey로 결제 조회하기 API를 자세히 알아보세요
paymentKey로 결제 조회하기 API를 직접 실행해보세요
주문 ID로 조회하기
주문 ID로 조회하려면 아래와 같이 결제 조회 API 엔드포인트에 Path 파라미터로 orderId를 추가합니다.
요청
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.tosspayments.com/v1/payments/orders/W7cVS-eiOZ9vyukjPboNw"))
.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());응답으로 orderId에 매칭되는 Payment 객체가 돌아옵니다.
응답
{
"mId": "tosspayments",
"version": "1.4",
"paymentKey": "",
"orderId": "",
"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,
"card": {
"company": "현대",
"number": "433012******1234",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": 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
}
JSON