에스크로 상태변경 API

이 페이지에서는 에스크로 가이드의 에스크로 상태변경 API를 설명합니다.
에스크로 상태변경 API는 승인이 완료된 거래에 대해 배송시작, 즉시취소, 정산보류, 취소, 발급계좌해지 등의 상태변경을 NHN KCP 서버에 요청하는 API입니다.
구매확인이 완료된 거래는 결제수단과 처리 유형에 따라 전체취소, 부분취소, 전체환불 또는 부분환불을 요청할 수 있습니다.

결제 승인 완료

상태변경 요청

NHN KCP 상태 처리

처리 결과 응답

요약

HTTP Method

POST 방식으로 JSON Body를 전송합니다.

Content-Type

application/json; charset=utf-8 형식으로 요청합니다.

통신 보안

TLS 1.2 이상 환경에서 통신합니다.

테스트 URL

https://stg-spl.kcp.co.kr/gw/mod/v1/cancel

운영 URL

https://spl.kcp.co.kr/gw/mod/v1/cancel

정상 응답 기준

res_cd 값이 0000이면 정상 처리입니다.

상태변경 유형

요청 파라미터의 mod_type 값을 사용하여 상태변경 업무를 구분합니다.

mod_type	상태변경	설명
STE1	배송시작	상품 배송을 시작하고 택배 송장번호와 배송업체명을 등록합니다.
STE2	즉시취소	아직 배송하지 않은 거래를 즉시 취소합니다.
STE3	정산보류	반품이나 배송 후 취소를 처리하기 위해 거래대금의 정산을 보류합니다.
STE4	취소	배송이 완료된 거래를 정산보류 상태에서 취소합니다.
STE5	발급계좌해지	가상계좌 거래에 발급된 계좌를 해지합니다.
STE9	구매확인 후 상태변경	구매확인이 완료된 계좌이체 또는 가상계좌 거래의 취소나 환불을 요청합니다.

요청 정보

배송시작 Request Body 예시

{
	"site_cd": "T0000",
	"kcp_cert_info": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
	"tno": "25536002322422",
	"mod_type": "STE1",
	"mod_desc": "배송시작",
	"kcp_sign_data": "YMpoQFohW76D...24ZCBmQ0ezbCi+7D/NLWBS/luQ==",
	"deli_numb": "1234567890",
	"deli_corp": "NHN택배"
}

공통 요청 파라미터

site_cd필수string5

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

kcp_cert_info필수string가변

NHN KCP에서 발급하는 서비스 인증서입니다.
파트너관리자 인증센터에서 다운로드한 PEM 파일 내용을 직렬화하여 사용합니다.ex) kcp_cert_info: -----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

tno필수string14

NHN KCP 거래번호입니다. 승인, 조회, 취소 등 후속 처리 시 사용하므로 반드시 저장합니다.
에스크로 상태변경 요청에서는 상태를 변경할 대상 거래번호로 사용합니다.ex) tno: 25536002322422

mod_type필수string4

에스크로 상태변경 요청 유형을 구분하는 값입니다.
상태변경 유형 표에서 요청할 업무에 해당하는 코드를 선택하여 전달합니다.ex) mod_type: STE1

mod_desc필수string100

상태변경을 요청하는 사유를 입력합니다.ex) mod_desc: 배송시작

kcp_sign_data필수string가변

가맹점의 부인방지와 요청 데이터의 무결성 검증을 위한 서명데이터입니다.
site_cd + "^" + tno + "^" + mod_type 규칙으로 문자열을 생성한 뒤, 개인키를 사용하여 SHA256withRSA 방식으로 서명합니다.ex) kcp_sign_data: YMpoQFohW76D...24ZCBmQ0ezbCi+7D/NLWBS/luQ==

배송시작 추가 파라미터

mod_type: STE1을 요청하는 경우에는 다음 파라미터를 필수로 전달해야 합니다.

deli_numb필수string50

상품 배송에 사용한 택배 송장번호를 입력합니다. 자가배송인 경우에는 0000을 입력합니다.ex) deli_numb: 1234567890

deli_corp필수string25

상품을 배송하는 업체명을 입력합니다.ex) deli_corp: NHN택배

즉시취소·취소 추가 파라미터

mod_type: STE2 또는 mod_type: STE4를 요청하는 경우에는 다음 파라미터를 필수로 전달해야 합니다.

refund_account필수string20

취소 금액을 환불받을 계좌번호를 입력합니다.ex) refund_account: 12345678901234

refund_nm필수string30

환불받을 계좌의 예금주명입니다.ex) refund_nm: 홍길동

bank_code필수string4

환불받을 계좌의 은행코드입니다.ex) bank_code: BK20

구매확인 후 상태변경 추가 파라미터

mod_type: STE9를 요청하는 경우에는 처리 유형에 따라 다음 파라미터를 전달해야 합니다.

mod_desc_cd필수string4

구매확인 후 상태변경 요청에 사용하는 취소 사유 코드입니다. CA06을 고정값으로 전달합니다.ex) mod_desc_cd: CA06

sub_mod_type필수string4

구매확인 후 변경할 결제상태의 유형을 구분합니다.
전체취소는 STSC, 부분취소는 STPC, 전체환불은 STHD, 부분환불은 STPD를 사용합니다.ex) sub_mod_type: STPD

mod_sub_type필수string6

결제수단과 처리 유형을 세부적으로 구분하는 보조값입니다.
가상계좌 전체환불은 MDSC00, 계좌이체 전체취소는 MDSC03, 가상계좌 부분환불·계좌이체 부분취소·계좌이체 전체환불은 MDSC04를 사용합니다.ex) mod_sub_type: MDSC04

part_canc_ynstring1

부분취소 또는 부분환불 여부를 나타냅니다.
계좌이체 구매확인 후 부분취소나 가상계좌 구매확인 후 부분환불을 요청할 때 Y를 전달합니다.ex) part_canc_yn: Y

mod_mnynumber12

취소하거나 환불할 금액을 입력합니다.
계좌이체 부분취소·전체환불 또는 가상계좌 부분환불을 요청할 때 전달합니다.ex) mod_mny: 500

rem_mnynumber12

상태변경 요청 이후에도 취소할 수 있는 잔여 금액을 입력합니다.
계좌이체 부분취소 또는 가상계좌 부분환불을 요청할 때 전달합니다.ex) rem_mny: 500

mod_accountstring20

부분취소 또는 부분환불 금액을 받을 계좌번호를 입력합니다.
계좌이체 또는 가상계좌 거래의 부분취소·부분환불을 요청할 때 전달합니다.ex) mod_account: 12345678901234

mod_depositorstring30

부분취소 또는 부분환불 금액을 받을 계좌의 예금주명을 입력합니다.
계좌이체 또는 가상계좌 거래의 부분취소·부분환불을 요청할 때 전달합니다.ex) mod_depositor: 홍길동

mod_bankcodestring4

부분취소 또는 부분환불 금액을 받을 계좌의 은행코드를 입력합니다.
계좌이체 또는 가상계좌 거래의 부분취소·부분환불을 요청할 때 전달합니다.ex) mod_bankcode: BK20

mod_tax_mnynumber12

복합과세 거래에서 부분취소 또는 부분환불할 공급가액을 입력합니다.

mod_vat_mnynumber12

복합과세 거래에서 부분취소 또는 부분환불할 부가가치세 금액을 입력합니다.

mod_free_mnynumber12

복합과세 거래에서 부분취소 또는 부분환불할 비과세 금액을 입력합니다.

응답 정보

Response Body 예시

{
	"res_cd": "0000",
	"res_msg": "정상처리"
}

응답 파라미터

res_cdstring4

응답 코드입니다. 에스크로 상태변경 요청이 정상 처리된 경우 0000을 반환합니다.ex) res_cd: 0000

res_msgstring100

결과 메시지입니다.ex) res_msg: 정상처리