결제 화면 호출 - API

해당 API를 호출하면 응답으로 결제창 호출 URL이 반환됩니다. 해당 URL을 사용자 브라우저에서 직접 호출하거나 리디렉션하여 결제창을 연동할 수 있습니다.

안내사항

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

주의사항

API 방식의 경우 SDK 방식과 달리 당사에서 화면 요소를 관리하지 않으며, 전달받은 URL을 기반으로 고객사에 직접 openType, width, height 등의 화면 구성을 설정하실 수 있습니다.
또한 API 방식에서 directView 옵션을 사용하시는 경우, 카드사 인증 페이지 역시 당사에서 관리하지 않기 때문에 고객사에서 구성해주셔야 합니다.

서비스 흐름

결제 흐름 요약

결제 URL 요청: API를 호출하여 결제창 URL(forwardUrl)을 받습니다.
결제 화면 호출: 받은 URL로 사용자를 리디렉션하여 결제창을 띄웁니다.
인증 완료: 사용자가 결제수단을 선택하고 인증을 완료하면, returnUrl로 결과가 전달됩니다.
승인 요청: 인증 성공 시 approvalUrl을 사용하여 승인 요청 API를 호출합니다.
결제 완료: 승인 결과에 따라 사용자에게 결과를 안내합니다.

결제 금액 주의

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

요청 파라미터

POST

/api/v1/payments_url

Base URLhttps://dev.firstpay.co.kr

Content-Typeapplication/json

공통

필수

조건부 필수

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을 지원하지 않아, layer 방식으로 호출해도 자동으로 popup으로 열립니다.

요청 예시

json

{
  "payMethod": "CC",
  "mxId": "testcorp",
  "mxIssueNo": "testcorpYYYYMMDD00001",
  "mxIssueDate": "YYYYMMDDHHMMSS",
  "orderName": "상품명",
  "amount": 1000,
  "custName": "퍼스트",
  "email": "testpg@kpn.co.kr",
  "phoneNo": "01012345678",
  "returnUrl": "https://{your-returnUrl}",
  "callHash": "SHA256(mxId + mxIssueNo + amount + passKey)",
  "lang": "ko"
}

응답 파라미터

API 응답은 서비스 API 공통 형식을 따릅니다. data 필드 상세는 아래와 같습니다.

필수

조건부 필수

key	타입	최대크기	필수	설명
`forwardUrl`	String	-		PC 결제창 호출 URL
`forwardMUrl`	String	-		모바일 결제창 호출 URL

다음 단계

응답받은 forwardUrl 또는 forwardMUrl로 리디렉션하여 결제창을 호출합니다.
결제창 호출 후 returnUrl로 응답값이 나가게 됩니다.

returnUrl로 인증 완료 응답받기

전달 파라미터

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

POST

가맹점 도메인/{returnUrl}

Base URL가맹점 도메인

Content-Typeapplication/x-www-form-urlencoded

필수

조건부 필수

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을 사용하여 승인 요청을 진행해야 실제 결제가 이루어집니다.