결제 화면 호출 - 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

/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	-	간편결제 하위 결제수단 코드
`appScheme`	String	256	-	결제 완료 후 가맹점 앱으로 복귀할 앱 스킴 (예: merchantapp://) : 가맹점 모바일 앱(WebView)에서 결제창을 호출하는 경우에만 전달 (모바일웹·PC 결제창 호출 시에는 전달하지 않음) : scheme:// 형식만 허용 (http, https 등 웹 스킴 불가) : 미설정 시 자동 복귀 미적용

앱 복귀 스킴(appScheme) 유의사항

자동 복귀는 현재 카카오페이·토스페이·페이코 결제에 적용됩니다.
페이코는 가맹점 앱에 PAYCO 앱 등록이 추가로 필요합니다. (iOS: LSApplicationQueriesSchemes에 payco, paycoapplogin / Android: queries에 com.nhnent.payapp) — 웹뷰(WebView) 결제 연동하기를 참고해주세요.
복귀 시 앱이 새로 실행되지 않고 기존 주문화면으로 돌아오도록 하는 가맹점 앱 설정(Android launchMode/taskAffinity 등)은 가맹점에서 처리해야 합니다.

다이렉트 전용

다이렉트 방식으로 결제창 호출하기

결제수단 선택 화면 없이 원하는 결제수단의 결제창을 바로 띄우려면 payMethod와 directView를 함께 전달하세요. 다이렉트는 신용카드뿐 아니라 모든 결제수단에서 사용할 수 있습니다.

파라미터	값	설명
`payMethod`	결제수단 코드 (`CC` 신용카드 · `IC` 계좌이체 · `MO` 휴대폰 · `VA` 가상계좌 · `SP` 간편결제)	바로 호출할 결제수단. `AL`(전체)은 선택 화면이 노출되므로 다이렉트에 사용하지 않습니다. 코드모음집 > payMethod 참고
`directView`	`true`	다이렉트 방식 사용

결제수단에 따라 함께 전달해야 하는 파라미터가 다릅니다.

결제수단	함께 전달할 파라미터	설명
신용카드 (`CC`)	`cardSelect` (필수)	바로 호출할 카드사 코드 (예: `04` 현대). 코드모음집 > cardSelect 참고
간편결제 (`SP`)	`cardSelect` (필수) `receiptType`, `receiptValue` (조건부 필수) `subPayMethod` (조건부 필수)	`cardSelect`: 바로 호출할 간편결제사 코드 (예: `X4` 카카오페이, `X7` 네이버페이). 코드모음집 > cardSelect 참고 `receiptType`·`receiptValue`: 현금영수증을 발행하는 경우 필수 (현금영수증 구분·발행 데이터). `receiptType` 코드는 코드모음집 > receiptType, 아래 다이렉트 전용 표 참고 `subPayMethod`: 네이버페이·카카오페이 등의 하위 결제수단(카드·포인트·머니)을 지정하려는 경우 필수. 코드모음집 > subPayMethod 참고
계좌이체 (`IC`)	`escrowTel` (조건부 필수)	에스크로 서비스를 이용하는 경우 필수 (에스크로 이용자 휴대폰번호). 아래 다이렉트 전용 표 참고
가상계좌 (`VA`)	가상계좌 전용 필수값	`vactNotiUrl` 등
휴대폰 (`MO`)	휴대폰 전용 필수값	`phoneItemInfo` 등

API 방식에서는 다이렉트로 열리는 결제창(카드사 인증 페이지 등)의 화면 구성(openType, width, height 등)을 고객사에서 직접 설정해야 합니다.

예시: 신용카드(현대카드) 다이렉트 호출

json

{
  "payMethod": "CC",
  "directView": true,
  "cardSelect": "04",
  "mxId": "testcorp",
  "mxIssueNo": "testcorpYYYYMMDD00001",
  "mxIssueDate": "YYYYMMDDHHMMSS",
  "orderName": "상품명",
  "amount": 1000,
  "returnUrl": "https://{your-returnUrl}",
  "callHash": "SHA256(mxId + mxIssueNo + amount + passKey)"
}

필수

조건부 필수

key	타입	최대크기	필수	기본값	설명
`directView`	Boolean	-	-	`false`	다이렉트 방식 사용여부 : 다이렉트 방식의 경우 당사 화면 없이 기관사 UI 호출
`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을 사용하여 승인 요청을 진행해야 실제 결제가 이루어집니다.