API Reference > 자동결제

빌링키 발급

본인확인 및 카드 정보 등록을 정상적으로 진행한 뒤, 인증 값으로 빌링키를 발급 받을 수 있습니다.

테스트 : https://stg-spl.kcp.co.kr/gw/enc/v1/payment 
운영 : https://spl.kcp.co.kr/gw/enc/v1/payment

Header

Protocol: HTTPS
HTTP Method: POST
Content-Type: application/json; charset=UTF-8

Request Body 파라미터


{
 "tran_cd":"00300001",
 "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCCAmmgAwIBAgIHkiG9w0…==-----END CERTIFICATE-----",
 "site_cd":"A52Q7",
 "enc_data":"SnvXdGftIEjAequorkpNhJXc4hfghdfs5dfsgu3GRuotLHW9vyDDOhdeorM4DPXMJgJlIEoRo6divo=",
 "enc_info":"3dsgjljlsSEGHsdccndsgnfdSDDhhbdrhffRbdfRYHFgfgnb=_"
}

string5

site_cd필수PC / Mobile

길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다. 모든 서비스에 사용합니다.
ex) "site_cd" : "A52Q7"

string가변

kcp_cert_info필수PC / Mobile

NHN KCP 에서 발급하는 서비스 인증서로, 상점관리자의 인증센터에서 다운받은 pem 파일내용을 직렬화 하여 사용합니다.
모든 서비스에 사용합니다.
ex) "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCCAmmgAwIBAgIHkiG9w0…………Cay7pJNWXCnw4jIiBsTBa3q95RVRyMEcDgPwugMXPXGBwNoMOOpuQ==-----END CERTIFICATE-----"

string가변

enc_data필수PC / Mobile

결제창 인증결과 암호화 정보
통합 결제 창으로부터 전달 받는 인증결과 암호화 데이터
※ 절대 임의로 변경 불가하며 결제 창에서 내려 주는 값을 그대로 사용 부탁 드립니다.
ex) "enc_data" : "1eOSNbDDMQCVqCHVNZGNPKZErG2lCPBL24RTDIATPEXWERwBkrN4ghC4M0ue81I8y-LZ1tl6q8CMpw-LvpFdQDKzbHx5tx1OYWBf”

string가변

enc_info필수PC / Mobile

결제창 인증결과 암호화 정보
통합 결제 창으로부터 전달 받는 인증결과 암호화 데이터
※ 절대 임의로 변경 불가하며 결제 창에서 내려 주는 값을 그대로 사용 부탁 드립니다.
ex) "enc_info" : "4dgxMICIupJdwMheYKVQI.Vd6cKDpBSSkWfEfW1k431UaMlGzuVl1N.NIsrbdDnQ5i9Mu.JVz.C7JIK1NpdfDkdYd”

string8

tran_cd필수PC / Mobile

요청코드(수정불가)
ex) "tran_cd" : "00300001"

Response 파라미터

빌링키 발급 요청이 정상 처리 되었을 경우 res_cd : 0000 과 함께 빌링키 정보가 리턴됩니다.
빌링키는 별도 조회할 수 있는 기능이 없으니 발급된 빌링키는 관리에 유의해주시기 바랍니다.


{
 "res_cd":"0000",
 "res_msg":"정상처리",
 "card_name":"삼성카드",
 "batch_key" : "24010124040463F4",
 "card_cd":"CCSS",
 "card_bin_type_01":"0",
 "card_bin_type_02":"0"
}

string4

res_cdPC / Mobile

결과코드
정상 승인이 이루어졌을 경우 ‘0000’ 값 리턴
ex) "res_cd" : "0000"

string100

res_msgPC / Mobile

결과메세지
ex) "res_msg" : "정상처리"

string16

batch_keyPC / Mobile

빌링키이며, 카드인증 후 결과로 내려드리는 카드정보를 암호화한 값입니다.
빌링키를 가맹점에서 저장해 두었다가, 결제 주기에 맞춰 해당 값으로 승인요청을 합니다.
ex) "batch_key" : "240508240394617F"

string4

card_cdPC / Mobile

발급된 빌링키의 카드사 코드입니다.
ex) "card_cd" : "CCNH"

string20

card_namePC / Mobile

발급된 빌링키의 카드사명입니다.
ex) "card_name" : "NH카드"

string1

card_bin_type_01PC / Mobile

발급된 빌링키의 카드 구분 정보입니다.
개인 : 0 / 법인 : 1
ex) "card_bin_type_01" : "0"

string1

card_bin_type_02PC / Mobile

발급된 빌링키의 카드 구분 정보입니다.
일반 : 0 / 체크 : 1
ex) "card_bin_type_02" : "0"

빌링키 승인

주문정보와 발급받은 빌링키로 결제 주기에 맞춰 결제 요청을 합니다.
결제 요청의 bt_group_id는 빌링키 발급단계에서 사용한 그룹아이디와 동일한 값을 사용해 주세요.
결제 요청 시 초당 2~3회 이하로 결제 요청 바랍니다.

테스트 : https://stg-spl.kcp.co.kr/gw/hub/v1/payment 
운영 : https://spl.kcp.co.kr/gw/hub/v1/payment

Header

Protocol: HTTPS
HTTP Method: POST
Content-Type: application/json; charset=UTF-8

Request Body 파라미터


{
 "site_cd":"A52Q7",
 "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCC…-----END CERTIFICATE-----",
 "pay_method":"CARD",
 "amount":"1000",
 "card_mny":"1000",
 "quota":"00",
 "currency":"410",
 "ordr_idxx":"TEST123456789",
 "good_name":"운동화",
 "good_cd":"00",
 "buyr_name":"홍길동",
 "card_tx_type":"11511000",
 "bt_batch_key":"24010124040463F4",
 "bt_group_id":"A52Q71000489"
}

string5

site_cd필수PC / Mobile

길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다. 모든 서비스에 사용합니다.
ex) "site_cd" : "A52Q7"

string가변

kcp_cert_info필수PC / Mobile

string4

pay_method필수PC / Mobile

결제수단입니다. 고정값입니다.
ex) "pay_method" : "CARD"

number12

amount필수PC / Mobile

총 결제 금액입니다.
ex) "amount" : "1000"

number12

card_mny필수PC / Mobile

카드 결제 금액입니다.
ex) "card_mny" : "1000"

string3

currency필수PC / Mobile

화폐단위입니다.
ex) "currency " : "410"

string2

quota필수PC / Mobile

할부개월수 입니다. 고정값 일시불입니다.
ex) "quota" : "00"

string50

ordr_idxx필수Mobile

상점에서 관리하는 주문번호입니다. 최대길이는 40자이며, 중복되지 않는 유니크한 값으로 사용하시길 권장합니다.
주문 데이터 관리를 위해 가맹점에서 반드시 저장해야합니다.
ex) "ordr_idxx" : "TEST123456789"

string8

card_tx_type필수PC / Mobile

결제전문 구분값이며, 자동결제 승인요청의 경우 11511000(고정)입니다.
ex) "card_tx_type" : "11511000"

string12

bt_group_id필수PC / Mobile

자동결제 그룹 아이디이며, 빌링키 발급 및 승인 시 그룹별로 관리할 수 있습니다.
ex) "bt_group_id" : "A52Q71000489"

string16

bt_batch_key필수PC / Mobile

빌링키이며, 카드인증 후 결과로 내려드리는 카드정보를 암호화한 값입니다.
빌링키를 가맹점에서 저장해 두었다가, 필요할 때 해당 값으로 승인요청을 합니다.
ex) "bt_batch_key" : "240508240394617F"

string4

media_type필수PC / Mobile

매체 구분입니다.
PC=MC01, 모바일=MC02
ex) "media_type" : "MC01"

string100

good_name필수PC / Mobile

상품명입니다. 최대길이는 100자입니다.
ex) "good_name" : "운동화"

string40

buyr_namePC / Mobile

주문자이름
ex) "buyr_name" : "홍길동"

string100

buyr_mailPC / Mobile

주문자 이메일
입력하신 E-Mail 주소로 결제 결과 메일이 발송됩니다.

string20

buyr_tel2PC / Mobile

주문자 휴대폰번호
하이폰(-)포함 가능
ex) "buyr_tel2" : "010-1234-1234"

Response 파라미터


//신용카드 응답 데이터 예시
{
 "res_cd":"0000",
 "res_msg":"정상처리",
 "pay_method":"PACA",
 "order_no":"TEST123456789",
 "amount":"1000",
 "card_mny":"1000",
 "coupon_mny":"0",
 "card_no":"4673090000000032",
 "quota":"00",
 "tno":"24346915432487",
 "card_cd":"CCKM",
 "card_name":"국민카드",
 "app_no":"78710726"
}

string4

res_cdPC / Mobile

결과코드
정상 승인이 이루어졌을 경우 ‘0000’ 값 리턴
ex) "res_cd" : "0000"

string100

res_msgPC / Mobile

결과메세지
ex) "res_msg" : "정상처리"

string100

res_en_msgPC / Mobile

영문 결과 메시지
ex) "res_en_msg" : "processing completed"

string4

pay_methodPC / Mobile

응답결제수단
신용카드 - PACA
ex) "pay_method" : "PACA"

string14

tnoPC / Mobile

NHN KCP 거래 고유번호
※ 거래고유번호 전체로 사용 하시기 바랍니다. (임의의 숫자나 파싱하여 사용 불가)
ex) "tno" : "24123456789012"

number12

amountPC / Mobile

결제 금액
결제 건의 총 결제 금액이 리턴 됩니다.
최종 결제 금액의 처리는 승인완료 후 리턴 데이터 중 amount 로 처리하여야 하며 반드시 업체의 DB금액과 비교하여 검증하시기 바랍니다.
ex) "amount" : "1000"

string4

card_cdPC / Mobile

결제 건의 발급 사 코드
ex) "card_cd" : "CCNH"

number12

card_mnyPC / Mobile

결제 건의 총 결제금액 중 신용카드 결제금액
ex) "card_mny" : "8000"

string32

card_namePC / Mobile

결제 건의 발급 사 명
ex) "card_name" : "NH카드"

string16

card_noPC / Mobile

결제 건의 카드번호 (카드번호 16자리 중 3번째구간은 마스킹)
ex) "card_no" : "9441160000001234"

string8

app_noPC / Mobile

결제 건의 승인번호
ex) "app_no" : "46761234"

string14

app_timePC / Mobile

결제 건의 결제(승인) 시간
ex) "app_time" : "20260101235959"

string1

noinfPC / Mobile

결제 건의 무이자 여부
ex) "noinf" : "Y"

string2

quotaPC / Mobile

결제 건의 할부 기간
ex) 일시불일 경우, "quota" : "00"

string4

acqu_cdPC / Mobile

결제 건의 매입사 코드입니다.
ex) "acqu_cd" : "CCAM"

string20

acqu_namePC / Mobile

결제 건의 매입사명입니다.
ex) "acqu_name" : "롯데아멕스카드"

string1

partcanc_ynPC / Mobile

결제 건의 부분취소 가능 유무
ex) "partcanc_yn" : "Y"

string1

card_bin_type_01PC / Mobile

결제 건의 카드 구분 정보
개인 : 0 / 법인 : 1
ex) "card_bin_type_01" : "0"

string1

card_bin_type_02PC / Mobile

결제 건의 카드 구분 정보
일반 : 0 / 체크 : 1
ex) "card_bin_type_02" : "0"

빌링키 삭제

구독을 중지하거나 신용카드 변경 등으로 기존의 빌링키(빌링키)를 사용하지 않을 경우, 삭제할 수 있습니다.
삭제 요청 후 정상 처리 되었을 경우, res_cd : 0000이 리턴됩니다.

테스트 : https://stg-spl.kcp.co.kr/gw/hub/v1/payment 
운영 : https://spl.kcp.co.kr/gw/hub/v1/payment

Header

Protocol: HTTPS
HTTP Method: POST
Content-Type: application/json; charset=UTF-8

Request Body 파라미터


{
 "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCCAmmgAwIBAg..-----END CERTIFICATE-----",
 "site_cd":"A52Q7",
 "pay_method":"BATCH",
 "tx_type":"10005010",
 "group_id":"A52Q71000489",
 "batch_key":"24010124040463F4"
}

string5

site_cd필수PC / Mobile

길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다. 모든 서비스에 사용합니다.
ex) "site_cd" : "A52Q7"

string가변

kcp_cert_info필수 PC / Mobile

NHN KCP 에서 발급하는 서비스 인증서로, 상점관리자의 인증센터에서 다운받은 pem 파일내용을 직렬화 하여 사용합니다.
모든 서비스에 사용합니다.
ex) "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDjDCCAnSgAwIBAgIK8gGsiPI-----END CERTIFICATE-----"

string5

pay_method필수PC / Mobile

결제수단으로 빌링키 삭제의 경우 BATCH(고정)입니다.
ex) "pay_method" : "BATCH"

string8

tx_typePC / Mobile

요청 타입입니다. 10005010 의 고정값을 사용합니다.
ex) "tx_type" : "10005010”

string12

group_idPC / Mobile

자동결제 그룹 아이디이며, 빌링키 발급 및 승인 시 그룹별로 관리할 수 있습니다.
ex) "group_id" : "A52Q71000489"

string16

batch_keyPC / Mobile

빌링키이며, 카드인증 후 결과로 내려드리는 카드정보를 암호화한 값입니다.
ex) "batch_key" : "240508240394617F"

빌링키 발급

빌링키 발급

Header

Request Body 파라미터

Response 파라미터

빌링키 승인

빌링키 승인

Header

Request Body 파라미터

Response 파라미터

빌링키 삭제

빌링키 삭제

Header

Request Body 파라미터

문서 목차