카카오페이 API 단건 결제 방법 정리

카카오페이 결제 API는 카카오페이 개발자센터에서 제공된다.
해당 링크를 통해 카카오페이 개발자센터로 이동할 수 있다.
> https://developers.kakaopay.com/

카카오페이 디벨로퍼 홈페이지 접속 화면

 

※ 주의사항

카카오 디벨로퍼 (https://developers.kakao.com/) 와는

다른 사이트이므로 혼동하지 않도록 하자.

---

1. KakaoPay Developers 애플리케이션 등록

카카오페이 API를 사용하기 위해서는

KakaoPay Developers 에서 애플리케이션을 등록해야 한다.

애플리케이션 등록 완료 시 확인할 수 있다.

1. 로그인
2. 애플리케이션 메뉴에서 등록
3. 기본 정보 입력
4. 테스트 환경에서는 Secret Key(dev) 발급받아 사용

나는 개인 프로젝트를 로컬에서만 테스트하기 때문에
테스트용 Secret Key(dev)만 발급받아 진행하였다.

 

 

카카오페이 개발자센터의 Secret Key는

결제 API 인증에 사용되는 중요한 값이다.

이 Key가 유출되면 결제 기능 전체가

위험해지므로 절대 깃허브에 올리면 안 된다.

 

※ 톰캣과 같은 로컬 네트워크를 쓰고 있다면?

위 이미지와 같이 플랫폼 탭에서 Web 부분에

내 핵심 도메인 주소(로컬)를 등록해주면 된다!

---

2. 단건 결제 API 활용

카카오페이 단건 결제는 아래 3단계로 이루어진다.

1) 결제 준비 (ready)

2) 사용자 결제 페이지로 이동 (redirect)

3) 결제 승인 (approve)

각 단계를 하나씩 알아보자.

 

2-1. 결제 준비 (Ready API)

서버가 카카오페이 서버에

결제 정보를 먼저 등록하는 단계이다.

필요한 정보는 다음과 같다.

가맹점 코드(CID)
> 개인 테스트용 CID: " TC0ONETIME"
주문번호(order_id)
상품명
결제 금액
결제 완료 시 돌아올 URL (success)
결제 취소/실패 URL

 

요청 성공 시 카카오페이는 다음 값을 응답한다.

tid : 결제 고유 번호
next_redirect_pc_url : 사용자가 이동할 결제창 URL

서버는 이 URL을 브라우저로 redirect 시켜

결제창을 띄우면 된다.

 

2-2. 결제 요청 (사용자 카카오페이 결제창 이동)

next_redirect_pc_url 로 사용자를 보내면
카카오페이 결제창이 뜬다.

 

사용자가 결제를 완료하면
등록해둔 success URL로 pg_token 이 전달된다.

http://localhost:8080/pay/success?pg_token=xxxx

이 pg_token이 있어야 최종 결제 승인을 할 수 있다.

 

2-3. 결제 승인 (Approve API)

서버는 다음 값을 이용하여 카카오페이에 결제 승인 요청을 보낸다.

• cid
• tid
• pg_token
• 결제 금액 정보

요청이 성공하면 결제는 최종 승인된다.

승인 시 카카오페이가 결제 완료 정보 전체를 반환한다.
(주문번호, 결제 시간, 결제 수단, 결제 금액 등)

---

3. Secret Key와 CID 관리 방식

API 키를 코드에 직접 넣지 않고
application.properties 로 관리하자.

kakao.secret_key=발급받은_시크릿키
kakao.cid=TC0ONETIME

 

그 후 서비스 코드에서
@Value 로 불러와 사용하면 된다.

이 방식은 아래와 같은 이유로 안전하다.

• 깃허브에 노출되지 않음
• 운영/개발 환경 분리 가능
• 키 유출 시 결제 API 전체가
  사고로 이어지므로 별도 관리가 필수

---

4. API 요청 시 반드시 지켜야 할 사항

- Authorization 헤더에 Secret Key 포함

Authorization: SECRET_KEY {시크릿키}

 

API 요청은 반드시 서버에서만 호출해야 한다

• 프론트에서 호출하면 키가 그대로 노출되기 때문에 매우 위험하다

테스트 CID는 "제공 받은 테스트 코드"

• 운영 환경에서는 실제 발급받은 CID 사용해야 한다

ready → redirect → approve 순서를 반드시 지켜야 한다

• 세 단계가 완성되어야 결제가 정상적으로 진행된다

---

▼ 전체 흐름 요약

1. 서버 → ready API → tid 발급
2. 서버 → 사용자에게 카카오페이 결제창 redirect
3. 사용자 결제 완료 후 pg_token 반환
4. 서버 → approve API로 결제 승인

이 순서가 카카오페이 단건 결제의 전체 구조이다.

카카오페이 결제 API는 구조만 이해하면 어렵지 않다.
핵심은 다음 두 가지이다.

• tid + pg_token 흐름을 정확히 이해할 것
• Secret Key를 안전하게 관리할 것

이 두 가지만 지키면 개인 프로젝트에서도
카카오페이 결제를 안전하게 구현할 수 있다.