카카오페이 결제 연동: 단건결제 API 흐름과 테스트 방법

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

카카오페이 결제 연동은 서비스의 주문과 카카오페이 결제 승인을 연결하는 작업입니다. 직접 API를 사용하는 방식과 PG 결제창을 거치는 방식이 있습니다. 오늘은 직접 연동의 준비·인증·승인 흐름과 테스트 방법을 알아보겠습니다.

카카오페이 직접 연동과 PG 경유 방식

카카오페이 API를 직접 연동하는 방식

서버의 결제 준비·승인 API와 사용자 인증 화면을 연결합니다. 취소와 실패 처리, 주문 검증도 구현 범위에 포함되며, 다른 결제수단을 추가할 때는 별도 연동이 필요할 수 있습니다.

결제수단이 여럿이면 PG 경유가 관리하기 쉽습니다.

포트원 문서를 보면 카카오페이는 간편결제(EASY_PAY) 수단으로 채널에 추가해 쓰게 되어 있습니다. PG 결제창 구조는 저희가 앞서 정리한 토스페이먼츠 연동 방법 총정리 글에 있으니, 여기서는 직접 연동을 중심으로 이어가겠습니다.

카카오 디벨로퍼스가 아니라 카카오페이 개발자센터에서 시작합니다

카카오 로그인을 붙여 본 분들이 여기서 자주 헷갈립니다. 카카오페이 결제 API는 카카오페이 개발자센터(developers.kakaopay.com)에서 관리합니다.

카카오페이 개발자센터 전환 가이드에 따르면 카카오 개발자센터에서 제공하던 (구)온라인 결제 API는 kapi.kakao.com 도메인에 어드민 키(KakaoAK)를 썼습니다. 2024년부터 안내되는 신규 API는 open-api.kakaopay.com 도메인에 SECRET_KEY 헤더를 쓰고 JSON으로 요청합니다. 새 연동에서는 현재 개발자센터의 API와 인증 방식을 기준으로 구현합니다.

먼저 비즈니스 계정으로 애플리케이션을 등록해 Secret key를 받은 뒤 [애플리케이션] > [플랫폼] > [Web]에 서비스 도메인을 등록합니다. 여기에 비즈앱 전환과 온라인 결제 API 사용 권한까지 받으면 준비가 끝납니다. Secret key는 테스트용(dev)과 운영용이 따로 나오는데, 결제에 쓰는 키라서 서버에만 둡니다.

단건결제 API는 준비, 인증, 승인 세 번의 흐름입니다

결제 준비(ready)에서 tid와 결제 화면 주소를 받습니다.

서버가 가맹점 코드(cid), 주문번호, 상품명, 금액, 성공·취소·실패 URL을 담아 요청합니다.

POST https://open-api.kakaopay.com/online/v1/payment/ready
Authorization: SECRET_KEY ${SECRET_KEY}
Content-Type: application/json

응답에는 결제 고유번호 tid와 PC·모바일 웹·앱용 결제 화면 URL이 담겨 옵니다. tid는 서버에 저장해 두고 클라이언트는 환경에 맞는 URL로 이동합니다.

사용자 인증이 끝나면 approval_url로 pg_token이 돌아옵니다.

사용자가 카카오페이 화면에서 결제수단을 고르고 비밀번호로 인증을 마치면 approval_url 뒤에 pg_token이 쿼리스트링으로 붙어 돌아옵니다. 공식 문서 기준으로 결제 요청이 15분을 넘기면 fail_url로 이동합니다.

결제 승인(approve)을 호출해야 결제가 완료됩니다.

서버가 tid와 pg_token, 준비 때와 같은 주문번호·회원 id로 /online/v1/payment/approve를 호출합니다. 인증만 받고 승인을 빠뜨리면 결제는 완료되지 않습니다. 서버에 보관한 주문과 tid·금액을 대응시키고 승인 결과를 확인한 뒤 주문을 확정합니다.

테스트 가맹점 코드로 먼저 돌려보고 계약을 붙입니다

계약 전에는 TC0ONETIME으로 결제 흐름을 확인합니다.

카카오페이 개발자센터는 단건결제 테스트용 가맹점 코드 TC0ONETIME과 Secret key(dev) 조합을 안내합니다. 테스트용 결제수단을 사용하는 환경이며 실제 출금 여부와 테스트 화면의 안내를 구분해 확인합니다.

실제 결제에는 가맹점 계약 후 받는 CID가 필요합니다.

카카오페이 비즈니스 파트너센터에서 온라인 가맹점을 신청하고 심사를 마치면 애플리케이션 Client ID 기준으로 실 CID가 발급됩니다. 심사 기간과 서류는 신청 시점 안내로 확인하시면 됩니다.

구독 상품이라면 정기결제 CID를 따로 받습니다.

정기결제는 별도로 발급받은 CID로 첫 결제를 하고 그때 받은 sid로 2회 차부터 결제를 요청합니다. 단건결제 CID로는 정기결제를 할 수 없으니 계약 단계에서 같이 정해 둡니다.

세부 항목과 최신 적용 조건은 카카오페이 단건결제 가이드를 참고해 보세요.

익숙한 카카오페이 결제를 우리 서비스에서도

결제 흐름을 하나씩 붙이다 보면 화면뿐 아니라 데이터와 운영 방식도 함께 살펴보게 됩니다. 지금 서비스에 필요한 범위부터 차근차근 정리해볼 수 있습니다.

똑똑한개발자는 UX/UI 디자인과 웹·앱 개발을 함께 진행합니다. 사용자가 이용하는 화면과 운영에 필요한 기능을 연결해 서비스를 만들어가는 과정을 돕습니다.

결제 흐름을 준비하면서 궁금한 점이 있다면 아래 똑똑한개발자 링크로 편하게 이야기 남겨주세요. 함께 살펴보겠습니다. 감사합니다. :)