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