API Reference > 에스크로 상태변경
에스크로 상태변경
에스크로 상태변경
✅ 에스크로 상태변경 용어에 대한 설명은 Guide 를, 상태변경 웹훅 데이터는 API Reference의 웹훅 메뉴를 참고해 주세요
테스트 : https://stg-spl.kcp.co.kr/gw/mod/v1/cancel
운영 : https://spl.kcp.co.kr/gw/mod/v1/cancel
Request Body 파라미터
공통 파라미터
site_cd필수PC / Mobile
길이가 5자리로 영문대문자 또는 영문대문자 + 숫자로 구성됩니다. 모든 서비스에 사용합니다.
ex) "site_cd" : "T0007"
kcp_cert_info필수PC / Mobile
NHN KCP에서 발급하는 서비스 인증서로, 모든 서비스에서 사용됩니다.
상점관리자의 인증센터에서 다운받은 pem 파일 내용을 직렬화하여 사용합니다.
ex) "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCCA9CaOpuQ==-----END CERTIFICATE-----"
kcp_sign_data필수PC / Mobile
서명데이터입니다.
NHN KCP로부터 발급받은 개인키 (PRIVATE KEY)로 SHA256withRSA 알고리즘을 사용하여 문자열을 인코딩하는 방식으로 이루어집니다.
site_cd+"^"+tno+"*"+mode_type 조합으로 생성합니다.
ex) "kcp_sign_data" : "ceCJUAwjijT7+VKVt+...P6wPmg=="
tno필수PC / Mobile
상태를 변경할 에스크로 거래건의 거래번호입니다.
ex) "tno" : "24822014611200”
mod_type필수PC / Mobile
상태변경 구분값입니다.
ex) "mod_type" : "STE1"
| 상태 | 값 |
|---|---|
| 배송시작 | STE1 |
| 즉시취소(배송 전 취소) | STE2 |
| 정산보류 | STE3 |
| 취소(배송 후 취소) | STE4 |
| 발급계좌해지 (가상계좌의 경우에만 사용) | STE5 |
| 계좌이체 구매 확인 후 취소 계좌이체 구매 확인 후 부분취소 가상계좌 구매 확인 후 환불 가상계좌 구매 확인 후 부분환불 | STE9 |
mod_ipPC / Mobile
상태변경 요청 IP입니다.
ex) "mod_ip" : "0.0.0.1"
배송 시작
{
"site_cd":"T0007",
"kcp_cert_info":"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
"kcp_sign_data":"QdwMF6y3GU1JTVk...0qH7NSq0c6BpedDZb04w==",
"tno":"20240516433552",
"mod_type":"자가배송",
"deli_corp":"0000",
}
deli_corpMobile
배송업체 명입니다.
택배사를 이용하지 않을 경우, 임의의 값으로 입력합니다.
배송시작 상태변경에서 필수값입니다.
ex) "deli_corp" : "자가배송"
deli_numbMobile
택배 송장번호 입니다.
배송시작 상태변경에서 필수값입니다. 택배사를 이용하지 않을 경우 임의의 값으로 입력합니다.
ex) "deli_numb" : "0000"
즉시 취소, 취소
{
"site_cd":"T0007",
"kcp_cert_info":"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
"kcp_sign_data":"QdwMF6y3GU1JTVk...0qH7NSq0c6BpedDZb04w==",
"tno":"20240516433552",
"mod_type":"자가배송",
"mod_desc":"단순변심",
"bank_code":"BK02", //가상계좌의 경우 사용
"refund_account":"12345612123456", //가상계좌의 경우 사용
"refund_nm":"홍길동", //가상계좌의 경우 사용
}
mod_descPC / Mobile
취소 사유입니다.
ex) "mod_desc" : "단순변심”
bank_codePC / Mobile
환불 계좌의 은행코드입니다.
즉시취소(STE2) / 취소(STE4) 요청에서 가상계좌 거래일 경우 사용합니다.
ex) "bank_code" : "BK03”
refund_accountPC / Mobile
환불 계좌번호입니다.
즉시취소(STE2) / 취소(STE4) 요청에서 가상계좌 거래일 경우 사용합니다.
ex) "refund_account" : "11025123456”
refund_nmPC / Mobile
환불 계좌의 예금주명입니다.
즉시취소(STE2) / 취소(STE4) 요청에서 가상 계좌 거래일 경우 사용합니다.
ex) "refund_nm" : "홍길동"
정산 보류
{
"site_cd":"T0007",
"kcp_cert_info":"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
"kcp_sign_data":"QdwMF6y3GU1JTVk...0qH7NSq0c6BpedDZb04w==",
"tno":"20240516433552",
"mod_type":"STE3",
}
구매확인 후 취소
{
"site_cd":"T0007",
"kcp_cert_info":"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
"kcp_sign_data":"QdwMF6y3GU1JTVk...0qH7NSq0c6BpedDZb04w==",
"tno":"20240516433552",
"mod_type":"STE9",
"mod_desc_cd":"CA06",
"sub_mod_type":"STSC",
"mod_sub_type":"MDSC03",
}
발급계좌 해지
{
"site_cd":"T0007",
"kcp_cert_info":"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
"kcp_sign_data":"QdwMF6y3GU1JTVk...0qH7NSq0c6BpedDZb04w==",
"tno":"20240516433552",
"mod_type":"STE5",
"mod_desc":"단순변심",
}
mod_desc_cdPC / Mobile
취소 사유에 대한 코드로 고정값 CA06이 사용됩니다.
ex) "mod_desc_cd" : "CA06"
sub_mod_typePC / Mobile
상태변경 유형입니다.
구매확인 후 취소, 부분 취소, 환불, 부분 환불시 사용합니다.
계좌이체 전체 취소 -STSC
계좌이체 부분 취소 -STPC
가상계좌 전체환불 - STHD
가상계좌 부분 환불 - STPD
ex) "sub_mod_type" : "STSC"
mod_sub_typePC / Mobile
구매확인 된 거래의 상태변경에 대한 추가 보조 유형입니다.
가상계좌 전체 환불 -MDSC00
계좌이체 전체 취소 -MDSC03
가상계좌 부분환불 / 계좌이체 부분 취소 - MDSC04
ex) "mod_sub_type" : "MDSC00"
part_canc_ynPC / Mobile
부분 취소 사용에 대한 파라미터입니다.
계좌이체 구매확인 후 부분 취소, 가상계좌 구매확인 후 부분 환불 요청시 전달합니다.
ex) "part_canc_yn" : "Y"
mod_mnyPC / Mobile
부분 취소 요청 금액입니다.
계좌이체 구매 확인 후 부분 취소, 가상계좌 구매 확인 후 부분 환불 요청 시 전달합니다.
ex) "mod_mny" : "500"
rem_mnyPC / Mobile
부분 취소 가능 금액입니다.
계좌이체 구매 확인 후 부분 취소, 가상계좌 구매 확인 후 부분 환불 요청 시 전달합니다.
ex) "rem_mny" : "1000"
mod_bankcodePC / Mobile
환불 계좌의 은행 코드 입니다.
가상계좌 전체환불(MDSC00)/부분환불(MDSC04)에서 사용합니다.
ex) "mod_bankcode" : "BK03"
mod_accountPC / Mobile
환불 계좌번호 입니다.
가상계좌 전체환불(MDSC00)/부분환불(MDSC04)에서 사용합니다.
ex) "mod_account" : "11025123456"
mod_depositorPC / Mobile
환불 계좌의 예금주명입니다.
가상계좌 전체환불(MDSC00)/부분환불(MDSC04)에서 사용합니다.
ex) "mod_depositor" : "홍길동"
tax_flagPC / Mobile
복합과세 거래 구분값입니다.
부분취소 및 부분환불 진행 시, 복합과세 거래 건 일 경우 사용합니다.
고정값: TG03
ex) "tax_flag" : "TG03"
mod_free_mnyPC / Mobile
부분취소, 부분환불 금액의 비과세액입니다.
mod_mny (부분취소 요청금액)의 비과세 금액을 입력합니다.
ex) "mod_free_mny" : "100"
mod_tax_mnyPC / Mobile
부분취소, 부분환불 금액의 공급가액입니다.
mod_mny 값이 500원이라면 비과세를 제외한 금액의 공급가액을 입력합니다.
ex) "mod_tax_mny" : "363"
mod_vat_mnyPC / Mobile
부분취소, 부분환불 금액의 부가세입니다.
mod_mny 값이 500원이라면 비과세를 제외한 금액의 부가세를 입력합니다.
ex) "mod_vat_mny" : "37"
Response 파라미터
{
"res_cd":"0000",
"res_msg":"정상처리",
}res_cdPC / Mobile
결과코드
정상 승인이 이루어졌을 경우 ‘0000’ 값 리턴
ex) "res_cd" : "0000"
res_msgPC / Mobile
결과메세지
ex) "res_msg" : "정상처리"