결제 화면 호출 - SDK

KPN JavaScript SDK는 가맹점 내 결제 서비스에 간단한 스크립트 추가를 통해 결제 연동이 가능합니다.

안내사항

결제서비스 UI 인코딩 방식은 UTF-8 입니다.
결제 요청 Timeout은 30분입니다.
파라미터는 별도 공지 없이 추가될 수 있습니다.

서비스 흐름

결제 흐름 요약

결제 화면 호출: SDK를 통해 KPN 결제창을 띄웁니다.
인증 완료: 사용자가 결제수단을 선택하고 인증을 완료하면, returnUrl로 결과가 전달됩니다.
승인 요청: 인증 성공 시 approvalUrl을 사용하여 승인 요청 API를 호출합니다.
결제 완료: 승인 결과에 따라 사용자에게 결과를 안내합니다.

샘플 코드

html

<!doctype html>
<html>
<head></head>
<body>
<button id="payBtn" type="button" value="결제 테스트" />

<script src="{EndPoint URL}/js/firstpay_v2.js"></script>
<script>
  document.querySelector("#payBtn").addEventListener("click", function () {
      // SDK 생성자 호출(SDK Parameter 참고)
      let pay = new FirstPay({
          env: "develop",
          openType: "popup",
          onFailure: (error) => {
              console.error(`[${error.code}] ${error.message}`);
              alert(`요청 실패: ${error.message}`);
          }
      });

      // 결제페이지 호출(Payment Parameter 참고)
      pay.goPay({
          mxId: "testcorp",
          mxIssueNo: "YYYYMMDD00001",
          mxIssueDate: "YYYYMMDDHHMMSS",
          orderName: "테스트",
          amount: 1000,
          returnUrl: "https://testReturnUrl.co.kr",
          callHash: SHA256("testcorpYYYYMMDD0000110006aMoJujE34XnL9gvUqdKGMqs9GzYaNo6")
      });
  });
</script>
</body>
</html>

결제 금액 주의

1,004원은 당사 정책에 따라 매입 처리되지 않으며, 매입 취소도 불가능합니다. 운영환경에서 테스트하실 경우 1,004원 이외의 금액을 사용해 주세요.

요청 파라미터

SDK 파라미터

필수

조건부 필수

key	타입	필수	기본값	설명
	String	-	`develop`	호출 환경 설정
	String	-	`popup`	결제페이지 호출 방식 (popup, layer, submit)
`closeWindowOnly`	Boolean	-	`false`	닫기 클릭 시, 창만 닫기 여부. false: returnUrl로 이동, true: 창 닫기
`onFailure`	Function	-	-	SDK 방식에서 결제 서비스 호출 실패 시 실행되는 콜백 함수

결제 파라미터

공통

필수

조건부 필수

key	타입	최대크기	필수	기본값	설명
	String	2	-	-	결제종류. 단일 결제수단만 노출 시 사용
`mxId`	String	12		-	가맹점 ID
`mxIssueNo`	String	32		-	주문번호 (유니크한 값 권장)
`mxIssueDate`	String	14		-	주문일시 (YYYYMMDDHHMMSS)
`orderName`	String	256		-	상품명
`amount`	Number	-		-	결제금액
`taxAmount`	Number	-	-	-	과세결제금액
`taxFreeAmount`	Number	-	-	-	면세결제금액
`custName`	String	64	-	-	주문자 명
`email`	String	64	-	-	주문자 이메일주소
`phoneNo`	String	32	-	-	주문자 휴대폰번호 ('-' 제거)
`returnUrl`	String	256		-	인증 결과 수신 URL
`mallApReserved`	String	1024	-	-	가맹점필드 (인증 완료 후 리턴)
	String	20	-	`ko`	사용언어구분
`callHash`	String	-		-	체크용 해시 데이터 : SHA256(mxId + mxIssueNo + amount + passKey)
`payMethodView`	Boolean	-	-	`true`	결제수단 표시 여부
`simplepayView`	Boolean	-	-	`true`	간편결제 결제수단 표시 여부
`emailView`	Boolean	-	-	`true`	이메일 입력 필드 표시 여부
`escrowView`	Boolean	-	-	`true`	에스크로 표시 여부
`supportDateView`	Boolean	-	-	`false`	제공기간 표시 여부
`supportDate`	String	256	-	`별도제공기간없음`	제공기간 노출 텍스트

신용카드 전용

필수

조건부 필수

key	타입	최대크기	필수	설명
	String	10	-	비인증 방식 결제
	String	256		카드사 코드 (':' 구분자로 여러 카드사 노출 가능)
`cardInstallment`	String	2	-	카드할부개월

가상계좌 전용

필수

조건부 필수

key	타입	최대크기	필수	설명
`expireDate`	String	14	-	가상계좌 만료일시 (YYYYMMDDHHMMSS)
`vactNotiUrl`	String	256		가상계좌 통보 URL (가상계좌 사용 시 필수)

개발계에서 가상계좌 입금 통보 테스트를 하시려면 별도의 API로 테스트가 가능합니다.

휴대폰 전용

필수

조건부 필수

key	타입	최대크기	필수	설명
	String	1		휴대폰 결제 유형 (휴대폰결제 사용 시 필수)

현금영수증 전용

필수

조건부 필수

key	타입	최대크기	필수	기본값	설명
	String	1	-	`Y`	현금영수증 플래그

간편결제 전용

필수

조건부 필수

key	타입	최대크기	필수	설명
	String	10	-	간편결제 하위 결제수단 코드

다이렉트 전용

필수

조건부 필수

key	타입	최대크기	필수	기본값	설명
`directView`	Boolean	-	-	`false`	다이렉트 방식 사용여부
`escrowTel`	String	32		-	에스크로 이용자 휴대폰번호
	String	1		`2`	현금영수증 구분
`receiptValue`	String	20		-	현금영수증 발행 데이터

네이버페이 다이렉트 호출 시 유의사항

네이버페이는 iframe을 지원하지 않아, openType: 'layer'로 설정해도 자동으로 popup으로 열립니다.

응답 파라미터

KPN 결제창에서 완료한 경우, returnUrl에 설정된 곳으로 응답 데이터(Form Submit)가 전달됩니다.

필수

조건부 필수

key	타입	최대크기	필수	설명
`mxId`	String	12		가맹점 ID
`mxIssueNo`	String	32		주문번호
`mxIssueDate`	String	14		주문일시
`amount`	String	12		결제금액
`mallApReserved`	String	1024	-	가맹점필드
`code`	String	4		에러코드 (성공: 0000)
`message`	String	-	-	에러메세지 (실패인 경우 리턴)
`fdTid`	String	18	-	KPN 인증 거래번호 (성공인 경우 리턴)
`approvalUrl`	String	-	-	승인 요청 URL (성공인 경우 리턴)

다음 단계

응답 파라미터의 code가 0000(성공)인 경우, approvalUrl을 사용하여 승인 요청을 진행해야 합니다.