페이지 이동경로

문서>
카카오페이>
정기 결제

카카오페이

정기 결제

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

정기 결제는 주기적으로 여러 차례 결제가 이뤄지는 구매건에 대해 사용하며, 구독과 같이 동일 사용자의 동일 구매건에 대해 결제를 진행할 필요가 있을 때 사용합니다. 한 번의 결제로 구매가 완료된다면 단건 결제를 사용해야 합니다.

정기 결제 고유번호(SID) 발급하기

정기 결제를 하려면 가맹점마다 발급되는 코드인 CID와 최초 정기 결제 시점에 부여되는 SID, 이 2가지 고유번호가 필요합니다. 이 중 SID는 특정 사용자에게 2회차 이후의 정기 결제를 요청할 때 사용하는 고유번호입니다. 가맹점은 카카오페이 제휴 시 단건 결제 CID, 정기 결제용 CID를 각각 받습니다. 이 중 정기 결제용 CID를 사용해 단건 결제를 승인 완료하여 SID를 발급 받을 수 있습니다. 상품 총액(total_amount) 0원으로 단건 결제를 처리하면 SID만 발급 받을 수 있습니다.

정기 결제 진행 과정과 SID 사용 방법을 보다 간결하게 정리하면 다음과 같습니다.

정기 결제 시작(1회차)

정기 결제용 CID를 사용해 정기 결제 1회차에 해당하는 금액으로 단건 결제 진행
금액 결제 없이 SID만 발급할 경우 1회차 금액을 0원으로 단건 결제 진행
1회차 금액에 대한 단건 결제 완료 후 SID 발급 받아 서버에 저장
결제 수단 CARD, 결제 금액 0원 결제 시 결제 응답의 card_info(JSON) 중 일부 필드만 제공

정기 결제 2회차 이후

정기 결제 2회차가 이뤄져야 할 시점에 서버에 저장된 SID로 정기 결제 2회차에 해당하는 금액으로 정기 결제 요청 진행

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

정기 결제 시작하기

정기 결제를 시작하는 1회차 결제는 정기 결제용 CID를 사용한 단건 결제로 처리합니다. 1회차 정기 결제 또한 단건 결제와 마찬가지로 결제 준비, 결제 요청, 결제 승인 단계를 모두 거쳐야 합니다. 결제 준비 API 호출 시 사용할 CID가 정기 결제용이어야 한다는 점, 정기 결제용 CID를 사용한 단건 결제 승인 완료 응답은 정기 결제 2회차부터 반드시 필요한 값인 SID를 포함한다는 점에 차이가 있습니다.

CID 값은 다르지만 단건 결제와 동일한 API를 사용하므로, 단건 결제 개발 가이드를 참고해 1회차 결제를 완료합니다.

SID

SID 값은 정기 결제 와 정기 결제 비활성화, 정기 결제 상태 조회 시 필수 파라미터로 사용되므로 반드시 서버에 저장하여 별도 관리합니다.

예제: 결제 준비

요청: 정기 결제 테스트 CID를 사용해 결제 준비 API 호출

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"

응답: 정기 결제 테스트 CID를 사용한 결제 준비 API 응답

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

예제: 결제 승인

요청: 정기 결제 테스트 CID를 사용해 결제 승인 API 호출

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"

응답: 결제 수단이 MONEY일 때

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

응답: 결제 수단이 CARD일 때

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

응답: 결제 수단이 CARD일 때 0원 결제

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`	결제 요청 시 전달했던 값

amount(JSON)

이름	타입	설명
total	`Integer`	전체 결제 금액
tax_free	`Integer`	비과세 금액
vat	`Integer`	부가세 금액
point	`Integer`	포인트 금액 (적용일: 2022. 11. 17)
discount	`Integer`	할인 금액 (적용일: 2022. 11. 17)
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`	카드사 가맹점 번호

예제

요청

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"

응답: 정기 결제 성공, 결제 수단이 MONEY일 때

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

응답: 정기 결제 성공, 결제 수단이 CARD일 때

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는 정기 결제 비활성화를 통해 해지 처리합니다.

menu

시작하기

로그인

커뮤니케이션

지도/로컬

내비게이션

검색

인공지능

광고

결제

더 보기

카카오페이

정기 결제

정기 결제 고유번호(SID) 발급하기

정기 결제 시작하기

예제: 결제 준비

요청: 정기 결제 테스트 CID를 사용해 결제 준비 API 호출

응답: 정기 결제 테스트 CID를 사용한 결제 준비 API 응답

예제: 결제 승인

요청: 정기 결제 테스트 CID를 사용해 결제 승인 API 호출

응답: 결제 수단이 MONEY일 때

응답: 결제 수단이 CARD일 때

응답: 결제 수단이 CARD일 때 0원 결제

정기 결제 요청하기

기본 정보

요청

헤더

본문

응답

본문

amount(JSON)

card_info(JSON)

예제

요청

응답: 정기 결제 성공, 결제 수단이 MONEY일 때

응답: 정기 결제 성공, 결제 수단이 CARD일 때

응답: 정기 결제 실패

정기 결제 비활성화하기

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

정기 결제 상태 조회하기

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

결제 수단 변경하기

더 보기