카카오페이

카카오 플랫폼 서비스를 통해 카카오페이로 결제하기 위한 REST API에 대해 설명합니다. 결제 REST API를 통해서 PC웹, 모바일 웹, 모바일 앱 등 다양한 환경에서 카카오페이로 결제할 수 있습니다.

카카오페이 API를 사용하기 전에 알아둬야 할 내용을 설명합니다.

  • 시작하기전에
    카카오페이 API를 연동하기 전에 먼저 알아둬야 하는 내용에 대해 설명합니다.
  • 결제 프로세스
    카카오페이 API를 연동 프로세스에 대해 설명합니다.

현재 제공되는 결제 API는 다음과 같습니다.

카카오페이 API를 사용할 때 필요한 버튼은 여기를 참조하세요.
카카오페이 데모를 바로 확인해 보세요! 데모 보러가기

시작하기 전에

웹사이트 도메인 등록하기

REST API를 사용하기 위해 웹사이트 도메인을 등록해야 합니다.
웹사이트 도메인은 앱의 설정페이지에서 설정 > 일반 > 플랫폼 > 웹 > 사이트 도메인 에서 설정 할 수 있습니다. 최대 10개까지 가능합니다.

카카오페이와 제휴하기

개발자사이트에서 제공하는 카카오페이API는 Mockup용 API로 각 환경에 맞게 카카오페이API를 붙여서 테스트해볼 수 있습니다.
실 서비스에서 카카오페이API를 사용하기 위해선 별도의 제휴가 필요합니다. 카카오페이 파트너 어드민 로 접속하여 안내에 따라 제휴프로세스를 진행할 수 있습니다.

용어설명

사용되는 ID

이름 설명
GID 가맹점 그룹 코드. 하위에 CID들이 있음. 10자리
CID 가맹점 코드. 결제 단위를 정의. 10자리
TID 결제 한 건에 대한 고유번호. 20자리
SID 정기결제에 사용되는 고유번호. 20자리
AID 결제, 취소, 정기결제 API 호출에 대한 고유번호. 20자리

결제에 필요한 필수 값

이름 설명
partner_order_id 결제건에 대한 가맹점의 주문번호. TID와 연결시켜두고 대사작업을 할 때 사용.
MAX 100자로 hash값 사용 가능
partner_user_id 가맹점에서 사용자를 구분할 수 있는 id. MAX 100자로 hash값 사용 가능
pg_token 사용자의 결제수단 선택 완료 후 결제 대기화면에서 approval_url로 redirect할 때 request param으로 붙여서 전달해줌

결제프로세스

PC 웹, 카카오톡이 설치되어 있지 않은 모바일 환경에서의 웹 또는 앱

pay_process

  • 서버에서 결제준비 API를 호출합니다.
    • 응답이 오면 요청한 결제와 TID를 매핑하여 저장하고 추후 결제승인 API 및 대사작업을 할 때 사용합니다.
    • TID는 보안을 위하여 사용자에게 노출되어선 안됩니다.
    • 응답 바디로 받은 next_redirect_pc_url(결제대기 화면)을 Popup 혹은 Layer 방식으로 직접 띄워줍니다.
  • 사용자정보 입력 화면에서 사용자는 전화번호와 생년월일을 입력합니다.
    • 카카오톡으로 결제요청 메시지가 전송되고 사용자정보 입력 화면은 결제대기 화면으로 변경됩니다.
    • 결제요청 메시지에서 결제창으로 이동하여 결제수단을 선택합니다.
  • 결제대기 화면은 approval_url로 redirect됩니다.
    • 사용자가 결제를 취소하는 경우, cancel_url로 redirect됩니다.
    • cancel_url에서는 보안을 위해 결제상태조회 API를 호출하여 상태값이 QUIT_PAYMENT(사용자가 결제를 중단한 상태)인 것을 확인하고 결제 중단 처리를 해야 합니다.
    • 결제 유효시간이 지난 경우, fail_url로 redirect됩니다.
  • 결제승인 API를 호출합니다.
    • 응답을 받아 결제 결과를 저장하고 사용자에게 결제완료 화면을 보여줍니다.
    • 사용자에게 결제완료 메시지가 발송됩니다.
모바일 환경에서의 웹 또는 앱

pay_process_mobile

  • 서버에서 결제준비 API를 호출합니다.
    • 응답이 오면 요청한 결제와 TID를 매핑하여 저장하고 추후 결제승인 API 및 대사작업을 할 때 사용합니다.
    • TID는 보안을 위하여 사용자에게 노출되어선 안됩니다.
    • WEB 에서 연동 : 응답 바디로 받은 next_redirect_web_url(결제대기 화면)으로 redirect합니다.
    • APP 에서 연동 : 응답 바디로 받은 next_redirect_app_url(결제대기 화면)을 웹뷰로 띄웁니다.
  • 결제대기 화면에서 결제창으로 이동하여 결제수단을 선택합니다.
  • 사용자가 결제대기 화면으로 돌아오면 approval_url로 redirect됩니다.
    • 사용자가 결제를 취소하는 경우, cancel_url로 redirect됩니다.
    • cancel_url에서는 보안을 위해 결제상태조회 API를 호출하여 상태값이 QUIT_PAYMENT(사용자가 결제를 중단한 상태)인 것을 확인하고 결제 중단 처리를 해야 합니다.
    • 결제 유효시간이 지난 경우, fail_url로 redirect됩니다.
  • 결제승인 API를 호출합니다.
    • 응답을 받아 결제 결과를 저장하고 사용자에게 결제완료 화면을 보여줍니다.
    • 사용자에게 결제완료 메시지가 발송됩니다.

단건결제 프로세스

단건결제용으로 발급받은 CID를 사용해 결제준비 API를 호출해 진행합니다.

테스트결제를 위해서는 "TC0ONETIME" 이라는 TEST CID값을 사용할 수 있습니다.
실결제를 위해서는 카카오페이와 제휴 후 단건결제용 CID를 발급받아야 합니다.

결제준비

사용자에게 결제를 요청하기 위해 호출합니다.

카카오페이 API는 사용자의 AccessToken 뿐만 아니라, 어드민 키(Admin Key)로도 요청 가능합니다. 어드민 키를 사용할 때에는 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 가맹점 서버에서 API를 호출하시기 바랍니다.

[Request]

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

어드민키/사용자토큰을 헤더에 담아 아래 파라미터의 값들과 함께 POST로 요청합니다.

approval_url, cancel_url, fail_url의 도메인은 앱에 등록된 웹사이트 도메인과 일치해야 합니다.

설명 필수 타입
cid 가맹점 코드. 10자. O String
partner_order_id 가맹점 주문번호. 최대 100자 O String
partner_user_id 가맹점 회원 id. 최대 100자 O String
item_name 상품명. 최대 100자 O String
item_code 상품코드. 최대 100자 X String
quantity 상품 수량 O Integer
total_amount 상품 총액 O Integer
tax_free_amount 상품 비과세 금액 O Integer
vat_amount 상품 부가세 금액(안보낼 경우 (상품총액 - 상품 비과세 금액)/11 : 소숫점이하 반올림) X Integer
approval_url 결제 성공시 redirect url. 최대 255자 O String
cancel_url 결제 취소시 redirect url. 최대 255자 O String
fail_url 결제 실패시 redirect url. 최대 255자 O String
user_phone_number 사용자 전화번호(결제요청 TMS 발송용). 최대11자 X String
available_cards 카드사 제한 목록(없을 경우 전체)
현재 SHINHAN, KB, HYUNDAI, LOTTE, SAMSUNG, NH, BC, HANA, CITI, KAKAOBANK 지원.
ex) [“HANA”, “BC”]
X JSON Array 형태
payment_method_type 결제 수단 제한(없을 경우 전체)
CARD, MONEY 중 하나
X String
install_month 카드할부개월수. 0~12(개월) 사이의 값 X Integer
custom_json 결제화면에 보여주고 싶은 custom message. 사전협의가 필요한 값 X JSON Map 형태로 key, value 모두 String

예를 들어, 단건 결제를 테스트 해보고 싶다면 다음과 같이 요청합니다.

curl -v -X POST 'https://kapi.kakao.com/v1/payment/ready' \
-H 'Authorization: KakaoAK xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data-urlencode 'cid=TC0ONETIME' \
--data-urlencode 'partner_order_id=partner_order_id' \
--data-urlencode 'partner_user_id=partner_user_id' \
--data-urlencode 'item_name=초코파이' \
--data-urlencode 'quantity=1' \
--data-urlencode 'total_amount=2200' \
--data-urlencode 'vat_amount=200' \
--data-urlencode 'tax_free_amount=0' \
--data-urlencode 'approval_url=https://developers.kakao.com/success' \
--data-urlencode 'fail_url=https://developers.kakao.com/fail' \
--data-urlencode 'cancel_url=https://developers.kakao.com/cancel'

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래의 값을 포함합니다.
가맹점 서버에서는 응답 바디의 tid 저장하고, 사용자가 요청한 클라이언트에서는 환경에 맞는 redirect url로 redirect해줘야 합니다.

설명 타입
tid 결제 고유 번호. 20자 String
tms_result TMS 발송 성공 여부. 결제준비 API호출시 전화번호를 입력한 경우에만 해당하는 값 Boolean
next_redirect_app_url 요청한 클라이언트가 모바일 앱일 경우 해당 url을 통해 카카오톡 결제페이지를 띄움 String
next_redirect_mobile_url 요청한 클라이언트가 모바일 웹일 경우 해당 url을 통해 카카오톡 결제페이지를 띄움 String
next_redirect_pc_url 요청한 클라이언트가 pc 웹일 경우 redirect. 카카오톡으로 TMS를 보내기 위한 사용자입력화면이으로 redirect String
android_app_scheme 카카오페이 결제화면으로 이동하는 안드로이드 앱스킴 String
ios_app_scheme 카카오페이 결제화면으로 이동하는 iOS 앱스킴 String
created_at 결제 준비 요청 시간 Datetime

예를 들면,

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "tid": "T1234567890123456789",
 "tms_result": false,
 "next_redirect_app_url": "https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/aInfo",
 "next_redirect_mobile_url": "https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/mInfo",
 "next_redirect_pc_url": "https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/info",
 "android_app_scheme": "kakaotalk://kakaopay/pg?url=https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/order",
 "ios_app_scheme": "kakaotalk://kakaopay/pg?url=https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/order",
 "created_at": "2016-11-15T21:18:22"
}

결제연동

결제준비 API Response를 활용해 사용자가 결제수단을 선택할 수 있게 하고 결제승인 단계로 가는 프로세스를 설명합니다.

tms_result
  • 전화번호를 파라미터로 넘긴 경우 전화번호에 연결된 계정으로 결제요청 메세지를 발송 시도합니다.
  • access_token 기반으로 결제준비 API를 호출했을 경우 해당 계정에 연결된 카카오톡으로 결제요청 메세지를 발송 시도합니다.
  • 메시지 발송 우선순위 : 전화번호 > access_token
next_redirect_pc_url
  • PC 연동

    • PC 결제의 경우 Popup 혹은 Layer 방식으로 next_redirect_pc_url을 직접 띄워줍니다.
  • 제공기능

    • 사용자 정보를 입력받아 결제요청 메시지를 발송하는 기능을 제공합니다.
    • tms_result가 true인 경우 카운트 다운을 하는 결제 대기화면으로 로딩됩니다.
    • 결제 대기화면으로 전환된 이후에는 사용자가 카카오톡 결제창에서 결제수단을 선택할 때 까지 카운트 다운을 하면서 polling 방식으로 결제상태를 체크합니다.
    • 사용자가 카카오톡 결제창에서 결제수단을 선택하고 비밀번호 인증까지 마치면 결제 대기화면에서 결제준비 API Request로 받은 approval_url에 pg_token 파라미터를 붙여서 redirect 합니다.
    • 사용자가 우측 상단의 결제취소 버튼을 누른 경우 결제준비 API Request로 받은 cancel_url로 redirect 합니다.
    • cancel_url에서는 보안을 위해 결제상태조회 API를 호출하여 상태값이 QUIT_PAYMENT(사용자가 결제를 중단한 상태)인 것을 확인하고 결제 중단 처리를 해야 합니다.
    • 결제제한 시간(15분)이 지난 경우 결제준비 API Request로 받은 fail_url로 redirect 합니다.
  • 결제승인 처리

    • approval_url에서 결제승인 API를 호출할 때 pg_token을 parameter로 넘겨줘야 합니다.
    • 결제승인 API 처리 후 결제 결과 화면을 사용자에게 보여주고 Popup 혹은 Layer를 처리합니다.
    • app, mobile web에서 전화번호를 입력받고 싶은 경우에도 사용 가능합니다.
next_redirect_mobile_url
  • 모바일 웹 연동

    • 모바일 웹 결제의 경우 해당 url로 redirect 해줍니다.
  • 제공기능

    • 각 브라우저에 대응해서 카카오톡 결제창 custom app scheme을 직접 호출하기도 하고 사용자가 “다음” 버튼을 눌려서 custom app scheme 호출을 유도하기도 합니다.
    • 사용자는 카카오톡 결제창에서 결제수단 선택과 비밀번호 인증 단계를 완료하고 해당 화면으로 돌아와야만 결제가 진행됩니다.
    • 결제상태 체크 polling이 성공하거나 사용자가 “결제완료” 버튼을 눌렀을 경우 결제준비 API Request로 받은 approval_url에 pg_token 파라미터를 붙여서 redirect 합니다.
    • 사용자가 우측 상단의 결제취소 버튼을 누른 경우 결제준비 API Request로 받은 cancel_url로 redirect 합니다.
    • cancel_url에서는 보안을 위해 결제상태조회 API를 호출하여 상태값이 QUIT_PAYMENT(사용자가 결제를 중단한 상태)인 것을 확인하고 결제 중단 처리를 해야 합니다.
    • 결제제한 시간(15분)이 지난 경우 결제준비 API Request로 받은 fail_url로 redirect 합니다.
  • 결제승인 처리

    • approval_url에서 결제승인 API를 호출할 때 pg_token을 parameter로 넘겨줘야 합니다.
    • 결제승인 API 처리 후 결제 결과 화면을 사용자에게 보여줍니다.
next_redirect_app_url
  • 앱 연동

    • 앱 결제의 경우 해당 url을 webview로 띄워줍니다.
    • iOS의 경우 해당 앱에서 canOpenURL 을 사용할 경우 info.plist 아래 LSApplicationQueriesSchemes 키값에 스킴 "kakaotalk"을 추가해줘야 합니다.
  • 제공기능

    • 카카오톡 결제창 custom app scheme을 자동으로 호출합니다.
    • 사용자는 카카오톡 결제창에서 결제수단 선택과 비밀번호 인증 단계를 완료하고 해당 화면으로 돌아와야만 결제가 진행됩니다.
    • 결제상태 체크 polling이 성공하거나 사용자가 “결제완료” 버튼을 눌렀을 경우 결제준비 API Request로 받은 approval_url에 pg_token 파라미터를 붙여서 redirect 합니다.
    • 사용자가 우측 상단의 결제취소 버튼을 누른 경우 결제준비 API Request로 받은 cancel_url로 redirect 합니다.
    • cancel_url에서는 보안을 위해 결제상태조회 API를 호출하여 상태값이 QUIT_PAYMENT(사용자가 결제를 중단한 상태)인 것을 확인하고 결제 중단 처리를 해야 합니다.
    • 결제제한 시간(15분)이 지난 경우 결제준비 API Request로 받은 fail_url로 redirect 합니다.
  • 결제승인 처리

    • approval_url에서 결제승인 API를 호출할 때 pg_token을 parameter로 넘겨줘야 합니다.
    • 결제승인 API 처리 후 결제 결과 화면을 사용자에게 보여주고 webview를 처리합니다.

결제승인

결제승인을 위해 API를 호출합니다.

카카오페이 API는 사용자의 AccessToken 뿐만 아니라, 어드민 키(Admin Key)로도 요청 가능합니다. 어드민 키를 사용할 때에는 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 가맹점 서버에서 API를 호출하시기 바랍니다.

[Request]

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

어드민키/사용자토큰을 헤더에 담아 아래 파라미터의 값들과 함께 POST로 요청합니다.

설명 필수 타입
cid 가맹점 코드. 10자. O String
tid 결제 고유번호. 결제준비 API의 응답에서 얻을 수 있음 O String
partner_order_id 가맹점 주문번호. 결제준비 API에서 요청한 값과 일치해야 함 O String
partner_user_id 가맹점 회원 id. 결제준비 API에서 요청한 값과 일치해야 함 O String
pg_token 결제승인 요청을 인증하는 토큰. 사용자가 결제수단 선택 완료시 approval_url로 redirection해줄 때 pg_token을 query string으로 넘겨줌 O String
payload 해당 Request와 매핑해서 저장하고 싶은 값. 최대 200자 X String

예를 들면,

curl -v -X POST 'https://kapi.kakao.com/v1/payment/approve' \
-H 'Authorization: KakaoAK xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data-urlencode 'cid=TC0ONETIME' \
--data-urlencode 'tid=T1234567890123456789' \
--data-urlencode 'partner_order_id=partner_order_id' \
--data-urlencode 'partner_user_id=partner_user_id' \
--data-urlencode 'pg_token=xxxxxxxxxxxxxxxxxxxx'

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래의 값을 포함합니다.

설명 타입
aid Request 고유 번호 String
tid 결제 고유 번호 String
cid 가맹점 코드 String
sid subscription id. 정기(배치)결제 CID로 결제요청한 경우 발급 String
partner_order_id 가맹점 주문번호 String
partner_user_id 가맹점 회원 id String
payment_method_type 결제 수단. CARD, MONEY 중 하나 String
amount 결제 금액 정보 JSON Object
card_info 결제 상세 정보(결제수단이 카드일 경우만 포함) JSON Object
item_name 상품 이름. 최대 100자 String
item_code 상품 코드. 최대 100자 String
quantity 상품 수량 Integer
created_at 결제 준비 요청 시각 Datetime
approved_at 결제 승인 시각 Datetime
payload Request로 전달한 값 String

amount 정보

설명 타입
total 전체 결제 금액 Integer
tax_free 비과세 금액 Integer
vat 부가세 금액 Integer
point 사용한 포인트 금액 Integer

card_info 정보

설명 타입
purchase_corp 매입카드사 한글명 String
purchase_corp_code 매입카드사 코드 String
issuer_corp 카드발급사 한글명 String
issuer_corp_code 카드발급사 코드 String
bin 카드 BIN String
card_type 카드타입 String
install_month 할부개월수 String
approved_id 카드사 승인번호 String

결제승인 요청이 성공한 경우에 예를 들면,

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
 },
 "created_at": "2016-11-15T21:18:22",
 "approved_at": "2016-11-15T21:20:47"
}

결제승인 요청이 실패하는 경우에는 필요에 따라 결제 원천사(머니/카드)의 실패 정보가 포함 될 수 있습니다. 예를 들면,

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

정기결제 프로세스

정기결제를 위해선 SID발급이 필요합니다.

정기결제용으로 발급받은 CID를 사용해 단건결제 프로세스를 진행하면 SID가 발급됩니다.
이 때, 상품총액을 0원으로 설정한 경우 SID만 발급받을 수 있습니다.
2회차 결제부터는 발급받은 SID를 통해 정기결제 API를 호출해 정기결제를 진행할 수 있습니다.

테스트결제를 위해서는 "TCSUBSCRIP" 이라는 테스트 CID값을 사용할 수 있습니다.
실결제를 위해서는 카카오페이와 제휴 후 정기결제용 CID를 발급받아야 합니다.

결제준비

정기결제를 위해 1회차 요청에서 결제준비 API를 요청해야 합니다. 결제준비 API 사용에 대한 자세한 내용은 단건결제 결제준비 를 참고하세요.

정기 결제를 테스트 해보고 싶다면 다음과 같이 요청합니다.

curl -v -X POST 'https://kapi.kakao.com/v1/payment/ready' \
-H 'Authorization: KakaoAK xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data-urlencode 'cid=TCSUBSCRIP' \
--data-urlencode 'partner_order_id=subscription_order_id_1' \
--data-urlencode 'partner_user_id=subscription_user_id_1' \
--data-urlencode 'item_name=음악정기결제' \
--data-urlencode 'quantity=1' \
--data-urlencode 'total_amount=9900' \
--data-urlencode 'vat_amount=900' \
--data-urlencode 'tax_free_amount=0' \
--data-urlencode 'approval_url=https://developers.kakao.com/success' \
--data-urlencode 'fail_url=https://developers.kakao.com/fail' \
--data-urlencode 'cancel_url=https://developers.kakao.com/cancel'

결제연동

결제연동 프로세스는 단건결제 결제연동과 동일합니다.

결제승인

정기결제승인을 위해 API를 호출합니다. 결제승인 API에 대한 자세한 내용은 단건결제 결제승인을 참고하세요.

정기결제승인 요청이 성공한 경우에 예를 들면,

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "aid": "A5678901234567890123",
 "tid": "T2468013579246801357",
 "sid": "S1234567890987654321",
 "cid": "TCSUBSCRIP",
 "partner_order_id": "subscription_order_id_1",
 "partner_user_id": "subscription_user_id_1",
 "payment_method_type": "MONEY",
 "item_name": "음악정기결제",
 "quantity": 1,
 "amount": {
  "total": 9900,
  "tax_free": 0,
  "vat": 900,
  "point": 0
 },
 "created_at": "2016-11-15T21:18:22",
 "approved_at": "2016-11-15T21:20:47"
}

정기결제 (2회차이후)

정기결제를 위한 API를 요청하기 위해서는 최초 한번은 정기결제 CID로 SID를 발급받기 위한 결제가 이루어져야 합니다.
2회차 결제부터는 발급받은 SID로 정기결제 API를 통해서 결제합니다.

카카오페이-결제내역조회 API는 어드민 키(Admin Key)로도 요청 가능합니다. 어드민 키를 사용할 때에는 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 가맹점 서버에서 API를 호출하시기 바랍니다.

[Request]

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

어드민키/사용자토큰을 헤더에 담아 아래 파라미터의 값들과 함께 POST로 요청합니다.

설명 필수 타입
cid 가맹점 코드. 10자. O String
sid 정기결제 키. 20자. O String
partner_order_id 가맹점 주문번호. 최대 100자 O String
partner_user_id 가맹점 회원 id. 최대 100자. SID를 발급받았던 최초 결제준비 API에서 요청한 값과 일치해야 함 O String
item_name 상품명. 최대 100자 X String
item_code 상품코드. 최대 100자 X String
quantity 상품 수량 O Integer
total_amount 상품 총액 O Integer
tax_free_amount 상품 비과세 금액 O Integer
vat_amount 상품 부가세 금액(안보낼 경우 (상품총액 - 상품 비과세 금액)/11 : 소숫점이하 반올림) X Integer
payload 해당 Request와 매핑해서 저장하고 싶은 값. 최대 200자 X String

예를 들면,

{
curl -v -X POST 'https://kapi.kakao.com/v1/payment/subscription' \
> -H 'Authorization: KakaoAK xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
> -d 'cid=TCSUBSCRIP' \
> -d 'sid=S1234567890987654321' \
> -d 'partner_order_id=subscription_order_id_1' \
> -d 'partner_user_id=subscription_user_id_1' \
> -d 'item_name=음악정기결제' \
> -d 'quantity=1' \
> -d 'total_amount=9900' \
> -d 'vat_amount=900' \
> -d 'tax_free_amount=0'

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래의 값을 포함합니다.

설명 타입
aid Request 고유 번호 String
tid 결제 고유 번호 String
cid 가맹점 코드 String
sid 정기(배치)결제 고유 번호. 20자 String
partner_order_id 가맹점 주문번호. String
partner_user_id 가맹점 회원 id. String
payment_method_type 결제 수단. CARD, MONEY 중 하나 String
amount 결제 금액 정보 JSON Object
card_info 결제 상세 정보(결제수단이 카드일 경우만 포함) JSON Object
item_name 상품 이름. 최대 100자 String
item_code 상품 코드. 최대 100자 String
quantity 상품 수량 Integer
created_at 결제 준비 요청 시각 Datetime
approved_at 결제 승인 시각 Datetime
payload Request로 전달한 값 String

amount 정보

설명 타입
total 전체 결제 금액 Integer
tax_free 비과세 금액 Integer
vat 부가세 금액 Integer

card_info 정보

설명 타입
purchase_corp 매입카드사 한글명 String
purchase_corp_code 매입카드사 코드 String
issuer_corp 카드발급사 한글명 String
issuer_corp_code 카드발급사 코드 String
bin 카드 BIN String
card_type 카드타입 String
install_month 할부개월수 String
approved_id 카드사 승인번호 String

정기결제 요청이 성공한 경우에 예를 들면,

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "aid": "A5678901234567890123",
 "cid": "TCSUBSCRIP",
 "sid": "S1234567890987654321",
 "tid": "T2468013579246801357",
 "partner_order_id": "subscription_order_id_1",
 "partner_user_id": "subscription_user_id_1",
 "payment_method_type": "MONEY",
 "item_name": "음악정기결제",
 "quantity": 1,
 "amount": {
  "total": 9900,
  "tax_free": 0,
  "vat": 900
 },
 "created_at": "2016-11-17T16:02:19",
 "approved_at": "2016-11-17T16:02:20"
}

정기결제 요청이 실패한 경우에는 필요에 따라 결제 원천사(머니/카드)의 실패 정보가 포함 될 수 있습니다. 예를 들면,

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "code": -782,
 "message": "subscription failure!",
 "extras": {
  "method_result_code": "8008",
  "method_result_message": "거래거절 거래금액미달"
 }
}

결제상태조회

결제상태를 조회하기 위해 API를 호출합니다.

카카오페이 API는 사용자의 AccessToken 뿐만 아니라, 어드민 키(Admin Key)로도 요청 가능합니다. 어드민 키를 사용할 때에는 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 가맹점 서버에서 API를 호출하시기 바랍니다.

[Request]

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

어드민키/사용자토큰을 헤더에 담아 아래 파라미터의 값들과 함께 POST로 요청합니다.

설명 필수 타입
cid 가맹점 코드. 10자. O String
tid 결제 고유번호. 20자 O String

예를 들면,

curl -v -X POST 'https://kapi.kakao.com/v1/payment/status' \
-H 'Authorization: KakaoAK xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d 'cid=TC0ONETIME' \
-d 'tid=T1234567890123456789'

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래의 값을 포함합니다.

설명 타입
tid 결제 고유 번호. 결제요청 API 응답에 오는 값과 동일해야 함 String
cid 가맹점 코드. 결제준비 API에서 요청한 값과 일치해야 함 String
status 결제상태값 String
partner_order_id 가맹점 주문번호 String
partner_user_id 가맹점 회원 id String
payment_method_type 결제 수단. CARD, MONEY 중 하나 String
amount 결제 금액 정보 JSON Object
canceled_amount 취소된 금액 정보 JSON Object
cancel_available_amount 해당 결제에 대해 취소 가능 금액 JSON Object
item_name 상품 이름. 최대 100자 String
item_code 상품 코드. 최대 100자 String
quantity 상품 수량 Integer
created_at 결제 준비 요청 시각 Datetime
approved_at 결제 승인 시각 Datetime
canceled_at 결제 취소 시각 Datetime
payment_action_details 결제/취소 상세 JSON Object의 List

status

상태명 설명
READY 결제요청
SEND_TMS 결제요청 TMS 발송완료
OPEN_PAYMENT 사용자가 카카오페이 결제화면을 열었음
SELECT_METHOD 결제수단 선택, 인증 완료
ARS_WAITING ARS인증 진행중
AUTH_PASSWORD 비밀번호 인증 완료
ISSUED_SID SID 발급완료(정기결제에서 SID만 발급 한 경우)
SUCCESS_PAYMENT 결제완료
PART_CANCEL_PAYMENT 부분취소된 상태
CANCEL_PAYMENT 결제된 금액이 모두 취소된 상태.
부분취소 여러 번해서 모두 취소된 경우도 포함
FAIL_AUTH_PASSWORD 사용자 비밀번호 인증 실패
QUIT_PAYMENT 사용자가 결제를 중단한 경우
FAIL_PAYMENT 결제 승인 실패

amount 정보

설명 타입
total 전체 결제 금액 Integer
tax_free 비과세 금액 Integer
vat 부가세 금액 Integer

canceled_amount 정보

설명 타입
total 전체 취소 금액 Integer
tax_free 취소된 비과세 금액 Integer
vat 취소된 부가세 금액 Integer

cancel_available_amount 정보

설명 타입
total 전체 취소 가능 금액 Integer
tax_free 취소 가능한 비과세 금액 Integer
vat 취소 가능한 부가세 금액 Integer

payment_action_details 정보

설명 타입
aid Request 고유 번호 String
approved_at 거래시간 String
amount 결제/취소 총액 Integer
point_amount 결제/취소 포인트 금액 Integer
payment_method_type 결제 수단. CARD, MONEY 중 하나 String
payment_action_type 결제 타입.
PAYMENT(결제), CANCEL(결제취소), ISSUED_SID(SID 발급) 중 하나
String
payload Request로 전달한 값 String

예를 들면,

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "tid": "T1234567890123456789",
 "cid": "TC0ONETIME",
 "status": "SUCCESS_PAYMENT",
 "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
 },
 "cancel_available_amount": {
  "total": 2200,
  "tax_free": 0,
  "vat": 200
 },
 "created_at": "2016-11-15T21:18:22",
 "approved_at": "2016-11-15T21:20:48",
 "payment_action_details": [
   {
    "aid": "A5678901234567890123",
    "payment_action_type": "PAYMENT",
    "payment_method_type": "MONEY",
    "amount": 2200,
    "point_amount": 0,
    "approved_at": "2016-11-15T21:20:48"
   }
  ]
}

결제취소

결제취소를 요청하기 위해 API를 호출합니다.

카카오페이 API는 사용자의 AccessToken 뿐만 아니라, 어드민 키(Admin Key)로도 요청 가능합니다. 어드민 키를 사용할 때에는 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 가맹점 서버에서 API를 호출하시기 바랍니다.

[Request]

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

어드민키/사용자토큰을 헤더에 담아 아래 파라미터의 값들과 함께 POST로 요청합니다.

설명 필수 타입
cid 가맹점 코드. 10자. O String
tid 결제 고유번호. 20자. O String
cancel_amount 취소 금액 O Integer
cancel_tax_free_amount 취소 비과세 금액 O Integer
cancel_vat_amount 취소 부가세 금액(안보낼 경우 (취소 금액 - 취소 비과세 금액)/11 : 소숫점이하 반올림) X Integer
payload 해당 Request와 매핑해서 저장하고 싶은 값. 최대 200자 X String

예를 들면,

curl -v -X POST 'https://kapi.kakao.com/v1/payment/cancel' \
-H 'Authorization: KakaoAK xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d 'cid=TC0ONETIME' \
-d 'tid=T1234567890123456789' \
-d 'cancel_amount=2200' \
-d 'cancel_tax_free_amount=0' \
-d 'cancel_vat_amount=200'

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래의 값을 포함합니다.

설명 타입
aid Request 고유 번호 String
tid 결제 고유 번호. 10자. String
cid 가맹점 코드. 20자 String
status 결제상태값 String
partner_order_id 가맹점 주문번호. 최대 100자. String
partner_user_id 가맹점 회원 id. 최대 100자. String
payment_method_type 결제 수단. CARD, MONEY 중 하나 String
amount 결제 금액 정보 JSON Object
canceled_amount 이번 요청으로 취소된 금액 정보 JSON Object
cancel_available_amount 해당 결제에 대해 취소 가능 금액 JSON Object
item_name 상품 이름. 최대 100자 String
item_code 상품 코드. 최대 100자 String
quantity 상품 수량 Integer
created_at 결제 준비 요청 시각 Datetime
approved_at 결제 승인 시각 Datetime
canceled_at 결제 취소 시각 Datetime
payload Request로 전달한 값 String

status

상태명 설명
READY 결제요청
SEND_TMS 결제요청 TMS 발송완료
OPEN_PAYMENT 사용자가 카카오페이 결제화면을 열었음
SELECT_METHOD 결제수단 선택, 인증 완료
ARS_WAITING ARS인증 진행중
AUTH_PASSWORD 비밀번호 인증 완료
ISSUED_SID SID 발급완료(정기결제에서 SID만 발급 한 경우)
SUCCESS_PAYMENT 결제완료
PART_CANCEL_PAYMENT 부분취소된 상태
CANCEL_PAYMENT 결제된 금액이 모두 취소된 상태.
부분취소 여러 번해서 모두 취소된 경우도 포함
FAIL_AUTH_PASSWORD 사용자 비밀번호 인증 실패
QUIT_PAYMENT 사용자가 결제를 중단한 경우
FAIL_PAYMENT 결제 승인 실패

amount 정보

설명 타입
total 전체 결제 금액 Integer
tax_free 비과세 금액 Integer
vat 부가세 금액 Integer

canceled_amount 정보

설명 타입
total 전체 취소 금액 Integer
tax_free 취소된 비과세 금액 Integer
vat 취소된 부가세 금액 Integer

cancel_available_amount 정보

설명 타입
total 전체 취소 가능 금액 Integer
tax_free 취소 가능한 비과세 금액 Integer
vat 취소 가능한 부가세 금액 Integer

결제 취소 요청이 성공 한 경우에 예를 들면,

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "aid": "A5678901234567890123",
 "tid": "T1234567890123456789",
 "cid": "TC0ONETIME",
 "status": "CANCEL_PAYMENT",
 "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
 },
 "canceled_amount": {
  "total": 2200,
  "tax_free": 0,
  "vat": 200
 },
 "cancel_available_amount": {
  "total": 0,
  "tax_free": 0,
  "vat": 0
 },
 "created_at": "2016-11-15T21:18:22",
 "approved_at": "2016-11-15T21:20:48",
 "canceled_at": "2016-11-15T21:28:28"
}

결제 취소 요청이 실패한 경우에는 필요에 따라 결제 원천사(머니/카드)의 실패 정보가 포함 될 수 있습니다. 예를 들면,

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "code": -781,
 "message": "cancel failure!",
 "extras": {
  "method_result_code": "6666",
  "method_result_message": "원거래없음"
 }
}

정기결제 상태조회

정기결제 SID의 상태 확인을 위해 호출합니다.

카카오페이 API는 사용자의 AccessToken 뿐만 아니라, 어드민 키(Admin Key)로도 요청 가능합니다. 어드민 키를 사용할 때에는 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 가맹점 서버에서 API를 호출하시기 바랍니다.

[Request]

POST /v1/payment/manage/subscription/status HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}
Content-type: application/x-www-form-urlencoded;charset=utf-8
POST /v1/payment/manage/subscription/status HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-type: application/x-www-form-urlencoded;charset=utf-8

어드민키/사용자토큰을 헤더에 담아 아래 파라미터의 값들과 함께 POST로 요청합니다.

설명 필수 타입
cid 가맹점 코드. 10자 O String
sid 정기결제 고유번호. 20자 O String

예를 들면,

curl -v -X POST 'https://kapi.kakao.com/v1/payment/manage/subscription/status' \
-H 'Authorization: KakaoAK xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d 'cid=TCSUBSCRIP' \
-d 'sid=S1234567890987654321'

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래의 값을 포함합니다.

설명 타입
available 사용 가능 여부 Boolean
cid 가맹점 코드. 10자 String
sid 정기(배치)결제 고유 번호. 20자 String
status 정기결제 상태. ACTIVE(활성화 상태), INACTIVE(비활성화 상태) 중 하나 String
payment_method_type 결제 수단. CARD, MONEY 중 하나 String
item_name 상품 이름. 최대 100자 String
created_at SID 발급 시각 Datetime
last_approved_at 마지막 결제승인 시각 Datetime
inactivated_at 정기결제 취소 시각 Datetime

예를 들면,

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "available": true,
 "cid": "TCSUBSCRIP",
 "sid": "S1234567890987654321",
 "status": "ACTIVE",
 "item_name": "음악정기결제",
 "payment_method_type": "MONEY",
 "created_at": "2016-11-17T16:01:13",
 "last_approved_at": "2016-11-17T16:02:20"
}

정기결제 비활성화

정기결제 SID 비활성화를 요청할 수 있습니다. 정기결제 비활성화 API를 호출하면 발급했던 SID가 비활성화 되고, 해당 SID로 더이상 정기결제를 진행할 수 없습니다.

카카오페이 API는 사용자의 AccessToken 뿐만 아니라, 어드민 키(Admin Key)로도 요청 가능합니다. 어드민 키를 사용할 때에는 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 가맹점 서버에서 API를 호출하시기 바랍니다.

[Request]

POST /v1/payment/manage/subscription/inactive HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}
Content-type: application/x-www-form-urlencoded;charset=utf-8
POST /v1/payment/manage/subscription/inactive HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-type: application/x-www-form-urlencoded;charset=utf-8

어드민키/사용자토큰을 헤더에 담아 아래 파라미터의 값들과 함께 POST로 요청합니다.

설명 필수 타입
cid 가맹점 코드. 10자 O String
sid 정기결제 고유번호. 20자 O String

예를 들면,

curl -v -X POST 'https://kapi.kakao.com/v1/payment/manage/subscription/inactive' \
-H 'Authorization: KakaoAK xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d 'cid=TCSUBSCRIP' \
-d 'sid=S1234567890987654321'

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래의 값을 포함합니다.

설명 타입
cid 가맹점 코드. 10자 String
sid 정기(배치)결제 고유 번호. 20자 String
status 정기결제 상태. ACTIVE(활성화 상태), INACTIVE(비활성화 상태) 중 하나 String
created_at SID 발급 시각 Datetime
last_approved_at 마지막 결제승인 시각 Datetime
inactivated_at 정기결제 취소 시각 Datetime

예를 들면,

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "cid": "TCSUBSCRIP",
 "sid": "S1234567890987654321",
 "status": "INACTIVE",
 "created_at": "2016-11-17T16:01:13",
 "inactivated_at": "2016-11-17T16:21:55",
 "last_approved_at": "2016-11-17T16:02:20"
}

결제내역조회

하루동안 발생한 가맹점에서의 결제내역을 조회하기 위해 API를 호출합니다.

카카오페이-결제내역조회 API는 어드민 키(Admin Key)로만 요청 가능합니다. 어드민 키를 사용할 때에는 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 가맹점 서버에서 API를 호출하시기 바랍니다.

[Request]

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

어드민키를 헤더에 담아 아래 파라미터의 값들과 함께 POST로 요청합니다.

설명 필수 타입
cid 가맹점 코드. 10자. cid/gid 둘중 하나는 값이 있어야 함 X String
gid 가맹점 정산 코드. 10자. cid/gid 둘중 하나는 값이 있어야 함 X String
date 결제내역을 조회하려는 날짜. yyyyMMdd 형식 O String
page 보여줄 페이지(default 1), 최소값 1 X Integer

예를 들면,

curl -v -X POST 'https://kapi.kakao.com/v1/payment/manage/report' \
-H 'Authorization: KakaoAK xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d 'cid=TC0ONETIME' \
-d 'date=20161115'
-d 'page=1'

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래의 값을 포함합니다.

설명 타입
data_list 결제/취소 내역 리스트 JSON Object의 List
page 페이지 정보 JSON Object

data_list 정보

설명 타입
tid 결제 고유번호. 20자 String
cid 가맹점 코드 String
approved_at 거래시간 String
partner_order_id 가맹점 주문번호. 최대 100자 String
item_name 상품 이름. 최대 100자 String
item_code 상품 코드. 최대 100자 String
amount 결제/취소 총액 Integer
point_amount 결제/취소 포인트 금액 Integer
payment_method_type 결제 수단. CARD, MONEY 중 하나 String
payment_action_type 결제 타입.
PAYMENT(결제), CANCEL(결제취소), ISSUED_SID(SID 발급) 중 하나
String
aid Request 고유 번호 String
payload Request로 전달한 값 String

page 정보

설명 타입
current_page 현재 페이지 Integer
total_pages 총 페이지 Integer
current_size 현재 페이지 데이터 개수 Integer
total_size 총 데이터 개수 Integer
first 첫번째 페이지 여부 Boolean
last 마지막 페이지 여부 Boolean

예를 들면,

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "data_list": [
  {
   "tid": "T9876543210987654321",
   "aid": "A6789012345678901234",
   "partner_order_id": "partner_order_id_1",
   "payment_action_type": "PAYMENT",
   "payment_method_type": "CARD",
   "amount": 4000,
   "point_amount": 0,
   "approved_at": "2016-11-15T14:28:47"
  },
  {
   "tid": "T1234567890123456789",
   "aid": "A5678901234567890123",
   "partner_order_id": "partner_order_id_2",
   "payment_action_type": "CANCEL",
   "payment_method_type": "MONEY",
   "amount": 2000,
   "point_amount": 0,
   "approved_at": "2016-11-15T21:28:28"
  },
  {
   "tid": "T4567890123456789123",
   "aid": "A1235678901234567890",
   "partner_order_id": "partner_order_id_3",
   "payment_action_type": "ISSUED_SID",
   "payment_method_type": "MONEY",
   "amount": 0,
   "point_amount": 0,
   "approved_at": "2016-11-15T23:21:11"
  }
 ],
 "page": {
  "current_page": 1,
  "current_size": 3,
  "first": true,
  "last": true,
  "total_pages": 1,
  "total_size": 3
 }
}

Last Modified : 2017-08-17