내가 만든 앱에서 카카오페이를 쓸 수 있다?! (부제 : 천사같은 오픈 API) | 코드스테이츠 PMB 14기

예전에 문득 날씨 관련 앱이 이렇게 많은 데 어떻게 기상청 데이터를 사용하는 것인지 궁금했던 적이 있다. 혹시 해킹...?🫢 하지만 이러한 의문은 한 학생이 만든 코로나 맵을 알게 되면서 해결되었다. 코로나 맵에 사용된 지도는 네이버 지도였는데, 학생이 네이버에서 제공하는 지도를 통해 새로운 프로덕트를 만드는 것이 가능하다는 것을 알게 됐다. 그땐 몰랐는데 이것을 오픈 API라고 부른다고 한다. 오픈 API는 실제로 개발자들의 토이 프로젝트에 많이 사용되고 있다.

도대체 오픈 API가 뭔데?

위에서 언급한 OPEN API를 설명하기 앞서 API가 뭔지 이해할 필요가 있다.

• API (Application Programming Interface)
  API는 직역하자면 애플리케이션을 프로그래밍하는데 필요한 인터페이스다.
  쉽게 말하자면 두개의 시스템이 서로 데이터를 주고받으며 상호작용하기 위한 인터페이스를 의미한다.
  
  
• 오픈 API
  하나의 웹 사이트에서 자신이 가진 기능을 이용할 수 있도록 공개한 API다.
  위에서 말한 지도 기능 외 요즘 수많은 프로덕트에서 로그인 시 많이 이용하는 소셜 로그인도 각 서비스에서 제공하여 무료로 사용할 수 있는 오픈 API다.

 

네이버와 카카오에서 제공하는 OPEN API

 오픈 API로 제공되는 데이터의 종류는 꽤 다양하며, 그 수도 생각보다 많다. 찾아보면서 이런 것도 활용할 수 있도록 해줬단 말이야?라는 생각이 들었다. 오늘은 그중 카카오페이 오픈 API에 대해 알아보려 한다.

---

 

카카오페이 OPEN API

카카오페이는 카카오 그룹 계열사 중 하나로, 송금이나 결제를 할 수 있는 핀테크 서비스이다. 카카오페이를 통해 우리는 온라인에서 간편하게 결제를 할 수 있게 되었다. 이용자의 계좌 또는 카드를 연결하기만 하면 송금, 더치페이, 결제 등 다양한 금융 기능을 이용할 수 있는 편리한 서비스다.
* 카카오페이 오픈 API에 대한 내용은 https://developers.kakao.com/product/kakaoPay 를 참고하여 정리하였다.


 카카오페이 API는 실물 카드나 현금 없이도 PC와 모바일 웹, 모바일 앱에서 손쉽게 결제하는 기능을 제공한다. 단 해당 API를 실제 서비스에서 이용하려면 제휴를 맺어야 하며, 무료 이용시 결제 프로세스만 체험 가능하다. 카카오페이 API는 SDK는 지원하지 않기 때문에 REST API 방식으로만 이용 가능하다. 카카오페이 API를 사용하기 위해서는 Kakao Developers에 들어가서 [내 애플리케이션]에 적용한 서비스의 웹 사이트 도메인을 등록해야 한다. (검수 시간이 소요되므로 고려해서 개발 일정을 잡아야 할 것이다!)

 

• SDK (Software Development Kit)란?
  어떤 소프트웨어를 만들기 위한 도구 모음을 SDK라고 한다. SDK엔 API도 포함되어 있다.
• REST API
  API를 구성할 때 CRUD를 염두하곤 한다. Create-등록, Read-읽기, Update-수정, Delete-삭제를 의미하는 데 일반적으로 우리가 블로그를 작성할때를 생각해보자! 작성만 할 수 있고, 작성된 글의 목록을 볼 수 없거나, 한번 등록시 수정이나 삭제가 불가능하다면? 얼마나 불편할지 상상만해도 끔찍하다.
  CRUD 방식으로 데이터를 요청할 때 각각의 주소를 가지게 되는데, 주소가 셀 수 없이 많아지면 관리하기 힘들어진다는 문제가 발생한다. 이를 해결하기 위해 주소의 갯수를 간소화하는 방안이 REST API이다.

 

 

💡 카카오페이 API 기능 목록

• 단건 결제 : 일회성 결제 진행
• 정기 결제 : 1회 등록 후 주기적으로 결제 가능
• 정기 결제 비활성화 : 등록된 정기결제 키(SID)를 비활성화하는 기능
• 정기 결제 상태 조회 : 정기결제 키(SID)의 상태 조회 기능
• 주문 조회 : 결제 요청한 주문 건 조회
• 결제 취소 : 완료된 결제를 부분 또는 전체 취소하는 기능

 카카오페이 API 기능을 보면 왜 REST API 방식으로 이용 가능하다는 것인지 알 수 있다. 여기서 CRUD는 Create-결제(단건/정기), Read-주문 조회, Update-정기 결제 비활성화, Delete-결제 취소로 연결될 것이다. 사실 Update는 없다고 해도 무방한데, 오프라인에서도 결제 시 문제가 발생하면 주문을 취소하고 다시 결제를 하기 때문이다. (아마도 금전적인 부분이기 때문에 수정을 애초에 막아둔 것이 우리의 일상 속 결제 방식이 된 것이 아닐까?)

 

 

 

⏰ 결제 프로세스

 카카오페이를 통한 결제는 크게 네 단계로 나뉜다. PC의 경우 '사용자 정보 입력' 단계가 추가되어있을 뿐 전체적인 프로세스는 PC와 모바일이 동일하게 작동한다.

1. 결제 준비
   가맹점 코드(CID), 가맹점이 부여한 주문번호(partner_order_id), 상품 총액(total_amount) 등 상세 정보를 카카오페이 서버에 전달하고 결제 과정을 시작하는 단계
2. 정보 확인 및 사용자인증
   사용자 정보 입력 및 카카오페이 결제 수단 선택과 인증이 이뤄지는 단계
3. 인증 완료
   사용자의 인증이 완료되고, 승인에 필요한 인증 값을 응답주는 단계
4. 결제 승인
   결제 필수 값으로 카카오페이 서버에 승인요청하여 최종적인 결제완료 처리를 하는 단계
   
   • 결제 승인 직전에 요청 결과별 리다이렉트 URL이 달라진다.
     1) 요청 성공 : approval_url로 리다이렉트
     2) 요청 취소 : cancel_url로 리다이렉트
     3) 요청 유효 시간(15분) 경과 : fail_url로 리다이렉트

---

카카오 페이 결제 방식이 단건과 정기 결제로 나뉘기 때문에 나는 이번에 단건 결제에 집중하여 살펴보고자 한다.

 

결제 준비 : POST

POST /v1/payment/ready HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8

 위의 내용은 우리가 카카오페이 API를 사용할 경우, 사용자가 결제에 필요한 상세 정보(parameter)를 가지고 결제 고유번호를 생성(Post) 해달라는 요청을 보내면 서버에서 요청에 해당하는 데이터를 제공(Request)한다는 내용이다.

 

 

요청 사항 : Request

 아래 표는 카카오페이 API 페이지에서 제공하는 Parameter 값이다. 각 parameter 값에 따른 이름, 데이터 타입, 세부 설명을 기술하고 있다. Required의 경우 'O'로 표기 된 것은 필수인 것으로 보인다.

Name	Type	Description	Required
cid	String	가맹점 코드, 10자	O
cid_secret	String	가맹점 코드 인증키, 24자, 숫자와 영문 소문자 조합	X
partner_order_id	String	가맹점 주문번호, 최대 100자	O
partner_user_id	String	가맹점 회원 id, 최대 100자	O
item_name	String	상품명, 최대 100자	O
item_code	String	상품코드, 최대 100자	X
quantity	Integer	상품 수량	O
total_amount	Integer	상품 총액	O
tax_free_amount	Integer	상품 비과세 금액	O
vat_amount	Integer	상품 부가세 금액 값을 보내지 않을 경우 다음과 같이 VAT 자동 계산 (상품총액 - 상품 비과세 금액)/11 : 소숫점 이하 반올림	X
green_deposit	Integer	컵 보증금	X
approval_url	String	결제 성공 시 redirect url, 최대 255자	O
cancel_url	String	결제 취소 시 redirect url, 최대 255자	O
fail_url	String	결제 실패 시 redirect url, 최대 255자	O
available_cards	JSON Array	결제 수단으로써 사용 허가할 카드사를 지정해야 하는 경우 사용, 카카오페이와 사전 협의 필요 사용 허가할 카드사 코드*의 배열 ex) ["HANA", "BC"] (기본값: 모든 카드사 허용)	X
payment_method_type	String	사용 허가할 결제 수단, 지정하지 않으면 모든 결제 수단 허용 CARD 또는 MONEY 중 하나	X
install_month	Integer	카드 할부개월, 0~12	X
custom_json	JSON Map {String:String}	결제 화면에 보여줄 사용자 정의 문구, 카카오페이와 사전 협의 필요 ex) iOS에서 사용자 인증 완료 후 가맹점 앱으로 자동 전환하는 방법(iOS만 예외 처리, 안드로이드 동작 안 함) - 다음과 같이 return_custom_url key 정보에 앱스킴을 넣어서 전송 return_custom_url":"kakaotalk://

 

데이터 반환 : Response

Name	Type	Description
tid	String	결제 고유 번호, 20자
next_redirect_app_url	String	요청한 클라이언트(Client)가 모바일 앱일 경우 카카오톡 결제 페이지 Redirect URL
next_redirect_mobile_url	String	요청한 클라이언트가 모바일 웹일 경우 카카오톡 결제 페이지 Redirect URL
next_redirect_pc_url	String	요청한 클라이언트가 PC 웹일 경우 카카오톡으로 결제 요청 메시지(TMS)를 보내기 위한 사용자 정보 입력 화면 Redirect URL
android_app_scheme	String	카카오페이 결제 화면으로 이동하는 Android 앱 스킴(Scheme)
ios_app_scheme	String	카카오페이 결제 화면으로 이동하는 iOS 앱 스킴
created_at	Datetime	결제 준비 요청 시간

 

 각 표에 뭔가 잔뜩 적혀있는 데 개발자가 아닌 PM 입장에서 저 많은 것을 다 정확하게 이해하기 보단 어떤 기능을 하는 지를 이해하는 것이 중요하다. 샘플 Response 코드를 보자!

 

1. 현금 결제 건에 대한 Response

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
    "aid": "A5678901234567890123",
    "tid": "T1234567890123456789",
    "cid": "TC0ONETIME",
    "partner_order_id": "partner_order_id",
    "partner_user_id": "partner_user_id",
    "payment_method_type": "MONEY",
    "item_name": "초코파이",
    "quantity": 1,
    "amount": {
        "total": 2200,
        "tax_free": 0,
        "vat": 200,
        "point": 0,
        "discount": 0,
        "green_deposit": 0
    },
    "created_at": "2016-11-15T21:18:22",
    "approved_at": "2016-11-15T21:20:47"
}

• "payment_method_type" : "MONEY"
  👉 현금으로 결제함
• "item_name" : "초코파이", "quantity" : 1 
   👉 초코파이 1개를 구매함
• "amount" : {"total" : 2200, "vat" : 200}
   👉 초코파이 1개는 2200원이고, 그 중 200원은 부가세이다
  
• "created_at" : "2016-11-15T21:18:22", "approved_at" : "2016-11-15T21:20:47"
   👉 2016년 11월 15일 9시 18분에 결제 요청, 9시 20분에 결제 완료됨
  

2. 카드 결제 실패 건에 대한 Response

 카드 결제의 경우 성공했다면 위의 코드와 유사할 것이다. 그렇다면 결제 오류로 실패했다면 어떻게 나타날까?

HTTP/1.1 400 Bad Request
Content-type: application/json;charset=UTF-8
{
    "code": -780,
    "msg": "approval failure!",
    "extras": {
        "method_result_code": "USER_LOCKED",
        "method_result_message": "진행중인 거래가 있습니다. 잠시 후 다시 시도해 주세요."
    }
}

• 400 Bad Request
  👉 클라이언트 오류 감지 (개발 세계에서 오류는 숫자로 표현한다. 궁금하다면 여기를 참고해보자!)
• "method_result_code" : "USER_LOCKED", "method_result_message" : "진행중인 거래가 있습니다. 잠시 후 다시 시도해 주세요."
  👉 오류 코드와 그에 따라 사용자가 확인하게 되는 오류 메세지

 

---

💡 카카오페이 API, 어떤 식으로 활용할 수 있을까?

 카카오페이는 사용자들이 간편하고 빠르게 결제를 할 수 있다는 장점이 있는 만큼 프로덕트 내 충전 기능에 활용할 수 있을 것 같다. 충전식 결제 방식을 제공하는 서비스는 뭐가 있을까? 가장 먼저 생각난 것이 웹툰, 음악 스트리밍 서비스다. 레진 코믹스와 멜론에서 확인해보니 결제 수단에 카카오페이가 있음을 알 수 있다.

 

---

과제를 마치며.

API는 정말 어렵다. 백엔드 개발자 분들 리스펙..^^

오픈 API에 대해서 보다 더 자세하게 알고 싶다면 아래 영상이 도움이 될 것이다 :)