📌 PortOne 결제 시스템 - 결제 취소 및 본인인증 확인 API 구현하기

📅 2025-05-15

📝 학습 내용

✅ 1. 결제 취소 API 개념

PortOne(아임포트)의 결제 취소 API는 이미 승인된 결제에 대해 환불을 요청하는 기능이다.

imp_uid 또는 merchant_uid 중 하나를 기반으로 특정 결제를 식별해 취소할 수 있다.

• 즉시 취소 가능: 카드결제, 휴대폰소액결제
• 별도 계좌 입력 필요: 가상계좌, 익월 휴대폰 결제

---

✅ 2. 결제 취소 API 요청 코드 (Spring Boot)

@GetMapping("/payments/cancel")
@ResponseBody
public void payments_cancel(){
    log.info("GET/portOne/payment/cancel...");

    String url = "<https://api.iamport.kr/payments/cancel>";

    HttpHeaders header = new HttpHeaders();
    header.add("Content-Type", "application/json");
    header.add("Authorization", "Bearer " + this.portOneTokenResponse.getResponse().getAccess_token());

    JSONObject params = new JSONObject();
    params.put("imp_uid", "imp_************************"); // 결제 고유번호 (마스킹 처리)
    params.put("merchant_uid", "merchant_************"); // 상점 주문번호 (마스킹 처리)

    HttpEntity<String> entity = new HttpEntity<>(params.toString(), header);

    RestTemplate rt = new RestTemplate();
    ResponseEntity<String> response = rt.exchange(url, HttpMethod.POST, entity, String.class);

    System.out.println(response.getBody());
}

---

✅ 3. 본인인증 결과 조회 API

@GetMapping("/certifications/{imp_uid}")
@ResponseBody
public void certifications(@PathVariable("imp_uid") String imp_uid){
    log.info("GET/portOne/certifications/" + imp_uid);

    String url = "<https://api.iamport.kr/certifications/>" + imp_uid;

    HttpHeaders header = new HttpHeaders();
    header.add("Authorization", "Bearer " + this.portOneTokenResponse.getResponse().getAccess_token());
    header.add("Content-Type", "application/json");

    HttpEntity<?> entity = new HttpEntity<>(header);

    RestTemplate rt = new RestTemplate();
    ResponseEntity<String> response = rt.exchange(url, HttpMethod.GET, entity, String.class);

    System.out.println(response);
}

---

✅ 4. 본인인증 조회 실습 방법

브라우저에서 테스트할 때는 다음과 같이 입력하면 된다:

<http://localhost:8090/portOne/certifications/imp_************************>

• 위 URL의 imp_uid는 인증 완료 후 아임포트에서 콜백으로 전달받은 실제 값으로 교체
• 본인인증은 사전 절차(휴대폰 인증 등)를 통해 발급된 imp_uid가 있어야 한다

---

🔥 정리

구분	설명
API 종류	결제 취소, 본인인증 조회
요청 방식	POST (결제 취소), GET (본인인증)
주요 파라미터	imp_uid 또는 merchant_uid
헤더 설정	Content-Type: application/json, Authorization: Bearer access_token
실습 팁	imp_uid는 인증 완료 후 콜백 또는 응답으로 전달됨

---

🔗 참고 자료

• PortOne 결제 취소 API 문서
• PortOne 본인인증 조회 API 문서

---

느낀 점

결제 시스템에서 환불 처리는 사용자 경험과 직결되며, 기술적으로도 민감한 영역이다.

이번 실습을 통해 access_token 발급 → API 인증 → 파라미터 구성 → 응답 확인까지 전체 흐름을 손에 익힐 수 있었다.

특히 본인인증 결과를 조회할 수 있다는 점은 향후 사용자 계정 보호나 가입 흐름에서도 중요한 기능이 될 수 있음을 느꼈다.

실제 프로젝트에서 유저 환불 처리나 본인확인 로직에 바로 적용할 수 있는 기반이 잡힌 것 같다.

---

요약

• ✅ 결제 취소는 POST 방식, JSON 포맷으로 imp_uid or merchant_uid 전달
• ✅ 본인인증은 GET 방식, imp_uid PathVariable로 전달
• ✅ 모두 access_token 포함한 Authorization 헤더 필수
• ✅ 실습 시 실제 인증 후 imp_uid 확보 필요

---