결제 조회 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로 조회하려면 아래와 같이 결제 조회 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