- 문서>
- 카카오페이>
- 이해하기
카카오페이
이해하기
이 문서는 카카오페이 API를 소개합니다.
기능 소개
카카오페이 API는 PC웹, 모바일 웹, 모바일 앱 등 다양한 환경에서 카카오페이로 결제하는 기능을 제공합니다. 데모 페이지에서 카카오페이를 통한 결제 프로세스를 체험해볼 수 있으며, [도구] 메뉴에서 카카오페이 결제 버튼 리소스 다운로드가 가능합니다.
카카오페이 API 제공 기능 목록
| Name | Description |
|---|---|
| 단건 결제 | 일회성 결제를 진행할 수 있습니다. |
| 정기 결제 | 1회 등록 후 주기적으로 결제를 진행할 수 있습니다. |
| 정기 결제 비활성화 | 등록된 정기 결제 키 (SID)를 비활성화 할 수 있습니다. |
| 정기 결제 상태 조회 | 정기 결제 키 (SID)의 상태를 조회할 수 있습니다. |
| 주문 조회 | 결제 요청한 주문을 조회할 수 있습니다. |
| 결제 취소 | 완료된 결제를 부분 또는 전체 취소할 수 있습니다. |
도메인 등록
카카오페이 API를 사용하려면 [내 애플리케이션] > [플랫폼] > [Web]에 서비스 웹 사이트 도메인을 등록해야 합니다. 도메인은 최대 10개까지 등록할 수 있습니다.
카카오페이 API는 애플리케이션(이하 앱) 어드민 키(Admin Key)로 호출합니다. 어드민 키 사용 시, 반드시 서버에서 카카오페이 API를 호출해 어드민 키 탈취 등의 사고를 예방해야 합니다.
제휴 안내
카카오페이 API를 실제 서비스에서 이용하려면 제휴를 맺어야 합니다. 카카오페이 제휴 신청 페이지에서 제휴 제안할 수 있습니다.
제휴를 맺기 전에도 카카오페이 API 테스트가 가능합니다. 카카오디벨로퍼스에서 제공하는 카카오페이 API는 모의(Mockup) 용도의 API로 각 환경에 맞게 카카오페이API를 테스트해볼 수 있습니다.
용어 설명
ID
| Name | Description |
|---|---|
| CID | 가맹점 코드, 제휴를 통해 발급, 결제 유형과 단위 정의, 10자리 |
| TID | 결제 한 건에 대한 고유번호, 결제 준비 API가 성공적으로 호출되면 발급, 20자리 |
| SID | 정기 결제에 사용되는 고유번호, 정기 결제 1회차 프로세스가 완료되면 발급, 20자리 2회차 정기 결제부터는 SID를 이용해 결제 요청 |
| AID | 결제, 취소, 정기 결제 API 호출에 대한 고유번호, 각 API 호출 성공 시 발급, 20자리 |
결제 필수 값
| Name | Description |
|---|---|
| partner_order_id | 결제건에 대한 가맹점의 주문번호 TID와 연결시켜두고 대사작업을 할 때 사용 MAX 100자로 hash 값 사용 가능 |
| partner_user_id | 가맹점에서 사용자를 구분할 수 있는 id MAX 100자로 hash값 사용 가능 |
| pg_token | 결제 승인 요청을 인증하는 토큰 |
결제 프로세스
카카오페이를 통한 결제는 크게 네 단계로 나뉩니다.
- 결제 준비: 가맹점 코드(CID), 가맹점이 부여한 주문번호(
partner_order_id), 상품 총액(total_amount) 등 상세 정보를 카카오페이 서버에 전달하고 결제 과정을 시작하는 단계 - 정보 확인 및 사용자인증: 사용자 정보 입력 및 카카오페이 결제 수단 선택과 인증이 이뤄지는 단계
- 인증 완료: 사용자의 인증이 완료되고, 승인에 필요한 인증 값을 응답주는 단계
- 결제 승인: 결제 필수 값으로 카카오페이 서버에 승인요청하여 최종적인 결제완료 처리를 하는 단계
사용자 환경에 따른 카카오페이 결제 진행 과정을 정리하면 다음과 같습니다.
PC 환경
Step 1. 결제 준비
서버에서 결제 준비 API를 호출합니다. 응답이 오면 요청한 결제와 TID를 매핑(Mapping)하여 저장하고, 추후 결제 승인 API 호출 및 대사 작업에 사용합니다. 보안을 위해 TID가 사용자에게 노출되지 않도록 주의합니다. 응답 바디로 받은 next_redirect_pc_url 값으로 결제 대기 화면을 팝업(Popup) 혹은 레이어(Layer) 방식으로 띄웁니다.
사용자는 전화번호 및 생년월일을 입력합니다. 올바른 정보가 입력되면 카카오톡으로 결제 요청 메시지가 전송되고, 사용자 정보 입력 화면은 결제 대기 화면으로 변경됩니다. 사용자는 결제 요청 메시지를 통해 결제 화면으로 이동해 결제 수단을 선택합니다.
결제 대기 화면은 결제 요청 결과에 따라 각각 다른 URL로 리다이렉트(redirect)됩니다. 사용자가 결제를 취소한 경우, 보안을 위해 주문 상세 조회 API를 호출하고 결제 과정을 중단해야 합니다. 조회 시 상태 값이 사용자가 결제를 중단한 상태임을 나타내는 QUIT_PAYMENT인 것을 확인하고 결제 중단 처리를 해야 합니다.
- 요청 결과별 리다이렉트 URL
- 요청 성공:
approval_url로 리다이렉트 - 요청 취소:
cancel_url로 리다이렉트 - 요청 유효 시간(15분) 경과:
fail_url로 리다이렉트
- 요청 성공:
approval_url, cancel_url, fail_url은 카카오페이 API 요청 응답을 받아 처리할 주소입니다. 이 값들의 도메인(Domain)은 앱 정보에 등록된 웹 플랫폼 도메인과 일치해야 합니다.
결제 대기 단계에서 결제 요청에 성공했다면 결제 승인 API를 호출합니다. 이때 결제 승인 요청을 인증하는 pg_token을 전달해야 합니다. pg_token은 사용자가 결제 수단을 선택하고 결제 버튼을 눌러 approval_url로 리다이렉트될 때, 리다이렉트 요청의 approval_url에 포함된 query string으로 전달 받습니다.
응답을 받으면 결제 결과를 저장하고 사용자에게 결제 완료 화면을 보여줍니다. 결제 승인 API의 동작에 따라 사용자도 결제 완료 메시지를 받습니다.
모바일 환경
Step 1. 결제 준비
서버에서 결제 준비 API를 호출합니다. 응답이 오면 요청한 결제와 TID를 매핑(Mapping)하여 저장하고, 추후 결제 승인 API 호출 및 대사 작업에 사용합니다. 보안을 위해 TID가 사용자에게 노출되지 않도록 주의합니다.
- 웹 브라우저(Web browser) : 응답 바디로 받은 결제 대기 화면 주소인
next_redirect_web_url로 리다이렉트합니다. - 네이티브 앱: 응답 바디로 받은
next_redirect_app_url값으로 결제 대기 화면 웹뷰를 띄웁니다.
사용자는 결제 준비 화면에서 결제 수단 선택 화면으로 이동하고, 결제 수단을 선택한 뒤 결제하기 버튼을 누릅니다.
사용자는 결제 대기 화면으로 이동하고, 화면은 결제 요청 결과에 따라 다른 URL로 리다이렉트됩니다. 사용자가 결제를 취소한 경우, 보안을 위해 주문 상세 조회 API를 호출하고 결제 과정을 중단해야 합니다. 조회 시 상태 값이 사용자가 결제를 중단한 상태임을 나타내는 QUIT_PAYMENT인 것을 확인하고 결제 중단 처리를 해야 합니다.
- 요청 결과별 리다이렉트 URL
- 요청 성공:
approval_url로 리다이렉트 - 요청 취소:
cancel_url로 리다이렉트 - 요청 유효 시간(15분) 경과:
fail_url로 리다이렉트
- 요청 성공:
approval_url, cancel_url, fail_url은 카카오페이 API 요청 응답을 받아 처리할 주소입니다. 이 값들의 도메인(Domain)은 앱 정보에 등록된 웹 플랫폼 도메인과 일치해야 합니다.
결제 대기 단계에서 결제 요청에 성공했다면 결제 승인 API를 호출합니다. 이때 결제 승인 요청을 인증하는 pg_token을 전달해야 합니다. pg_token은 사용자가 결제 수단을 선택하고 결제 버튼을 눌러 approval_url로 리다이렉트될 때, 리다이렉트 요청의 approval_url에 포함된 쿼리스트링(Query string)으로 전달 받습니다.
응답을 받으면 결제 결과를 저장하고 사용자에게 결제 완료 화면을 보여줍니다. 결제 승인 API의 동작에 따라 사용자도 결제 완료 메시지를 받습니다.
현금영수증 발행 관련 안내
현금영수증은 기본적으로 카카오페이에서 발행합니다. 가맹점 또는 제휴사에서 자체적으로 현금영수증을 발행하려면 카카오페이와 협의 후 진행할 수 있습니다. 카카오페이가 발행하는 현금영수증에는 포인트, 할인금액, 일회용컵보증금에 대해 자동계산되어 발행되나, 자체적으로 발행하는 경우 다음 사항을 참고합니다.
- 일회용컵 보증금 금액(
green_deposit) 필드가 추가됩니다. (적용일: 2022. 7. 7) - 포인트, 할인금액, 일회용컵 보증금 금액은 현금영수증 미발행 대상으로, 현금영수증 자체 발행 시에는 전체 결제 금액에서 할인된 금액과 포인트 금액을 제한 나머지 금액으로 현금영수증을 발행하여야 합니다.
(현금영수증 발행 대상 금액 =total–discount–point-green_deposit)
카카오페이 API는 REST API 방식으로만 이용할 수 있습니다.