Guide > 에스크로
에스크로
에스크로
에스크로 서비스 이용하기
NHN KCP 에스크로(Escrow)는 온라인 거래에서 NHN KCP가 결제 대금을 보관한 후,
고객이 상품을 정상적으로 수령했음을 확인하면
가맹점에 대금을 지급하는 서비스입니다.
가맹점과 고객 간의 상품 배송, 교환, 환불 과정에서 발생할 수 있는 약속 불이행으로 인한 거래 사고를 예방하기 위해,
NHN KCP가 거래 대금의 입·출금을 공정하게 관리하는 안전한 거래 보호 장치입니다.
에스크로 서비스는 표준 결제 서비스 연동 방식에 에스크로 파라미터를 추가하여 구현합니다.
본 가이드에서는 거래 등록, 결제창 호출, 결제 응답, 상태 변경 및 Webhook에서 사용되는 에스크로 추가 파라미터를 안내합니다.
에스크로 서비스는 현금성 결제 수단인 계좌이체 및 가상계좌 결제에서 제공됩니다.
✅ 에스크로 서비스에 대한 API 및 파라미터는 API Reference 를 확인해 주세요.
에스크로 관련 법률
"에스크로 서비스는 전자상거래 등에서의 소비자 보호에 관련 법률(이하 '전자상거래법')에 따라 2006년 4월 1일부터 시행되었으며, 2013년 11월 29일부터 에스크로 서비스가 거래금액 제한 없이 소비자가 선택하여 진행 할 수 있도록 변경되었습니다. 에스크로 서비스 의무 적용이 면제 되는 거래는 '신용카드로 재화 등의 대금을 지급하는 거래' , '정보통신망으로 전송되거나 에스크로 사업자가 배송을 확인할 수 없는 재화 등을 구매하는 거래' 등으로 자세한 사항은 전자상거래법 24조 3항을 참조 바랍니다."에스크로 서비스 프로세스
에스크로를 통한 결제 건은 결제가 이루어지면 프로세스가 끝나는 일반 결제 건과는 달리, 결제, 주문, 배송을 모두 관리해야 해요.
NHN KCP 에스크로에서 관리해야 할 업무는 배송시작, 정산보류, 즉시취소, 취소, 발급계좌해지(가상계좌), 구매확인 후 취소가 있습니다.
해당 업무에 대한 관리는 NHN KCP 파트너관리자에서 수행 가능하며, 각각 업무에 대한 상세 용어는 아래와 같아요.
배송시작
결제가 승인완료 되면 상품을 고객에게 배송하고, 배송 시작으로 에스크로 건을 상태 변경합니다.
배송 시작 단계에서는 택배사명과 운송장 번호를 입력하며, 자체 배송일 경우 자가배송으로 처리합니다.
✅ 배송시작을 반드시 해주셔야 NHN KCP로부터 정산을 받을 수 있습니다.
즉시취소
배송정보 입력 전에 고객이 구매취소를 요청한 경우, 가맹점에서 즉시 취소를 요청하면 바로 취소처리가 돼요.
정산보류
고객이 배송안내 메일에서 반품요청을 한 경우 또는 배송된 상품을 고객의 요청으로 취소해야 할 경우, 정산보류 후 취소를 진행해요.
취소
배송 중 또는 배송 완료 후에 고객이 구매취소를 요청한 경우, 정산보류 상태에서 고객에게 상품을 돌려받은 후 취소 요청하면 정상적으로 거래취소가 완료돼요.
발급계좌해지
가상계좌의 경우에만 해당하며, 발급된 가상계좌 해지를 진행해요.
구매확인 후 취소
구매확인이 된 건에 대해 에스크로 상태 변경으로 취소를 진행해요.
✅ 구매 확인 후 환불 기능은 NHN KCP와 별도 계약이 필요하니 자세한 사항은 NHN KCP로 문의해 주세요.
배송완료 후 구매확인까지 완료한다면, 정상적으로 거래가 완료된 것으로 확인하여
구매확인일로부터 2일 후에 정산대금이 입금돼요.
만약 고객이 배송일로부터 5일 내에 구매확인을 완료하지 않을 경우는
정상적으로 물품을 수령한 것으로 간주하여, 고객에게 자동구매확인을 통보하고 2일 후에 정산대금이 입금됩니다.
1. 서비스 인증서 적용하기
서비스 인증서는 가맹점 인증과 부인 방지를 위해 API 결제 서비스에서 사용돼요.
NHN KCP는 가맹점이 전달한 서비스 인증서 정보를 검증하고, 해당 결제 요청에 대한 결과를 응답합니다.
✅ 서비스 인증서에 대한 자세한 내용은 API Reference의 KCP PG-API를 확인해 주세요.
2. Mobile 거래등록 하기
모바일 버전에서는 결제 요청할 데이터 중 주문 및 결제 정보를 미리 NHN KCP 결제 서버에 등록하는 거래 등록이 필수입니다.
데이터 검증을 위해 결제 요청 전, 가맹점의 주문 요청 데이터를 서버에 저장해 주세요.
필수 주문 정보인 ordr_idxx, good_mny, pay_method, Ret_URL 파라미터의 값은 반드시 가맹점 서버에 저장하여 사용해 주세요.
🔗 거래등록 API Reference 바로가기
3. 장바구니 설정하기
에스크로 서비스 이용 시, 고객 결제 완료 후 가맹점이 상품 배송 시작을 등록하면
결제창에 입력된 고객의 이메일 주소로 에스크로 배송 안내 메일이 발송됩니다.
해당 메일에는 상품명, 수량, 가격 정보가 포함되며,
이 정보는 가맹점이 결제창 호출 시 전달한 장바구니 상품 정보 파라미터 값을 기준으로 표시됩니다.
📍장바구니 상품 정보 파라미터
good_info는 상품 정보를 seq(상품개수 일련번호)로 카운트 하여 상품 하나의 항목은 RECORD SEPARATOR(char(30)),
각각의 상품 구분은 UNIT SEPARATOR(chr(31))으로 구분합니다.
생성한 good_info는 order_info(주문데이터)에 저장하여 결제창으로 전달합니다.
function create_goodInfo()
{
var chr30 = String.fromCharCode(30); //ASCII 코드값 30
var chr31 = String.fromCharCode(31); //ASCII 코드값 31
var good_info = "seq=1" + chr31 + "ordr_numb=20060310_0001" + chr31 + "good_name=양말" + chr31 + "good_cntx=2" + chr31 + "good_amtx=1000" + chr30+
"seq=2" + chr31 + "ordr_numb=20060310_0002" + chr31 + "good_name=신발" + chr31 + "good_cntx=1" + chr31 + "good_amtx=1500" +chr30+
"seq=3" + chr31 + "ordr_numb=20060310_0003" + chr31 + "good_name=바지" + + chr31 + "good_cntx=1" + chr31 + "good_amtx=1000";
document.order+info.good_info.value = good_info;
v_frm.submit();
}
장바구니 개수
good_info에 생성된 상품정보 개수를 bask_cntx 파라미터로 전달합니다.
ex) seq가 3이라면 bask_cntx도 3이 됩니다.
{
"bask_cntx" : "3"
}4. 결제창 호출하기
Mobile 결제창 호출
모바일 결제창의 경우, 거래등록 응답에서 리턴된 PayUrl(결제창 호출 주소)로 order_info을 전달하여 결제창을 띄웁니다.
✅ 거래 등록의 데이터와 order_info 데이터가 다를 경우 결제창에서 오류를 리턴합니다.
✅ PayUrl은 리턴된 그대로 사용해주세요.
{
"site_cd:" : "T0007",
"pay_method" : "BANK",
"currency" : "410",
"shop_name" : "KCP SHOP",
"Ret_URL" : "https://쇼핑몰주문처리서버/../return",
"approval_key" : "J9z6rqeRrRIjGoxmPPQtpgcHyKIPdQ/iE35VBPEo1sQ=",
"PayUrl" : "https://testsmpay.kcp.co.kr/pay/mobileGW.kcp",
"ordr_idxx" : "TEST123456789",
"good_name" : "휴대폰",
"good_mny" : "1000",
"buyr_name" : "홍길동",
"buyr_tel2" : "010-1234-1234",
"quotaopt" : "12",
"escw_used":"Y",
"pay_mod":"Y",
"deli_term":"02",
"bask_cntx":"3",
"good_info":"seq=1order_numb=0001good_name=양말good_cntx=2good_amtx=1000seq=2order_numb=0001good_name=양말
good_cntx=2good_amtx=100seq=3order_numb=0001good_name=양말good_cntx=2good_amtx=100",
"rcvr_name":"홍길동",
"rcvr_tel1":"02-1234-1234",
"rcvr_tel2":"010-1234-1234",
"rcvr_mail":"수취인메일",
"rcvr_zipx":"157864",
"rcvr_add1":"서울시 구로구 구로동",
"rcvr_add2":"A아파트 101동 101호"
}
PC 결제창 호출
{
"site_cd:" : "T0007",
"site_name" : "TEST SITE",
"pay_method" : "010000000000",
"ordr_idxx" : "TEST123456789",
"good_name" : "운동화",
"good_mny" : "1000",
"escw_used":"Y",
"pay_mod":"Y",
"deli_term":"02",
"bask_cntx":"3",
"good_info":"seq=1order_numb=0001good_name=양말good_cntx=2good_amtx=1000seq=2order_numb=0001good_name=양말
good_cntx=2good_amtx=100seq=3order_numb=0001good_name=양말good_cntx=2good_amtx=100",
"rcvr_name":"홍길동",
"rcvr_tel1":"02-1234-1234",
"rcvr_tel2":"010-1234-1234",
"rcvr_mail":"수취인메일",
"rcvr_zipx":"157864",
"rcvr_add1":"서울시 구로구 구로동",
"rcvr_add2":"A아파트 101동 101호"
}
결제창 호출 파라미터
site_cd필수PC / Mobile
길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다.
모든 서비스에 사용합니다.
ex) "site_cd" : "T0000"
pay_method필수PC / Mobile
MOBILE 결제수단 코드 값 입니다. (4 Byte)
신용카드 : CARD
계좌이체 : BANK
휴대폰 : MOBX
포인트 : TPNT
상품권 : GIFT
ex) "pay_method" : "CARD"
PC 결제수단 코드 값 입니다. (12 Byte)
신용카드 : 100000000000
계좌이체 : 010000000000
포인트 : 000100000000
휴대폰 : 000010000000
상품권 : 000000001000
ex) "pay_method" : "100000000000"
PayUrl필수Mobile
결제창 호출 주소.
거래등록에서 전달받은 그대로 사용해주세요
ex) TEST일 경우, "PayUrl" : "https://testsmpay.kcp.co.kr/pay/mobileGW.kcp"
approval_key필수Mobile
거래 인증 키
(거래등록 후 리턴받은 approvalKey 값을 셋팅해주세요. )
ex) "approval_key" : "ockLyC3QHxD5rSUio3ETuAcHyKIPdQiE35VBPEo1cQ="
Ret_URL필수Mobile
리다이렉트 URL
인증결과를 리턴받을 가맹점의 URL
ex) "Ret_URL" : "https://쇼핑몰주문처리서버/../return"
AppUrlMobile
외부 앱에서 가맹점 앱으로 돌아오기 위해 사용하는 URL
앱 연동시 필수이며, 가맹점 앱을 초기화 하는 주소가 아닌 결제창을 호출한 웹뷰가 유지되는 주소를 사용해주세요.
https 값이 아닌 '앱스킴명://' 형식으로 입력합니다.
ex) "AppUrl" : "myapp://"
ordr_idxx필수PC / Mobile
상점에서 관리하는 주문번호입니다. 중복되지 않는 유니크한 값으로 사용하시길 권장합니다.
주문 데이터 관리를 위해 가맹점에서 반드시 저장해야합니다.
ex) "ordr_idxx" : "TEST123456789"
good_mny필수PC / Mobile
결제 금액입니다.
ex) "good_mny" : "1000"
good_name필수PC / Mobile
상품명입니다. 최대길이는 100자입니다.
ex) "good_name" : "운동화"
good_cdPC / Mobile
상품코드
주문상품명으로 구분이 어려운 경우 상품군을 따로 구분하여 처리할 수 있는 기능
ex) "good_cd" : "00"
currency필수PC / Mobile
화폐단위
※ Mobile 원화 - 410 / 달러 - 840
※ PC 원화 - WON / 달러 - USD
ex) 모바일의 경우, "currency" : "410"
shop_user_id필수PC / Mobile
휴대폰, 상품권 결제시 필수 파라미터입니다.
쇼핑몰에서 관리하는 회원 ID
※ 유니크한 값으로 입력
기관에 따라 리스크 관리 조치를 위한 쇼핑몰 관리 ID를 필수로 요청
ex) "shop_user_id" : "hong123"
buyr_namePC / Mobile
주문자이름
ex) "buyr_name" : "홍길동"
buyr_mailPC / Mobile
주문자 이메일
입력하신 E-Mail 주소로 결제 결과 메일이 발송됩니다.
buyr_tel2PC / Mobile
주문자 휴대폰번호
하이폰(-)포함 가능
ex) "buyr_tel2" : "010-1234-1234"
shop_nameMobile
사이트명
ex) "shop_name" : "NHN KCP SHOP"
site_namePC
상점이름(영문으로 작성권장)
ex) "site_name" : "NHN KCP"
van_code필수Mobile
상품권, 포인트 결제시 필수 파라미터입니다.
도서문화 상품권 - SCBL
컬쳐랜드 상품권 - SCCL
베네피아 복지 포인트 - SCWB
OK캐쉬백 - SCSK
ex) "van_code" : "SCBL"
param_opt_1 Mobile
NHN KCP 기본 파라미터 외 업체 추가 파라미터입니다. (opt_1, opt_2, opt_3 세개까지 가능합니다.)
ex) "param_opt_1" : "test"
escw_used필수PC / Mobile
에스크로 사용 여부 입니다.
ex) "escw_used":"Y"
pay_mod필수PC / Mobile
에스크로 결제 처리 여부입니다.
escw_used를 Y 로 넘겼어도 pay_mod를 N 으로 넘기면 일반결제로 처리됩니다.
에스크로 결제 처리 : Y , 일반 결제처리 : N
ex) "pay_mod" : "Y"
deli_term필수PC / Mobile
예상되는 배송 소요일입니다.
3일이 예상될 경우 3이라고 입력합니다. 숫자 2자리로 사용됩니다.
ex) "deli_term" : "3"
rcvr_namePC / Mobile
수취인 명입니다.
ex) "rcvr_name" : "김케이"
rcvr_tel1PC / Mobile
수취인 전화번호입니다.
ex) "rcvr_tel1" : "02-1234-1234"
rcvr_tel2PC / Mobile
수취인 휴대폰 번호입니다.
ex) "rcvr_tel2" : "010-1234-1234"
rcvr_mailPC / Mobile
수취인 이메일 주소입니다.
ex) "rcvr_mail" : "이메일주소"
rcvr_zipxPC / Mobile
수취인 우편 번호입니다.
ex) "rcvr_zipx" : "01853"
rcvr_add1PC / Mobile
수취인 주소입니다.
ex) "rcvr_add1" : "서울시 구로구 구로동"
rcvr_add2PC / Mobile
수취인 상세주소입니다.
ex) "rcvr_add2" : "0번지 1층"
bask_cntxPC / Mobile
장바구니에 담긴 상품 개수입니다.
good_info 값에 담긴 상품 개수와 동일하게 입력합니다. 예를 들어 seq가 3개일 경우 3으로 입력합니다.
최대 허용 개수는 40개 입니다.
ex) "bask_cntx" : "3"
good_infoPC / Mobile
장바구니의 상품 정보 입니다.
한 상품에 대한 주문 번호, 이름, 수량 금액 항목을 입력합니다.
ex) "good_info" :
"seq=1" + chr31 + "ordr_numb=TEST123456789" + chr31+ "good_name=양말" + chr31 + "good_cntx=2" + chr31 + "good_amtx=1000" + chr30 +
"seq=2" + chr31 + "ordr_numb=TEST123456789" + chr31+ "good_name=신발" + chr31 + "good_cntx=1" + chr31 + "good_amtx=1500" + chr30 +
"seq=3" + chr31 + "ordr_numb=TEST123456789" + chr31+ "good_name=바지" + chr31 + "good_cntx=1" + chr31 + "good_amtx=1000";
| 항목 명 | 상품 정보 | 길이 |
|---|---|---|
| seq | 상품개수 일련번호 | 2 |
| ordr_numb | 상품 주문번호 | 40 |
| good_name | 상품 이름 | 30 |
| good_cntx | 상품 수량 | 2 |
| good_amtx | 상품 금액 | 12 |
5. 결제창 인증결과
📍결제창 인증 주요 파라미터
enc_info, enc_data 는 인증정보를 암호화한 값으로, 리턴된 그대로 결제요청 하시기 바랍니다.
{
"res_cd":"0000",
"res_msg":"정상처리",
"tran_cd":"00100000",
"enc_data":"SnvXdGftIEjAe...JlIEoRo6divo=",
"enc_info":"3dsgjljlsSE...RYHFgfgnb=_",
}
Mobile 결제창 인증 결과
결제창 인증이 완료되면 최초 거래등록에서 넘긴 파라미터에 대한 결과가 Ret_URL로 전달됩니다. 결제창에서 리턴된 데이터는 form 형식의 pay_form으로 전달되며, PayUrl로 보낸 결제요청 데이터와 Ret_URL 로 돌아온 데이터가 동일한지 확인해 보실 수 있습니다.
PC 결제창 인증 결과
PC 버전은 m_Completepayment 콜백 함수를 통해 enc_info, enc_data 가 리턴됩니다.
결제창 인증 결과 파라미터
res_cdPC / Mobile
결과코드
인증 정상인 경우 '0000'값 리턴
ex) "res_cd" : "0000"
res_msgPC / Mobile
결과메세지
ex) "res_msg" : "정상처리"
site_cdMobile
길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다.
모든 서비스에 사용합니다.
ex) "site_cd" : "T0000"
enc_dataPC / Mobile
결제창 인증결과 암호화 정보
통합 결제 창으로부터 전달 받는 인증결과 암호화 데이터
※ 절대 임의로 변경 불가하며 결제 창에서 내려 주는 값을 그대로 사용 부탁 드립니다.
ex) "enc_data" : "1eOSNbDDMQCVqCHVNZGNPKZErG2lCPBL24RTDIATPEXWERwBkrN4ghC4M0ue81I8y-LZ1tl6q8CMpw-LvpFdQDKzbHx5tx1OYWBf"
enc_infoPC / Mobile
결제창 인증결과 암호화 정보
통합 결제 창으로부터 전달 받는 인증결과 암호화 데이터
※ 절대 임의로 변경 불가하며 결제 창에서 내려 주는 값을 그대로 사용 부탁 드립니다.
ex) "enc_info” : "4dgxMICIupJdwMheYKVQI.Vd6cKDpBSSkWfEfW1k431UaMlGzuVl1N.NIsrbdDnQ5i9Mu.JVz.C7JIK1NpdfDkdYd"
tran_cdPC / Mobile
요청코드(수정불가)
ex) "tran_cd" : "00100000"
6. 결제 승인 요청
전달받은 인증 결과 데이터(enc_data, enc_info 등)를 API 통신으로 결제 승인 요청하는 단계입니다.
승인요청 데이터는 NHN KCP가 제공하는 API URL로 json string 형태로 전송해 주세요.
단, 승인 요청 전에 결제창으로부터 받은 인증결과 데이터와 승인 요청하는 데이터가 일치하는지 검증하기 위해 실제 결제금액인 ordr_mony, ordr_no, pay_type을 서버 통신으로 넘겨주세요.
결제창에서 처리된 정보와 서버단으로 요청하는 정보가 일치하지 않으면 승인이 거절될 수 있으니,
결제정보 검증기능 적용을 참고 바랍니다.
✅ 결제정보 검증 기능 참고사항바로가기
📍결제창 승인요청 필수 파라미터
{
"res_cd":"0000",
"kcp_cert_info":"-----BEGIN CERTIFICATE-----MII...puQ==-----END CERTIFICATE-----",
"tran_cd":"00100000",
"enc_data":"SnvXdGftIEjAe...JlIEoRo6divo=",
"enc_info":"3dsgjljlsSE...RYHFgfgnb=_",
"ordr_mony":"1000",'
"pay_type":"PACA",
"ordr_no":"TEST123456789",
}
결제창 승인 요청 파라미터
site_cd필수PC / Mobile
길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다.
모든 서비스에 사용합니다.
ex) "site_cd" : "T0000"
kcp_cert_info필수PC / Mobile
NHN KCP 에서 발급하는 서비스 인증서로, 상점관리자의 인증센터에서 다운받은 pem 파일내용을 직렬화 하여 사용합니다.
모든 서비스에 사용합니다.
ex) "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCCAmmgAwIBAgIHkiG9w0…………Cay7pJNWXCnw4jIiBsTBa3q95RVRyMEcDgPwugMXPXGBwNoMOOpuQ==-----END CERTIFICATE-----"
enc_data필수PC / Mobile
결제창 인증결과 암호화 정보
통합 결제 창으로부터 전달 받는 인증결과 암호화 데이터
※ 절대 임의로 변경 불가하며 결제 창에서 내려 주는 값을 그대로 사용 부탁 드립니다.
ex) "enc_data" : "1eOSNbDDMQCVqCHVNZGNPKZErG2lCPBL24RTDIATPEXWERwBkrN4ghC4M0ue81I8y-LZ1tl6q8CMpw-LvpFdQDKzbHx5tx1OYWBf"
enc_info필수PC / Mobile
결제창 인증결과 암호화 정보
통합 결제 창으로부터 전달 받는 인증결과 암호화 데이터
※ 절대 임의로 변경 불가하며 결제 창에서 내려 주는 값을 그대로 사용 부탁 드립니다.
ex) "enc_info" : "4dgxMICIupJdwMheYKVQI.Vd6cKDpBSSkWfEfW1k431UaMlGzuVl1N.NIsrbdDnQ5i9Mu.JVz.C7JIK1NpdfDkdYd"
tran_cd필수PC / Mobile
요청코드(수정불가)
ex) "tran_cd" : "00100000"
ordr_mony필수PC / Mobile
실제 결제 요청 금액(결제금액 유효성 검증)
ex) "ordr_mony" : "1000"
ordr_no필수PC / Mobile
실제 결제 주문번호
ex) "ordr_no" : "TEST123456789"
pay_type필수PC / Mobile
실제 결제수단(결제수단 유효성 검증)
가맹점 서버에 저장된 결제수단에 값을 입력해주세요.
신용카드 : PACA
계좌이체 : PABK
휴 대 폰 : PAMC
포 인 트 : PAPT
상 품 권 : PATK
ex) "pay_type" : "PACA"
7. 결제 승인응답
결제 승인에 성공하면 res_cd : 0000 과 함께 결제수단별 응답 데이터가 리턴되며 에스크로 거래건은
에스크로 파라미터 escw_yn가 추가로 전달됩니다.
✅ 결제 승인 응답 및 에스크로 상태변경에 대한 API 및 파라미터는 API Reference 를 확인해 주세요.
8. 웹훅
에스크로 거래 건의 상태가 변경되면, 가맹점에 등록된 Webhook URL로 상태 변경에 대한 알림(Notification)을 전송합니다.
해당 통보 서비스는 다음 업무에 대해 제공됩니다.
✅ 웹훅에 대한 상세 설명은 Guide 웹훅을 확인해 주세요.