빌키 발급

01거래등록 API

빌키 발급을 위해 요청정보를 등록하고 결제창 페이지 URL을 응답으로 받을 수 있습니다.
HTTP POST 방식으로 호출하시기 바랍니다.

요청

URL 정보

테스트	https://testpgapi.easypay.co.kr/api/ep9/trades/webpay
운영	https://pgapi.easypay.co.kr/api/ep9/trades/webpay

파라미터

필드명	타입	최대크기	필수여부	설명
mallId	String	8 Byte	필수	KICC에서 부여한 상점ID
mallName	String	40 Byte		결제창에 표시할 가맹점 명 빈값일 경우 원장정보로 표시
returnUrl	String	256 Byte	필수	인증 완료 후 이동할 URL
clientTypeCode	String	2 Byte	필수	결제창 구분코드(통합형 : 00)
deviceTypeCode	String	20 Byte	필수	결제고객 단말구분 PC버전 : "pc", 모바일버전 : "mobile"
langFlag	String	3 Byte		언어 선택(결제창 표기 언어) 빈값일 경우 한국어 표기 한국어 : "KOR", 영어 : "ENG", 중국어 : "CHN", 일본어 : "JPN"
payMethodTypeCode	String	2 Byte	필수	빌키 발급 시 "81"로 고정
shopOrderNo	String	40 Byte	필수	상점 주문번호 반드시 Unique 값으로 생성
currency	String	2 Byte	필수	통화코드(원화 : "00")
amount	Number		필수	결제요청 금액 0원으로 호출바람
orderInfo	Object		필수	결제 주문정보 {orderInfo} 참조
payMethodInfo	Object			결제수단 관리정보 {payMethodInfo}참조
shopValueInfo	Object			가맹점 필드 인증응답으로 전송됨 {shopValueInfo}참조

orderInfo(결제 주문정보)

필드명	타입	최대크기	필수여부	설명
goodsName	String	50 Byte	필수	상품명
customerInfo	Object			주문 고객정보 {customerInfo}참조

customerInfo(주문 고객정보)

필드명	타입	최대크기	설명
customerId	String	20 Byte	고객 ID
customerName	String	20 Byte	고객 명
customerMail	String	50 Byte	고객 Email
customerContactNo	String	11 Byte	고객 연락처(숫자만 허용)

payMethodInfo(결제수단 관리정보)

필드명	타입	최대크기	필수여부	설명
billKeyMethodInfo	Object		필수	빌키 설정 정보 {billKeyMethodInfo} 참조

billKeyMethodInfo(빌키 설정정보)

필드명	타입	최대크기	필수여부	설명
certType	String	1 Byte	필수	신용카드인증타입 참조

shopValueInfo(가맹점 필드)

필드명	타입	최대크기	설명
value1	String	64 Byte	필드1
value2	String	64 Byte	필드2
value3	String	32 Byte	필드3
value4	String	32 Byte	필드4
value5	String	64 Byte	필드5
value6	String	64 Byte	필드6
value7	String	64 Byte	필드7

요청 예

{

"mallId": "T0001997",

"payMethodTypeCode": "81",

"currency": "00",

"amount": 0,

"clientTypeCode": "00",

"returnUrl": "https://sample.easypay.co.kr/res.jsp",

"deviceTypeCode": "mobile",

"shopOrderNo": "20210326085908",

"orderInfo": {

"goodsName": "예시 상품명"

"payMethodInfo" : {

"biilMethodInfo": {

"certType": "0"

}

응답

Body

필드명	타입	최대크기	필수여부	설명
resCd	String	4 Byte	필수	결과코드(정상 : "0000")
resMsg	String	100 Byte	필수	결과 메시지
authPageUrl	String	256 Byte		결제창 호출 URL

응답 예

{

resCd: 0000,

resMsg: 정상처리,

authPageUrl: "https://testsp.easypay.co.kr/webpay/ReqAction.do?authorizationId=1231234"

}

02빌링 결제창 호출

빌키를 발급받기 위한 결제창을 호출하여 고객의 신용카드 정보를 수집합니다.
HTTP GET 방식으로 호출하시기 바랍니다.
인증완료 후 결제등록 시 받은 returnUrl로 인증완료에 대한 응답을 POST로 전송합니다.

요청

URL 정보

URL	authPageUrl(결제창 호출 URL)

응답

필드명	타입	최대크기	필수여부	설명
resCd	String	4 Byte	필수	결과코드(정상 : "0000")
resMsg	String	100 Byte	필수	결과 메시지
shopOrderNo	String	40 Byte		상점 주문번호 결제등록 요청 시 전달받은 값
authorizationId	String	60 Byte		인증 거래번호 빌키 발급요청 시 필수 값
shopValue1	String	64 Byte		필드1, 결제등록 요청 시 전달받은 값
shopValue2	String	64 Byte		필드2, 결제등록 요청 시 전달받은 값
shopValue3	String	32 Byte		필드3, 결제등록 요청 시 전달받은 값
shopValue4	String	32 Byte		필드4, 결제등록 요청 시 전달받은 값
shopValue5	String	64 Byte		필드5, 결제등록 요청 시 전달받은 값
shopValue6	String	64 Byte		필드6, 결제등록 요청 시 전달받은 값
shopValue7	String	64 Byte		필드7, 결제등록 요청 시 전달받은 값

03빌키 발급 API

결제창으로부터 받은 인증값으로 빌키 발급 요청하는 API 입니다.
HTTP POST 방식으로 호출하시기 바랍니다.

요청

URL 정보

테스트	https://testpgapi.easypay.co.kr/api/ep9/trades/approval
운영	https://pgapi.easypay.co.kr/api/ep9/trades/approval

파라미터

필드명	타입	최대크기	필수여부	설명
mallId	String	8 Byte	필수	KICC에서 부여한 상점ID
shopTransactionId	String	60 Byte	필수	가맹점 트랜젝션ID 중복요청을 방지를 위해 일별로 Unique 보장
authorizationId	String	60 Byte	필수	인증 거래번호 결제창 호출 후 받은 값 그대로 사용
shopOrderNo	String	40 Byte	필수	상점 주문번호 결제등록 시 요청한 값 그대로 사용
approvalReqDate	String	8 Byte	필수	승인요청일자(yyyyMMdd)

요청 예

{

"mallId": "T0001997",

"shopTransactionId": "20210326090126",

"authorizationId" : "21032609005210816913",

"shopOrderNo": "20210326090046",

"approvalReqDate" : "20210326"

}

응답

Body

필드명	타입	최대크기	필수여부	설명
resCd	String	4 Byte	필수	결과코드
resMsg	String	100 Byte	필수	결과 메시지
mallId	String	8 Byte	필수	KICC에서 부여한 상점ID
shopTransactionId	String	60 Byte	필수	가맹점 트랜젝션ID 중복요청을 방지를 위해 일별로 Unique 보장
shopOrderNo	String	40 Byte		상점 주문번호 결제등록 시 요청한 값 그대로 사용
pgCno	String	20 Byte		PG 승인거래번호
amount	Number			총 결제금액
transactionDate	String	14 Byte		거래일시(yyyyMMddHHmmss)
statusCode	String	4 Byte		거래상태 코드(거래상태 코드표 참조)
statusMessage	String	50 Byte		거래상태 메시지(거래상태 코드표 참조)
msgAuthValue	String	200 Byte		각주 1) 메시지 인증값 응답값의 무결성을 검증할 때 사용 Secret Key는 영업담당자에게 문의
paymentInfo	Object			결제수단별 승인결과 {paymentInfo}참조

각주 1)

메시지 인증값 구성은 PG승인거래번호, 결제금액, 거래일시로 아래와 같이 조합하고 해당값을 HmacSHA256으로 해시한다.(HmacSHA256 해시함수 참조)
pgCno(PG승인거래번호) + “|” + amount(결제금액) + “|” + transactioDate(거래일시)

paymentInfo(결제수단별 승인결과)

필드명	타입	최대크기	필수여부	설명
payMethodTypeCode	String	2 Byte	필수	신용카드: 11
approvalNo	String	50 Byte	필수	결제수단 승인번호
approvalDate	String	14 Byte	필수	결제수단의 승인일시 yyyyMMddHHmmss
cardInfo	Object			신용카드 결제결과 정보 {cardInfo}참조

cardInfo(신용카드 결제결과)

필드명	타입	최대크기	필수여부	설명
cardNo	String	20 Byte	필수	빌키(승인요청 시 필수)
issuerCode	String	3 Byte	필수	발급사 코드
issuerName	String	50 Byte	필수	발급사 명
acquirerCode	String	3 Byte	필수	매입사 코드
acquirerName	String	50 Byte	필수	매입사 명
cardGubun	String	1 Byte	필수	카드종류 신용("N"), 체크("Y"), 기프트("G")
cardBizGubun	String	1 Byte	필수	카드 주체 개인("P"), 법인("C"), 기타("N")
partCancelUsed	String	1 Byte		부분취소 가능여부(Y/N)
subCardCd	String	3 Byte		BC제휴사 카드코드 빌키 발급 시 응답
cardMaskNo	String	40Byte		마스킹된 카드번호

응답 예

{

"resCd": "0000",

"resMsg": "단독인증 정상",

"mallId": "T0001997",

"pgCno": "21032609005610816914",

"shopTransactionId": "20210326090126",

"shopOrderNo": "20210326090046",

"amount": "51004",

"transactionDate": "20210326090200",

"msgAuthValue": "e06540df5ac28ac877fb4f063d06d5f9c3ee2a3a8820a888bfc8db1577a7fe",

"paymentInfo": {

"payMethodTypeCode": "11",

"approvalNo": "00017177",

"approvalDate": "20210326090200",

"cardInfo": {

"cardNo": "T00019971100BA007681",

"cardMaskNo": "546465******0001",

"issuerCode": "029",

"issuerName": "OK:00017177",

"acquirerCode": "029",

"acquirerName": "Payzone TestCard",

"cardGubun": "N",

"cardBizGubun": "P",

"partCancelUsed": "Y"

}