Kakao Developers

페이지 이동경로

문서>
카카오페이>
단건 결제

카카오페이

단건 결제

이 문서는 카카오페이 단건 결제 사용 방법을 안내합니다.

단건 결제는 한 번의 결제로 지불이 완료되는 구매건에 해당하며, 정기적으로 여러 차례 결제가 발생하는 결제인 정기 결제와 다릅니다. 일반적인 상품 판매나 비용 지불 시 단건 결제를 사용합니다.

단건 결제 시 가맹점 코드(CID)가 필요합니다. 테스트 결제는 가맹점 코드로 'TC0ONETIME'를 사용합니다. 실제로 결제하려면 카카오페이와 제휴를 맺어 가맹점 코드를 발급 받아야 합니다.

결제 준비하기

기본 정보

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

카카오페이 결제를 시작하기 위해 상세 정보를 카카오페이 서버에 전달하고 결제 고유 번호(TID)를 받는 단계입니다. 어드민 키를 헤더에 담아 파라미터 값들과 함께 POST로 요청합니다.

요청이 성공하면 응답 바디에 JSON 객체로 다음 단계 진행을 위한 값들을 받습니다. 서버(Server)는 tid를 저장하고, 클라이언트는 사용자 환경에 맞는 URL로 리다이렉트(redirect)합니다.

Request

Parameter

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://`	X

* 컵 보증금(green_deposit) 사용 시 부분 취소 불가

* 카드사 코드: SHINHAN, KB, HYUNDAI, LOTTE, SAMSUNG, NH, BC, HANA, CITI, KAKAOBANK, KAKAOPAY

* KAKAOBANK, KAKAOPAY, CITY 는 KB/BC에 미포함, 별도 지정 필요

* SUHYUP, SHINHYUP, JEONBUK, JEJU, SC 등 기타 상세 분류가 필요한 경우 문의 요망

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`	결제 준비 요청 시간

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v1/payment/ready" \
-H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \
--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

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
 "tid": "T1234567890123456789",
 "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의 응답으로 받은 Redirect URL 중 사용자 접속 환경에 맞는 URL을 선택해 리다이렉트를 실행합니다. 이후 클라이언트에는 결제 대기 화면이 노출되며, 사용자는 카카오톡 결제 화면에서 결제 수단을 선택할 수 있습니다. 이 프로세스는 카카오페이의 서비스 화면에서 일어나기 때문에 가맹점으로 다른 요청을 보내지 않습니다. 사용자의 접속 환경별로 고려해야되는 내용은 아래와 같습니다.

공통

결제 대기 화면은 사용자가 카카오톡 결제 화면에서 결제 수단을 선택할 때까지 카운트다운을 하며, 결제 상태를 지속적으로 직접 체크(polling 방식)합니다.

사용자가 카카오톡 결제 화면에서 결제수단을 선택하고 비밀번호 인증까지 마치면, 결제 대기 화면은 결제 준비 API 요청 시 전달 받은 approval_url에 pg_token 파라미터를 붙여 리다이렉트합니다. pg_token은 결제 승인 API 호출 시 사용합니다. 사용자가 결제를 취소한 경우의 처리는 이해하기를 참고합니다.

next_redirect_pc_url

결제 준비 API 응답으로 받으며, PC 환경에서 사용합니다. URL을 팝업(Popup) 또는 레이어(Layer) 방식으로 띄웁니다.

사용자가 생년월일과 카카오톡 휴대전화번호를 입력하여 결제 요청 카카오톡 메시지를 보내는 기능
QR 코드를 통해 결제 진행하는 기능

위 두 가지 방식을 지원하며, 결제창으로 이동 후 결제 수단을 선택하고 비밀번호를 입력하여 결제를 진행합니다.

사용자 정보 입력(전화번호)이 필요한 경우, 모바일 환경에서도 PC 환경을 위한 URL을 사용할 수 있습니다.

next_redirect_mobile_url

결제 준비 API 응답으로 받으며, 모바일 웹 환경에서 사용합니다. URL을 웹뷰(Web view)로 띄웁니다. iOS의 경우, canOpenURL 사용 시 Info.plist 아래 LSApplicationQueriesSchemes 키 값에 "kakaotalk" 스킴(Scheme)을 추가해야 합니다.

브라우저마다 동작이 다를 수 있습니다. 카카오톡 결제 화면으로 이동하는 커스텀 앱 스킴(Custom App Scheme)을 직접 호출하기도 하고, 사용자가 직접 "다음" 버튼을 눌러야 하는 경우도 있습니다. 사용자는 커스텀 앱 스킴을 통해 카카오톡의 결제 화면으로 이동하고, 결제 수단과 비밀번호를 입력해 결제를 진행합니다.

next_redirect_app_url

결제 준비 API 응답으로 받으며, 모바일 앱 환경에서 사용합니다. 카카오톡 결제 화면으로 이동하는 커스텀 앱 스킴(Custom App Scheme)을 자동 호출하며, 해당 URL을 웹뷰로 띄웁니다. 사용자는 결제 화면으로 이동해, 결제 수단을 선택하고 비밀번호를 입력해 결제를 진행합니다.

iOS의 경우 앱에서 canOpenURL을 사용할 경우 Info.plist 아래 LSApplicationQueriesSchemes 키값에 스킴 "kakaotalk"을 추가해야 합니다. 자세한 내용은 iOS 9.0 이상일 때 추가로 설정해야 할 것을 참고합니다.

결제 승인 요청하기

기본 정보

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

사용자가 결제 수단을 선택하고 비밀번호를 입력해 결제 인증을 완료한 뒤, 최종적으로 결제 완료 처리를 하는 단계입니다. 결제 승인 API를 호출하면 결제 준비 단계에서 시작된 결제건이 승인으로 완료 처리됩니다. 결제 승인 요청이 실패하면 카드사 등 결제 수단의 실패 정보가 필요에 따라 포함될 수 있습니다.

Request

Parameter

Name	Type	Description	Required
cid	`String`	가맹점 코드, 10자	O
cid_secret	`String`	가맹점 코드 인증키, 24자, 숫자+영문 소문자 조합	X
tid	`String`	결제 고유번호, 결제 준비 API 응답에 포함	O
partner_order_id	`String`	가맹점 주문번호, 결제 준비 API 요청과 일치해야 함	O
partner_user_id	`String`	가맹점 회원 id, 결제 준비 API 요청과 일치해야 함	O
pg_token	`String`	결제승인 요청을 인증하는 토큰 사용자 결제 수단 선택 완료 시, approval_url로 redirection해줄 때 pg_token을 query string으로 전달	O
payload	`String`	결제 승인 요청에 대해 저장하고 싶은 값, 최대 200자	X
total_amount	`Integer`	상품 총액, 결제 준비 API 요청과 일치해야 함	X

Response

Name	Type	Description
aid	`String`	요청 고유 번호
tid	`String`	결제 고유 번호
cid	`String`	가맹점 코드
sid	`String`	정기 결제용 ID, 정기 결제 CID로 단건 결제 요청 시 발급
partner_order_id	`String`	가맹점 주문번호, 최대 100자
partner_user_id	`String`	가맹점 회원 id, 최대 100자
payment_method_type	`String`	결제 수단, CARD 또는 MONEY 중 하나
amount	`Amount`	결제 금액 정보
card_info	`CardInfo`	결제 상세 정보, 결제수단이 카드일 경우만 포함
item_name	`String`	상품 이름, 최대 100자
item_code	`String`	상품 코드, 최대 100자
quantity	`Integer`	상품 수량
created_at	`Datetime`	결제 준비 요청 시각
approved_at	`Datetime`	결제 승인 시각
payload	`String`	결제 승인 요청에 대해 저장한 값, 요청 시 전달된 내용

amount(JSON)

Name	Type	Description
total	`Integer`	전체 결제 금액
tax_free	`Integer`	비과세 금액
vat	`Integer`	부가세 금액
point	`Integer`	사용한 포인트 금액
discount	`Integer`	할인 금액
green_deposit	`Integer`	컵 보증금

card_info(JSON)

Name	Type	Description
purchase_corp	`String`	매입 카드사 한글명
purchase_corp_code	`String`	매입 카드사 코드
issuer_corp	`String`	카드 발급사 한글명
issuer_corp_code	`String`	카드 발급사 코드
kakaopay_purchase_corp	`String`	카카오페이 매입사명
kakaopay_purchase_corp_code	`String`	카카오페이 매입사 코드
kakaopay_issuer_corp	`String`	카카오페이 발급사명
kakaopay_issuer_corp_code	`String`	카카오페이 발급사 코드
bin	`String`	카드 BIN
card_type	`String`	카드 타입
install_month	`String`	할부 개월 수
approved_id	`String`	카드사 승인번호
card_mid	`String`	카드사 가맹점 번호
interest_free_install	`String`	무이자할부 여부(Y/N)
card_item_code	`String`	카드 상품 코드

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v1/payment/approve" \
-H "Authorization: KakaoAK ${APP_ADMIN_KEY}' \
--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: 결제 수단 MONEY일 때 성공

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"
}

Response: 결제 수단 CARD일 때 성공

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
    "cid": "TC0ONETIME",
    "aid": "A5678901234567890123",
    "tid": "T1234567890123456789",
    "partner_user_id": "partner_user_id",
    "partner_order_id": "partner_order_id",
    "payment_method_type": "CARD",
    "item_name": "카페아메리카노",
    "quantity": 1,
    "amount": {
        "total": 3200,
        "tax_free": 0,
        "vat": 0,
        "point": 0,
        "discount": 0,
        "green_deposit": 0
    },
    "card_info": {
        "interest_free_install": "N",
        "bin": "621640",
        "card_type": "체크",
        "card_mid": "123456789",
        "approved_id": "12345678",
        "install_month": "00",
        "purchase_corp": "비씨카드",
        "purchase_corp_code": "01",
        "issuer_corp": "수협카드",
        "issuer_corp_code": "13",
        "kakaopay_purchase_corp": "비씨카드",
        "kakaopay_purchase_corp_code": "104",
        "kakaopay_issuer_corp": "수협은행",
        "kakaopay_issuer_corp_code": "212"
    },
    "created_at": "2019-05-21T11:18:24",
    "approved_at": "2019-05-21T11:18:32"
}

Sample: 결제 수단 CARD 일 때 실패

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": "진행중인 거래가 있습니다. 잠시 후 다시 시도해 주세요."
    }
}

menu

시작하기

로그인

커뮤니케이션

지도/로컬

내비게이션

검색

인공지능

광고

결제

다운로드

참고정보

카카오페이

단건 결제

결제 준비하기

기본 정보

Request

Parameter

Response

Sample

Request

Response

결제 요청하기

공통

next_redirect_pc_url

next_redirect_mobile_url

next_redirect_app_url

결제 승인 요청하기

기본 정보

Request

Parameter

Response

amount(JSON)

card_info(JSON)

Sample

Request

Response: 결제 수단 MONEY일 때 성공

Response: 결제 수단 CARD일 때 성공

Sample: 결제 수단 CARD 일 때 실패

더 보기