이 문서는 카카오페이 정기 결제 API 사용 방법을 안내합니다.
정기 결제는 주기적으로 여러 차례 결제가 이뤄지는 구매건에 대해 사용하며, 구독과 같이 동일 사용자의 동일 구매건에 대해 결제를 진행할 필요가 있을 때 사용합니다. 한 번의 결제로 구매가 완료된다면 단건 결제를 사용해야 합니다.
정기 결제를 하려면 가맹점마다 발급되는 코드인 CID
와 최초 정기 결제 시점에 부여되는 SID
, 이 2가지 고유번호가 필요합니다. 이 중 SID는 특정 사용자에게 2회차 이후의 정기 결제를 요청할 때 사용하는 고유번호입니다. 가맹점은 카카오페이 제휴 시 단건 결제 CID, 정기 결제용 CID를 각각 받습니다. 이 중 정기 결제용 CID를 사용해 단건 결제를 승인 완료하여 SID를 발급 받을 수 있습니다. 상품 총액(total_amount) 0원으로 단건 결제를 처리하면 SID만 발급 받을 수 있습니다.
정기 결제 진행 과정과 SID 사용 방법을 보다 간결하게 정리하면 다음과 같습니다.
정기 결제 시작(1회차)card_info
(JSON) 중 일부 필드만 제공정기 결제 시 가맹점 코드(CID)가 필요합니다. 테스트 결제는 가맹점 코드로 'TCSUBSCRIP'를 사용합니다. 실제로 결제하려면 카카오페이와 제휴를 맺어 가맹점 코드를 발급 받아야 합니다.
정기 결제를 시작하는 1회차 결제는 정기 결제용 CID를 사용한 단건 결제로 처리합니다. 1회차 정기 결제 또한 단건 결제와 마찬가지로 결제 준비, 결제 요청, 결제 승인 단계를 모두 거쳐야 합니다. 결제 준비 API 호출 시 사용할 CID가 정기 결제용이어야 한다는 점, 정기 결제용 CID를 사용한 단건 결제 승인 완료 응답은 정기 결제 2회차부터 반드시 필요한 값인 SID
를 포함한다는 점에 차이가 있습니다.
CID 값은 다르지만 단건 결제와 동일한 API를 사용하므로, 단건 결제 개발 가이드를 참고해 1회차 결제를 완료합니다.
SID 값은 정기 결제 와 정기 결제 비활성화, 정기 결제 상태 조회 시 필수 파라미터로 사용되므로 반드시 서버에 저장하여 별도 관리합니다.
curl -v -X POST "https://kapi.kakao.com/v1/payment/ready" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
--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"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"tid": "T9876543210987654321",
"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": "2020-06-18T14:35:11"
}
curl -v -X POST "https://kapi.kakao.com/v1/payment/approve" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
--data-urlencode "cid=TCSUBSCRIP" \
--data-urlencode "tid= T9876543210987654321" \
--data-urlencode "partner_order_id=subscription_order_id_1" \
--data-urlencode "partner_user_id=subscription_user_id_1" \
--data-urlencode "pg_token= xxxxxxxxxxxxxxxxxxxx"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"aid": "A7894561230789456123",
"tid": "T9876543210987654321",
"cid": "TCSUBSCRIP",
"sid": "S4561237890456123789",
"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,
"discount": 0,
"green_deposit": 0
},
"created_at": "2020-06-18T14:35:12",
"approved_at": "2020-06-18T14:46:12"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"aid": "A7894561230789456123",
"tid": "T9876543210987654321",
"cid": "TCSUBSCRIP",
"sid": "S4561237890456123789",
"partner_order_id": "subscription_order_id_1",
"partner_user_id": "subscription_user_id_1",
"payment_method_type": "CARD",
"item_name": "음악정기결제",
"quantity": 1,
"amount": {
"total": 9900,
"tax_free": 0,
"vat": 900,
"point": 0,
"discount": 0,
"green_deposit": 0
},
"card_info": {
"approved_id": "11111111",
"bin": "123456",
"card_mid": "mid",
"card_type": "신용",
"install_month": "00",
"issuer_corp": "신한카드",
"issuer_corp_code": "05",
"purchase_corp": "신한카드",
"purchase_corp_code": "05",
"interest_free_install": "N",
"kakaopay_purchase_corp": "신한",
"kakaopay_purchase_corp_code": "101",
"kakaopay_issuer_corp": "신한",
"kakaopay_issuer_corp_code": "101"
},
"created_at": "2020-06-18T14:58:34",
"approved_at": "2020-06-18T14:59:31"
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"aid": "A7894561230789456123",
"tid": "T9876543210987654321",
"cid": "TCSUBSCRIP",
"sid": "S4561237890456123789",
"partner_order_id": "subscription_order_id_1",
"partner_user_id": "subscription_user_id_1",
"payment_method_type": "CARD",
"item_name": "음악정기결제",
"quantity": 1,
"card_info": {
"bin": "123456",
"card_type": "신용",
"install_month": "00",
"kakaopay_purchase_corp": "신한",
"kakaopay_purchase_corp_code": "101",
"kakaopay_issuer_corp": "신한",
"kakaopay_issuer_corp_code": "101"
},
"created_at": "2020-06-18T15:00:03",
"approved_at": "2020-06-18T15:01:16"
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v1/payment/subscription |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
- | - | - | - |
첫 정기 결제를 통해 받은 SID로 2회차부터 결제를 요청하려면 이 API를 사용합니다.
어드민 키를 헤더에 담아 POST
로 요청합니다. 1회차 정기 결제 시 응답으로 받았던 SID를 반드시 포함해야 합니다. 정기 결제는 최초 결제 시 사용했던 결제 수단과 정보를 계속해서 쓰므로, 2회차 결제부터는 한 번의 요청으로 처리할 수 있습니다.
결제 성공 시 응답은 결제 상세 정보를 포함합니다. 정기 결제 요청이 실패한 경우, 상황에 따라 결제 수단(머니/카드)별 원천사의 실패 사유가 포함될 수 있습니다.
이름 | 설명 | 필수 |
---|---|---|
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 |
가맹점 코드 인증 키(Key), 24자 숫자+영문 소문자 조합 | X |
sid | String |
정기 결제 키, 20자 | O |
partner_order_id | String |
가맹점 주문번호, 최대 100자 | O |
partner_user_id | String |
가맹점 회원 id, 최대 100자 SID를 발급 받은 첫 결제의 결제 준비 API로 전달한 값과 일치해야 함 |
O |
item_name | String |
상품명, 최대 100자 | X |
item_code | String |
상품코드, 최대 100자 | X |
quantity | Integer |
상품 수량 | O |
total_amount | Integer |
상품 총액 | O |
tax_free_amount | Integer |
상품 비과세 금액 | O |
vat_amount | Integer |
상품 부가세 금액 기본 값: (상품총액 - 상품 비과세 금액)/11, 소수점 이하 반올림 |
X |
green_deposit | Integer |
컵 보증금 | X |
payload | String |
결제 승인 요청에 대해 저장하고 싶은 값, 최대 200자 | X |
이름 | 타입 | 설명 |
---|---|---|
aid | String |
Request 고유 번호 |
tid | String |
결제 고유 번호 |
cid | String |
가맹점 코드 |
sid | String |
정기(배치)결제 고유 번호. 20자 |
partner_order_id | String |
가맹점 주문번호 |
partner_user_id | String |
가맹점 회원 id |
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 |
결제 요청 시 전달했던 값 |
이름 | 타입 | 설명 |
---|---|---|
total | Integer |
전체 결제 금액 |
tax_free | Integer |
비과세 금액 |
vat | Integer |
부가세 금액 |
point | Integer |
포인트 금액 (적용일: 2022. 11. 17) |
discount | Integer |
할인 금액 (적용일: 2022. 11. 17) |
green_deposit | Integer |
컵 보증금 |
이름 | 타입 | 설명 |
---|---|---|
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 |
카드사 가맹점 번호 |
curl -v -X POST "https://kapi.kakao.com/v1/payment/subscription" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-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"
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,
"point": 0,
"discount": 0,
"green_deposit": 0
},
"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
{
"cid": "TCSUBSCRIP",
"aid": "A5678901234567890123",
"tid": "T1234567890123456789",
"sid": "S1234567890123456789",
"partner_user_id": "subscription_user_id_1",
"partner_order_id": "subscription_order_id_1",
"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"
}
HTTP/1.1 400 Bad Request
Content-type: application/json;charset=UTF-8
{
"code": -782,
"msg": "subscription failure!",
"extras": {
"method_result_code": "8008",
"method_result_message": "거래거절 거래금액미달"
}
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v1/payment/manage/subscription/inactive |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
- | - | - | - |
정기 결제를 중단할 때 사용하는 API입니다. 이 API는 요청 시 지정된 SID를 비활성화하여 다시 사용할 수 없도록 합니다. 앱 어드민 키를 헤더에 담아 POST
로 요청합니다. 요청이 성공하면 응답 내용은 JSON
객체로 받습니다.
이름 | 설명 | 필수 |
---|---|---|
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 |
sid | String |
정기 결제 고유번호. 20자 | O |
이름 | 타입 | 설명 |
---|---|---|
cid | String |
가맹점 코드, 10자 |
sid | String |
정기 결제 고유번호, 20자 |
status | String |
정기 결제 상태, ACTIVE(활성) 또는 INACTIVE(비활성) 중 하나 |
created_at | Datetime |
SID 발급 시각 |
last_approved_at | Datetime |
마지막 결제승인 시각 |
inactivated_at | Datetime |
정기 결제 비활성화 시각 |
curl -v -X POST "https://kapi.kakao.com/v1/payment/manage/subscription/inactive" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "cid=TCSUBSCRIP" \
-d "sid=S1234567890987654321"
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"
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v1/payment/manage/subscription/status |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
- | - | - | - |
정기 결제 고유번호인 SID의 상태 확인을 위해 호출합니다. SID 상태는 '활성화(ACITVE)'와 '비활성화(INACTIVE)' 2가지 값을 제공합니다. SID가 활성 상태여야만 다음 결제 시 사용할 수 있습니다. 정기 결제를 중단해 비활성 상태로 바뀐 SID도 상태를 조회할 수 있습니다. 앱 어드민 키를 헤더에 담아 POST
로 요청합니다.
요청 성공 시 응답은 JSON
객체로 sid
상세 정보를 포함합니다.
이름 | 설명 | 필수 |
---|---|---|
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 |
sid | String |
정기 결제 고유번호. 20자 | O |
이름 | 타입 | 설명 |
---|---|---|
available | Boolean |
사용 가능 여부 |
cid | String |
가맹점 코드, 10자 |
sid | String |
정기 결제 고유 번호, 20자 |
status | String |
정기 결제 상태, ACTIVE(활성) 또는 INACTIVE(비활성) 중 하나 |
payment_method_type | String |
결제 수단, CARD 또는 MONEY 중 하나 |
item_name | String |
상품 이름. 최대 100자 |
created_at | Datetime |
SID 발급 시각 |
last_approved_at | Datetime |
마지막 결제 승인 시각 |
inactivated_at | Datetime |
정기 결제 비활성화 시각 |
use_point_status | String |
사용자 포인트 전액사용 여부 (적용일: 2022. 11. 17)ACTIVE (활성), INACTIVE (비활성) 중 하나 |
curl -v -X POST "https://kapi.kakao.com/v1/payment/manage/subscription/status" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "cid=TCSUBSCRIP" \
-d "sid=S1234567890987654321"
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",
"use_point_status": "INACTIVE"
}
정기 결제의 결제 수단을 변경하려면 정기 결제 시작을 통해 신규 SID를 발급하여 새로운 결제 수단을 등록해야 합니다. 사용하지 않는 기존 SID는 정기 결제 비활성화를 통해 해지 처리합니다.