자체 쇼핑몰이나 앱을 운영하면서 카카오페이 결제를 연동하고 싶은 개발자분들이 많아요. 카카오페이는 국내에서 가장 많이 사용되는 간편결제 서비스 중 하나로, 결제 전환율을 높이는 데 매우 효과적이에요. 카카오페이 결제 API는 REST 방식으로 제공되어 대부분의 언어와 플랫폼에서 쉽게 연동할 수 있어요.
이 글에서는 카카오페이 결제 API의 개요부터 연동 절차, 주요 API 흐름, 테스트 방법까지 개발자 친화적으로 안내해 드릴게요. 공식 문서를 기반으로 실제 연동에 도움이 될 핵심 내용을 정리했어요.
카카오페이 결제 API 시작하기
카카오 개발자 계정 등록
카카오페이 API를 사용하려면 먼저 카카오 개발자 센터(developers.kakao.com)에 가입하고 애플리케이션을 등록해야 해요. 앱 등록 후 REST API 키를 발급받는데, 이 키가 API 호출 시 인증 수단으로 사용돼요. 사업자의 경우 카카오페이 가맹점 계약을 별도로 진행해야 실제 결제를 받을 수 있어요.
카카오페이 가맹점 계약
카카오페이로 실제 결제를 받으려면 카카오페이 가맹점 신청이 필요해요. 카카오페이 비즈니스 페이지(business.kakao.com)에서 가맹점 신청을 할 수 있으며, 사업자등록증과 통장 사본 등 서류가 필요해요. 개인 개발자의 경우 개인사업자 등록 후 신청하거나, 테스트 환경에서만 활용할 수 있어요.
API 키 및 보안 설정
카카오 개발자 센터에서 발급받은 어드민 키(Admin Key)와 CID(가맹점 코드)가 API 호출에 필요해요. 어드민 키는 절대 클라이언트 사이드(브라우저, 앱 프론트엔드)에 노출되어서는 안 돼요. 반드시 서버 사이드에서만 사용하고, 환경 변수나 시크릿 매니저로 관리하는 것이 보안상 올바른 방법이에요.
카카오페이 단건 결제 API 흐름
1단계 – 결제 준비 요청 (Ready)
단건 결제의 첫 번째 단계는 결제 준비 API 호출이에요. 서버에서 카카오페이 결제 준비 API(POST /v1/payment/ready)를 호출하면 결제 고유 ID(tid)와 결제 URL이 반환돼요. 이 URL로 사용자를 리디렉션하면 카카오페이 결제 화면이 표시돼요. 파라미터로 가맹점 주문번호, 상품명, 금액, 리디렉션 URL 등을 전달해야 해요.
2단계 – 사용자 결제 승인
사용자가 카카오페이 화면에서 결제를 승인하면, 설정한 approval_url로 pg_token이 포함되어 리디렉션돼요. 이 pg_token을 받아 서버에서 결제 승인 API(POST /v1/payment/approve)를 호출하면 결제가 완료돼요. 성공 응답에는 결제 수단, 금액, 결제 시각 등의 정보가 담겨 있어요.
3단계 – 결제 완료 처리
결제 승인 응답을 받으면 서버에서 주문 상태를 ‘결제 완료’로 업데이트하고 사용자에게 결제 완료 페이지를 보여줘요. 이 과정에서 결제 정보를 데이터베이스에 저장하고, 필요시 이메일이나 카카오톡 메시지로 결제 영수증을 발송해요. tid는 이후 조회, 취소에 계속 활용되므로 반드시 저장해야 해요.
정기 결제 API (구독 서비스 연동)
정기 결제 개요
정기 결제는 구독 서비스나 자동 납부에 활용되는 API예요. 최초 1회 사용자 동의(SID 발급)를 받은 뒤, 이후에는 서버에서 자동으로 결제를 요청하는 구조예요. 월정액 서비스, 보험료 자동납부, 멤버십 구독 등에 적합해요.
SID 발급 절차
정기 결제 등록을 위해 먼저 ‘정기 결제 준비 API’를 호출해 결제 URL을 발급받아요. 사용자가 해당 URL에서 최초 결제에 동의하면 SID(정기 결제 ID)가 발급돼요. 이 SID를 서버에 저장해 두면 이후 정해진 주기마다 해당 SID로 자동 결제 요청을 보낼 수 있어요.
정기 결제 실행 및 관리
저장된 SID를 사용해 정기 결제 승인 API를 호출하면 사용자 확인 없이 자동으로 결제가 이루어져요. 결제 실패 시 재시도 로직, 실패 알림, 구독 해지 처리 등의 예외 처리를 서버에서 구현해야 해요. 정기 결제 해지는 사용자가 직접 하거나 API를 통해 서버에서 처리할 수 있어요.
결제 취소 API
전액 취소 방법
결제 완료된 건을 전액 취소하려면 취소 API(POST /v1/payment/cancel)를 호출해요. 파라미터로 tid(결제 ID), cancel_amount(취소 금액), cancel_tax_free_amount(비과세 취소 금액)를 전달해야 해요. 취소 성공 시 카카오페이에서 원래 결제 수단으로 환불 처리가 이루어져요.
부분 취소 구현
부분 취소는 전액 취소와 동일한 API를 사용하되, cancel_amount에 취소할 금액만 입력하면 돼요. 여러 번에 나누어 부분 취소할 수 있으며, 취소 가능 금액은 원래 결제 금액에서 이미 취소된 금액을 뺀 잔여분이에요. 부분 취소 내역도 tid로 조회할 수 있어요.
취소 불가 상황과 처리
이미 전액 취소된 거래에 추가 취소 요청을 하거나, 취소 금액이 결제 금액을 초과하는 경우 API 오류가 반환돼요. 오류 코드를 파싱해 적절한 오류 메시지를 사용자에게 표시해야 해요. 카카오페이 API 오류 코드 목록은 공식 문서에서 확인할 수 있어요.
결제 조회 API와 웹훅(Webhook)
결제 조회 API 활용
결제 조회 API(GET /v1/payment/{tid})를 사용하면 특정 결제의 현재 상태, 금액, 결제 수단, 취소 내역 등을 실시간으로 조회할 수 있어요. 결제 상태 동기화, 영수증 재발행, 고객 문의 처리 등에 활용할 수 있어요. 주문번호로 조회하는 API도 별도로 제공돼요.
웹훅(Webhook) 설정
카카오페이는 결제 완료, 취소 등의 이벤트 발생 시 서버에 자동으로 알림을 보내는 웹훅 기능을 제공해요. 카카오 개발자 센터에서 웹훅 URL을 등록하면 돼요. 웹훅을 활용하면 실시간으로 결제 상태 변경을 감지해 처리할 수 있어 신뢰성 높은 결제 시스템을 구축할 수 있어요.
멱등성(Idempotency) 처리
네트워크 오류 등으로 동일 요청이 중복 호출될 수 있어요. 카카오페이 API는 partner_order_id(가맹점 주문 ID)를 기반으로 중복 처리를 방지하는 로직이 있어요. 서버에서도 동일 주문 ID로 결제 준비가 이미 완료됐는지 체크하는 로직을 구현하는 것이 안전해요.
테스트 환경 구성 방법
테스트 CID 사용
카카오페이 API는 실제 결제 없이 테스트할 수 있는 테스트 환경을 제공해요. CID를 ‘TC0ONETIME'(단건 결제 테스트 코드)로 설정하면 실제 결제 없이 API 흐름을 테스트할 수 있어요. 정기 결제 테스트는 ‘TCSUBSCRIP’를 사용해요.
테스트 계정으로 결제 흐름 확인
테스트 환경에서는 카카오페이 앱의 테스트 계정 또는 개발자 계정으로 결제 승인 단계를 실제로 밟아볼 수 있어요. 이를 통해 결제 준비 → 사용자 승인 → 서버 승인 → 완료의 전체 흐름이 정상적으로 동작하는지 검증할 수 있어요. 오류 케이스도 테스트 환경에서 충분히 검증하는 것이 좋아요.
운영 환경 전환 시 체크리스트
- 테스트 CID를 실제 가맹점 CID로 교체
- 어드민 키 운영 환경 값으로 변경
- 웹훅 URL을 운영 서버로 업데이트
- 성공/실패 리디렉션 URL 운영 환경으로 변경
- SSL/TLS 인증서 확인 (HTTPS 필수)
마무리 – 카카오페이 API, 공식 문서와 함께 시작해요
카카오페이 결제 API는 REST 방식으로 제공되어 개발 경험이 있는 개발자라면 비교적 빠르게 연동할 수 있어요. 단건 결제부터 정기 결제, 취소, 조회까지 결제 서비스에 필요한 전반적인 기능이 제공돼요.
공식 카카오 개발자 문서(developers.kakao.com)와 카카오페이 개발자 가이드를 함께 참고하면서 테스트 환경에서 충분히 검증한 뒤 운영 환경에 적용하는 것을 추천해요. 안정적인 결제 시스템 구축에 이 글이 도움이 되길 바라요!