페이지 이동경로
  • 문서>
  • 카카오페이>
  • 단건 결제

카카오페이

단건 결제

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

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

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

결제 준비하기

기본 정보
메서드 URL 인증 방식
POST https://kapi.kakao.com/v1/payment/ready 서비스 앱 어드민 키
권한 사전 설정 카카오 로그인 사용자 동의
- - - -

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-type Content-type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
본문
이름 타입 설명 필수
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 등 기타 상세 분류가 필요한 경우 문의 요망

응답

본문
이름 타입 설명
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 결제 준비 요청 시간

예제

요청
curl -v -X POST "https://kapi.kakao.com/v1/payment/ready" \
-H "Authorization: KakaoAK ${SERVICE_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"
응답
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_urlpg_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"을 추가해야 합니다.

결제 승인 요청하기

기본 정보
메서드 URL 인증 방식
POST https://kapi.kakao.com/v1/payment/approve 서비스 앱 어드민 키
권한 사전 설정 카카오 로그인 사용자 동의
- - - -

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

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-type Content-type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
본문
이름 타입 설명 필수
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

응답

본문
이름 타입 설명
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)
이름 타입 설명
total Integer 전체 결제 금액
tax_free Integer 비과세 금액
vat Integer 부가세 금액
point Integer 사용한 포인트 금액
discount Integer 할인 금액
green_deposit Integer 컵 보증금
card_info(JSON)
이름 타입 설명
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 카드 상품 코드

예제

요청
curl -v -X POST "https://kapi.kakao.com/v1/payment/approve" \
-H "Authorization: KakaoAK ${SERVICE_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"
응답: 결제 수단 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"
}
응답: 결제 수단 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"
}
응답: 결제 수단 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": "진행중인 거래가 있습니다. 잠시 후 다시 시도해 주세요."
    }
}

더 보기