페이지 이동경로
  • 문서>
  • 카카오페이>
  • 정기 결제

카카오페이

정기 결제

이 문서는 카카오페이 정기결제 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) 중 일부 필드만 제공 (2020년 7월 27일 적용 예정)
정기결제 2회차 이후
  • 정기결제 2회차가 이뤄져야 할 시점에 서버에 저장된 SID로 정기결제 2회차에 해당하는 금액으로 정기 결제 요청 진행

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

정기 결제 시작

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

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

SID

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

Sample: 결제 준비
Request: 정기 결제 테스트 CID를 사용해 결제 준비 API 호출
curl -v -X POST "https://kapi.kakao.com/v1/payment/ready" \
-H "Authorization: KakaoAK {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"
Response: 정기 결제 테스트 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"
  }
Sample: 결제 승인
Request: 정기 결제 테스트 CID를 사용해 결제 승인 API 호출
curl -v -X POST "https://kapi.kakao.com/v1/payment/approve" \
-H "Authorization: KakaoAK {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"
Response: 결제 수단이 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
    },
  "created_at":"2020-06-18T14:35:12",
  "approved_at":"2020-06-18T14:46:12"
}
Response: 결제 수단이 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
    },
  "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"
}
Response: 결제 수단이 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"
}

정기 결제 요청

첫 정기 결제를 통해 받은 SID로 2회차부터 결제를 요청하려면 이 API를 사용합니다.

어드민 키를 헤더에 담아 POST로 요청합니다. 1회차 정기 결제 시 응답으로 받았던 SID를 반드시 포함해야 합니다. 정기 결제는 최초 결제 시 사용했던 결제 수단과 정보를 계속해서 쓰므로, 2회차 결제부터는 한 번의 요청으로 처리할 수 있습니다.

결제 성공 시 응답은 결제 상세 정보를 포함합니다. 정기결제 요청이 실패한 경우, 상황에 따라 결제 수단(머니/카드)별 원천사의 실패 사유가 포함될 수 있습니다.

Request
URL
POST /v1/payment/subscription HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Parameter
Name Type Description Required
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
payload String 결제 승인 요청에 대해 저장하고 싶은 값, 최대 200자 X
Response
Key
Name Type Description
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
Name Type Description
total Integer 전체 결제 금액
tax_free Integer 비과세 금액
vat Integer 부가세 금액
card_info
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 카드사 가맹점 번호
Sample
Request
curl -v -X POST "https://kapi.kakao.com/v1/payment/subscription" \
-H "Authorization: KakaoAK {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"
Response: 정기 결제 성공, 결제 수단이 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
 },
 "created_at": "2016-11-17T16:02:19",
 "approved_at": "2016-11-17T16:02:20"
}
Response: 정기 결제 성공, 결제 수단이 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,
  "discount": 0,
  "point": 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"
}
Response: 정기 결제 실패
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": "거래거절 거래금액미달"
 }
}

정기 결제 비활성화

정기 결제를 중단할 때 사용하는 API입니다. 이 API는 요청 시 지정된 SID를 비활성화하여 다시 사용할 수 없도록 합니다. 앱 어드민 키를 헤더에 담아 POST로 요청합니다. 요청이 성공하면 응답 내용은 JSON 객체로 받습니다.

Request
URL
POST /v1/payment/manage/subscription/inactive HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Parameter
Name Type Description Required
cid String 가맹점 코드, 10자 O
cid_secret String 가맹점 코드 인증 키, 24자, 숫자+영문 소문자 조합 X
sid String 정기 결제 고유번호. 20자 O
Response
Key
Name Type Description
cid String 가맹점 코드, 10자
sid String 정기 결제 고유번호, 20자
status String 정기 결제 상태, ACTIVE(활성) 또는 INACTIVE(비활성) 중 하나
created_at Datetime SID 발급 시각
last_approved_at Datetime 마지막 결제승인 시각
inactivated_at Datetime 정기결제 비활성화 시각
Sample
Request
curl -v -X POST "https://kapi.kakao.com/v1/payment/manage/subscription/inactive" \
-H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
-d "cid=TCSUBSCRIP" \
-d "sid=S1234567890987654321"
Response
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"
}

정기 결제 상태 조회

정기 결제 고유번호인 SID의 상태 확인을 위해 호출합니다. SID 상태는 '활성화(ACITVE)'와 '비활성화(INACTIVE)' 2가지 값을 제공합니다. SID가 활성 상태여야만 다음 결제 시 사용할 수 있습니다. 정기 결제를 중단해 비활성 상태로 바뀐 SID도 상태를 조회할 수 있습니다. 앱 어드민 키를 헤더에 담아 POST로 요청합니다.

요청 성공 시 응답은 JSON 객체로 sid 상세 정보를 포함합니다.

Request
URL
POST /v1/payment/manage/subscription/status HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Parameter
Name Type Description Required
cid String 가맹점 코드, 10자 O
cid_secret String 가맹점 코드 인증키, 24자, 숫자+영문 소문자 조합 X
sid String 정기 결제 고유번호. 20자 O
Response
Key
Name Type Description
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 정기결제 비활성화 시각
Sample
Request
curl -v -X POST "https://kapi.kakao.com/v1/payment/manage/subscription/status" \
-H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
-d "cid=TCSUBSCRIP" \
-d "sid=S1234567890987654321"
Response
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를 발급하여 새로운 결제 수단을 등록해야 합니다. 사용하지 않는 기존 SID는 정기 결제 비활성화를 통해 해지 처리합니다.

더보기