온라인 쇼핑몰이나 서비스에 카카오페이 결제를 연동하면 수천만 명의 카카오 사용자가 간편하게 결제할 수 있는 환경을 만들 수 있습니다. 카카오페이는 국내 최대 규모의 간편결제 서비스 중 하나로, 온라인 결제 API를 제공하여 다양한 서비스에 통합할 수 있어요.
이 글에서는 카카오페이 온라인 결제 API의 개요, 연동 방법, 개발 절차, 그리고 주의사항까지 개발자와 사업자 모두가 이해할 수 있도록 상세히 안내해 드리겠습니다.
카카오페이 결제 API 개요
카카오페이 결제 API란?
카카오페이 결제 API는 온라인 사업자가 자신의 웹사이트나 앱에 카카오페이 결제 기능을 통합할 수 있도록 카카오에서 제공하는 프로그래밍 인터페이스입니다. API 연동을 통해 사용자는 별도의 회원가입이나 카드 정보 입력 없이 카카오 계정과 연결된 카카오페이로 간편하게 결제할 수 있어요. 사업자 입장에서는 높은 결제 편의성으로 전환율을 높이고, 이탈률을 낮추는 효과를 기대할 수 있습니다.
결제 방식의 종류
카카오페이 결제 API는 여러 결제 방식을 지원합니다. 일반 결제(단건 결제)는 고객이 물건을 구매할 때마다 결제 과정을 거치는 방식이에요. 정기 결제(자동결제)는 구독 서비스나 정기 배송 서비스에서 매월 또는 주기적으로 자동으로 결제되는 방식입니다. 또한 결제 준비, 결제 승인, 결제 취소, 환불, 결제 조회 등 결제 라이프사이클 전반을 API로 처리할 수 있어요.
카카오페이 개발자 센터
카카오페이 결제 API 연동을 위한 모든 개발 문서는 카카오페이 개발자 센터(developers.kakaopay.com)에서 확인할 수 있습니다. API 명세, 샘플 코드, 테스트 환경 설정 방법 등이 상세히 안내되어 있어요. 개발자 계정 등록 후 테스트 환경(sandbox)을 이용하면 실제 결제 없이 연동 테스트를 진행할 수 있습니다.
카카오페이 결제 API 연동 절차
1단계: 카카오페이 사업자 등록
카카오페이 결제 API를 사용하려면 먼저 카카오페이 비즈니스 파트너로 등록해야 합니다. 카카오페이 파트너 신청 페이지(partner.kakaopay.com)에서 사업자등록번호, 업종, 서비스 정보 등을 입력하여 신청할 수 있어요. 개인 사업자와 법인 사업자 모두 신청 가능하며, 심사 후 승인이 이루어집니다. 심사 기간은 통상 3~7 영업일 정도 소요될 수 있어요.
2단계: API 키 발급
파트너 승인 후 카카오페이 개발자 콘솔에서 결제 API 키를 발급받습니다. API 키는 Admin Key(서버 간 통신에 사용), Client Key(클라이언트에서 사용) 두 가지로 구분돼요. Admin Key는 절대 외부에 노출해서는 안 되며, 서버 측 코드에서만 사용해야 합니다. 테스트 환경(sandbox)용 키와 실서비스(production)용 키가 별도로 존재해요.
3단계: 개발 환경 설정
카카오페이 결제 API는 REST API 방식으로 제공됩니다. HTTP POST 방식으로 요청을 보내고, JSON 형태의 응답을 받는 구조예요. 개발 언어(Java, Python, Node.js, PHP 등)에 관계없이 HTTP 요청을 보낼 수 있는 환경이면 연동 가능합니다. 카카오페이에서 공식 SDK를 별도로 제공하는 경우도 있으니 개발자 센터를 확인하세요.
카카오페이 일반 결제 API 연동 방법
결제 준비(ready) API 호출
결제 과정의 첫 번째 단계는 결제 준비 API를 호출하는 것입니다. 서버에서 카카오페이 서버로 결제 준비 요청을 보내면, 카카오페이 서버에서 결제 고유 번호(tid)와 결제 페이지 URL(next_redirect_pc_url, next_redirect_mobile_url)을 반환해요. 이 URL로 사용자를 리다이렉트하면 카카오페이 결제 화면이 표시됩니다. 준비 요청 시 주문번호, 상품명, 결제 금액, 성공/실패/취소 URL 등을 파라미터로 전달해야 해요.
결제 승인(approve) API 호출
사용자가 카카오페이 결제 화면에서 결제를 완료하면, 사전에 등록한 success_url로 pg_token이 전달됩니다. 이 pg_token과 결제 준비 시 받은 tid를 사용하여 서버에서 결제 승인 API를 호출해요. 승인 API 호출 결과로 결제 완료 정보(결제 방법, 금액, 시각 등)를 받을 수 있습니다. 승인 완료 후 주문 처리와 영수증 발행 등 이후 로직을 처리하면 돼요.
결제 취소 및 환불 API
고객이 환불을 요청하거나 주문이 취소되면 결제 취소 API를 호출합니다. 전액 취소와 부분 취소 모두 지원하며, 부분 취소의 경우 취소 금액을 지정하여 호출해요. 취소 API 호출 시 원래 결제의 tid, 취소 금액, 취소 가용 금액 등을 파라미터로 전달해야 합니다. 취소 결과는 API 응답으로 즉시 확인할 수 있어요.
정기 결제(자동결제) API 연동
정기 결제의 개요
정기 결제는 구독 서비스, 정기 배송, 보험료 자동납부 등에 활용됩니다. 사용자가 최초 1회 결제를 진행하면 카카오페이에서 SID(결제 수단 고유 번호)를 발급해줘요. 이후 이 SID를 사용하여 서버에서 자동으로 결제를 실행할 수 있습니다. 사용자의 추가 인증 없이 주기적으로 결제가 이루어지므로, 구독 서비스 운영에 매우 편리해요.
정기 결제 연동 단계
정기 결제는 일반 결제와 다른 API 엔드포인트를 사용합니다. 최초 결제 시 정기 결제 준비 API로 요청하고, 사용자 승인 후 SID를 발급받아요. 이후 결제 주기(매월, 매주 등)에 맞춰 서버에서 정기 결제 실행 API를 호출하면 자동으로 결제가 이루어집니다. 정기 결제는 사용자가 언제든지 해지할 수 있도록 해지 기능도 함께 구현해야 해요.
정기 결제 실패 처리
정기 결제 실행 시 결제 수단 만료, 잔액 부족 등의 이유로 결제가 실패할 수 있습니다. 실패 시 사용자에게 알림을 보내고, 재결제 또는 결제 수단 업데이트를 유도하는 로직을 구현해야 해요. 연속으로 여러 번 실패하면 서비스 이용을 자동으로 중단하는 처리도 필요합니다.
보안과 주의사항
Admin Key 보안 관리
Admin Key는 절대로 클라이언트 코드(JavaScript, 앱 소스)에 포함시켜서는 안 됩니다. Admin Key가 외부에 노출되면 무단 결제 취소, 환불, API 악용 등의 심각한 보안 사고가 발생할 수 있어요. Admin Key는 서버 환경 변수나 보안 설정 파일에 저장하고, 반드시 서버 측 코드에서만 사용해야 합니다.
결제 금액 검증
결제 승인 완료 후 반드시 실제 결제 금액이 주문 금액과 일치하는지 서버에서 검증해야 합니다. 클라이언트 측에서 금액을 변조하여 더 적은 금액으로 결제하는 시도를 방지하기 위해서예요. 결제 완료 정보를 카카오페이 서버에서 재조회하여 금액 일치 여부를 확인하는 로직이 필수입니다.
결제 중복 처리 방지
네트워크 오류나 사용자 행동에 의해 결제 승인 API가 중복으로 호출될 수 있습니다. 서버에서 멱등성 처리(이미 처리된 주문번호는 재처리하지 않는 로직)를 구현하여 중복 결제가 발생하지 않도록 해야 해요. 주문번호를 고유하게 관리하고, 이미 처리된 주문은 완료 처리를 반환하는 방식이 일반적입니다.
테스트와 실서비스 전환
테스트 환경(샌드박스) 활용
카카오페이는 테스트 환경을 제공하여 실제 결제 없이 API 연동을 테스트할 수 있도록 합니다. 테스트 환경에서는 가상의 결제 프로세스를 실행하여 연동 로직이 올바르게 작동하는지 확인할 수 있어요. 결제 성공, 실패, 취소 등 다양한 시나리오를 테스트하고 충분히 검증한 후 실서비스로 전환하세요.
실서비스 전환 전 체크리스트
- 결제 준비, 승인, 취소, 조회 API 모두 정상 동작 확인
- 결제 금액 검증 로직 구현 여부
- Admin Key 보안 관리 여부 (서버 측에서만 사용)
- 결제 실패 및 오류 처리 로직 구현
- 환불 처리 로직 구현
- 결제 로그 기록 및 모니터링 설정
- PG사 및 카카오페이 약관 준수 여부
결제 오류 모니터링
실서비스 운영 중에는 결제 오류와 실패 건을 모니터링하는 시스템을 갖추는 것이 중요합니다. 결제 실패율이 높아지거나 특정 오류가 반복되면 빠르게 원인을 파악하고 대응해야 해요. 카카오페이 파트너 콘솔에서도 결제 현황 및 오류 로그를 확인할 수 있습니다.
결론: 철저한 테스트 후 안전하게 연동하세요
카카오페이 온라인 결제 API는 방대한 사용자 기반과 높은 편의성으로 온라인 서비스의 결제 전환율을 높이는 데 효과적입니다. API 문서를 꼼꼼히 읽고 테스트 환경에서 충분히 검증한 후 실서비스에 적용하는 것이 중요해요.
보안 관리와 결제 금액 검증, 중복 처리 방지 등 기술적 주의사항을 철저히 준수하면 안전하고 안정적인 결제 환경을 만들 수 있습니다. 개발 중 막히는 부분이 있으면 카카오페이 개발자 센터의 문서와 개발자 포럼을 적극 활용하세요.