결제연동

결제 요청 페이지 작성

특징

UDID는 사용자의 PC등에 별도의 모듈 설치(Non-ActiveX)없이 사용 가능합니다.
SHA256을 통한 위변조 방지와 HTTPS(SSL) 통신을 이용하여 보안이 한층 더 강화된 전자지불 시스템을 제공합니다.
사용자의 PC 환경에 따라 자동으로 웹표준 결제창을 표시하며, ActiveX 등의 추가적인 설치없이 Chrome, IE, Firefox, Safari 브라우저에서 사용할 수 있습니다.
(단, 카드사 등 금융기관에서 요구하는 경우에 사용자는 해당 모듈을 설치하여 결제를 이용해야 합니다.)
시스템 언어에 관계없이 HTTPS 통신만을 사용하여 쉽게 연동하여 사용할 수 있습니다.

결제 요청 데이터

form 데이터 처리가 필요한 경우 페이지 표시전에 별도로 DB 또는 세션 등에 저장해 두시기 바랍니다.
발급받은 가맹점 Key를 merchantKey로 지정합니다.
웹 표준 결제 이용시 패스워드 기능을 하는 코드로 MID 번호별로 부여됩니다.

가맹점 Key 발급방법

https://mms.lightpay.kr 가맹점 관리자 로그인 > “가맹점정보 > 결제환경 설정 > KEY관리” 에서 확인 가능합니다.
가맹점 Key는 외부에 노출되지 않도록 주의합니다.

Input에 결제 요청 데이터 생성

Input tag에 name 설정(결제요청 스크립트 실행시 사용됨)
필드명 대소문자 구분
일부 가맹점에서 필요에 의해 사용자가 변경하는 경우를 제외하고 모두 type=”hidden”을 사용



<div id="sampleInput">
    <input type="hidden" name="mid" value="demotest0m"/>
    <input type="hidden" name="goodsAmt" value="1004"/>
     ......
</div>

UDID는 Form Post 로 결제 요청되며, form 태그에 action 속성 설정 / submit 등의 모든 동작은 Import 된 스크립트에 의해서 자동 처리됩니다.

방화벽

라이트페이에 대한 통신이 가능하도록 방화벽 설정이 필요합니다.

연결대상	URL
개발	https://testpaywin.lightpay.kr	https://testmms.lightpay.kr
운영	https://paywin.lightpay.kr	https://mms.lightpay.kr

프로토콜	HTTPS
연결방향	INBOUND, OUTBOUND
포트	443

암호화

암호화 구성

파라미터	hashString
암호화 방식	Hex(Sha256)

코드샘플

                                    
public void encryption(){
    String mid = "test00001m";  //상점 아이디
    String ediDate = "20210325183601";  //전문 요청 일시(yyyyMMddHHmmss 형식)
    String goodsAmt = "1004";  //결제 금액
    String merchantKey = "wEvQ8ZzgGpuEhujNx6++HCOO5XJKhhHJmP5q8UAYsr6j8zL0wIMKdbVmruWKMx0GgBbZwIkx3PUstbe3g1UZAQ==";  //가맹점KEY
    String hashString = encoding(mid+ediDate+goodsAmt+merchantKey);
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}



                                

                                    
public void encryption(){
    String mid = "test00001m";  //상점 아이디
    String ediDate = "20210325183601";  //전문 요청 일시(yyyyMMddHHmmss 형식)
    String goodsAmt = "0";  //'0' 고정
    String merchantKey = "wEvQ8ZzgGpuEhujNx6++HCOO5XJKhhHJmP5q8UAYsr6j8zL0wIMKdbVmruWKMx0GgBbZwIkx3PUstbe3g1UZAQ==";  //가맹점KEY
    String hashString = encoding(mid+ediDate+goodsAmt+merchantKey);
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
public void encryption(){
    String mid = "test00001m";  //상점 아이디
    String ediDate = "20210325183601";  //전문 요청 일시(yyyyMMddHHmmss 형식)
    String ccAmt = "1004";  //취소 금액
    String merchantKey = "wEvQ8ZzgGpuEhujNx6++HCOO5XJKhhHJmP5q8UAYsr6j8zL0wIMKdbVmruWKMx0GgBbZwIkx3PUstbe3g1UZAQ==";  //가맹점KEY
    String hashString = encoding(mid + ediDate + ccAmt + merchantKey);
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
public void encryption(){
    String mid = "test00001m";  //상점 아이디
    String ediDate = "20210325183601";  //전문 요청 일시(yyyyMMddHHmmss 형식)
    String bid = "test00001mcb002102151652573903";  //빌키 아이디
    String merchantKey = "wEvQ8ZzgGpuEhujNx6++HCOO5XJKhhHJmP5q8UAYsr6j8zL0wIMKdbVmruWKMx0GgBbZwIkx3PUstbe3g1UZAQ==";  //가맹점KEY
    String hashString = encoding(mid + ediDate + bid + merchantKey);
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
public void encryption(){
    String mid = "test00001m";  //상점 아이디
    String ediDate = "20210325183601";  //전문 요청 일시(yyyyMMddHHmmss 형식)
    String merchantKey = "wEvQ8ZzgGpuEhujNx6++HCOO5XJKhhHJmP5q8UAYsr6j8zL0wIMKdbVmruWKMx0GgBbZwIkx3PUstbe3g1UZAQ==";  //가맹점KEY
    String hashString = encoding(mid + ediDate + merchantKey);
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
public void encryption(){
    String mid = "test00001m";  //상점 아이디
    String rid = "b7c491c0";  //결제 요청 아이디
    String merchantKey = "wEvQ8ZzgGpuEhujNx6++HCOO5XJKhhHJmP5q8UAYsr6j8zL0wIMKdbVmruWKMx0GgBbZwIkx3PUstbe3g1UZAQ==";  //가맹점KEY
    String hashString = encoding(mid + rid + merchantKey);
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

가맹점연동가이드

개요

본 문서는 UDID의 지불결제 서비스를 이용하는 가맹점이 가맹점의 web 페이지에서 UDID와 결제 연동을 통해 UDID의 결제 서비스를 가맹점의 사용자에게 제공하는 방법을 제공합니다.

과정

서비스 구조와 결제 처리 (신용카드)

가맹점에서 SHA256을 이용하여 위변조 방지를 포함한 결제데이터를 생성합니다.
결제페이지에서 form 데이터를 UDID API 로 HTTPS(SSL) Post 액션을 발생시켜 결제요청 데이터로 보냅니다.
UDID는 결제요청을 받아 사용자의 디바이스에 따른 결제창을 표시하고 사용자가 결제(인증)를 진행할 수 있도록 합니다.
인증이 완료되면 리턴된 인증결과를 가맹점이 받아 결제 승인 요청을 합니다.
승인이 완료되면 리턴된 승인결과를 가맹점에 표시합니다.

설치

요구사항

하드웨어 요구사항 : 특별한 하드웨어 요구사항은 없습니다.
Web server : SHA256 암호화값의 생성 / httpClient(http Background) 통신이 가능한 웹서버
DBMS : UDID에서는 결제 결과 DATA를 제공해 드리며 DB처리는 가맹점에서 관리하셔야 합니다. 이러한 경우에는 별도의 DBMS가 필요합니다.

샘플코드

샘플코드는 가맹점의 환경에 맞도록 수정하여 사용할 수 있습니다.
UDID API 는 표준 웹 통신만을 사용합니다.
결제요청 시에는 페이지이동(Form POST Action), API 통신시에는 httpClient 통신을 이용합니다.
HTTPS API Request(httpClient 통신)= httpClient 등의 http Background 통신이 가능한 유틸을 통해서 웹페이지를 요청후 그 결과를 수신합니다.

결제 요청

결제 요청 URL

운영	https://paywin.lightpay.kr/payment/v1/view/request
개발	https://testpaywin.lightpay.kr/payment/v1/view/request

결제 요청 정보

Protocol	HTTP/1.1
Method	POST
Encoding	UTF-8
Content-type	application/x-www-form-urlencoded;

결제 기본 요청데이터 필드

필드명	한글 명칭	설명	필수 여부	최대 크기
payMethod	결제 방법	ALL: 모두(전체) CARD: 신용카드 VACNT: 가상계좌 KAKAOPAY: 카카오페이 NPAY: 네이버페이 SMILEPAY: 스마일페이 TRANS: 계좌이체 MOBILE: 휴대폰 MYACCOUNT: 내통장결제 PAYCO : 페이코 TOSSPAY : 토스페이	Y	10
payType	결제 유형	payMethod=CARD 일 경우 적용 AUTH: 인증 결제(default) KEYIN: 수기 결제(구인증) BILL: 빌링등록 NONE: 수기 결제(비인증) APPLEPAY: 애플페이		N/A
mid	상점 아이디	상점 아이디	Y	21
goodsNm	상품명	상품 이름	Y	100
ordNo	주문 번호	주문번호 Unique한 값	Y	40
goodsAmt	결제 금액	숫자만 입력 가능	Y	15
ordNm	구매자명	한글/특수기호 입력가능	Y	30
ordTel	구매자 전화번호	숫자만 허용 ※결제수단 [ MOBILE : 휴대폰 ] 일 경우, 휴대폰번호 필수		20
ordEmail	구매자 Email	이메일 형식에 맞도록 입력		60
ordIp	구매자 아이피	유저 접속 아이피 (IPv4, IPv6 지원)		20
mbsReserved	상점 예약 필드	가맹점에서 보낸 데이터 그대로 리턴		500
goodsSplAmt	공급가	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
goodsVat	부가세	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
goodsTaxfreeAmt	면세금액	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
connCd	접속 타입	Default: userAgent 값을 확인하여 0001/0002 세팅 0001: PC Web 0002: Smartphone		4
period	제공 기간	Default: 별도 제공 기간 없음		21
returnUrl	응답 받을 URL	응답 받을 URL	Y	N/A
resultUrl	결과 후 이동 URL	라이트페이 결제 완료 화면에서 이동할 URL (PC 결제 화면만 적용) ※URL 형식이 아닐 경우, 공백처리		N/A
noIntUseFlg	가맹점 무이자 적용 여부	0: 미적용(default) 1: 적용 네이버페이 결제 요청시 0으로 고정		1
pointFlg	포인트 여부	0: 미적용(default) 1: 적용 네이버페이 결제 요청시 0으로 고정		1
instmnOptions	가능 할부 개월	가능 할부개월 중 파라미터 할부개월만 표시 예) 최대할부개월 12개월일 경우 instmnOptions = 04:05:06 => 일시불 및 할부개월 4, 5, 6개월만 표시		N/A
directType	다이렉트 타입	0: 미사용(default) 1: 사용		1
directCardCode	다이렉트 카드사 코드	payMethod=CARD 또는 KAKAOPAY, directType=1 일 경우 필수 카드사: 카드사 코드 (카드사 코드표 참조) 간편결제사: ‘00’ 고정 payMethod=CARD, payType=APPLEPAY, directType=1 일 경우 필수 카드사 : ‘00’ 고정 간편결제사: ‘00’ 고정 카카오페이 호출 시 카드사와 할부개월을 고정으로 지정하는 경우 선행 필수 설정 값 payMethod = KAKAOPAY directType=1 directCardQuota		2
ezpAuthCd	다이렉트 간편 카드사 코드	payMethod=CARD directType=1 directCardCode=00 일 경우 필수 (간편 결제사 코드표 참조) ※[ payType=APPLEPAY ] : 필수아님		2
directCardQuota	다이렉트 할부 개월	payMethod=CARD 또는 KAKAOPAY, directType=1 일 경우 필수 00: 일시불, 02:03:04 카카오페이 호출 시 카드사와 할부개월을 고정으로 지정하는 경우 선행 필수 설정 값 payMethod = KAKAOPAY directType=1 directCardCode 00: 일시불, 02:03:04 ※[ payType=APPLEPAY ] : ‘00’ 고정		2
directCardPointFlag	다이렉트 포인트 사용 여부	payMethod=CARD 또는 KAKAOPAY, directType=1 일 경우 필수 0: 미사용 1: 사용		1
directTelCd	다이렉트 통신사 코드	payMethod=MOBILE directType=1 일 경우 필수 (통신사 코드 참조)		3
crctReqType	현금 영수증 용도 타입	0: 미발행(default) 1: 소득공제 2: 지출증빙		2
crctPubType	현금 영수증 발급 타입	crctReqType 값이 1 또는 2일 경우 필수 1: 카드번호 3: 사업자등록번호 4: 휴대폰 번호		10
crctId	현금 영수증 발급 번호	crctReqType 값이 1 또는 2일 경우 필수 현금 영수증 발급 번호(숫자만 허용)		20
ediDate	전문 요청 일시	yyyyMMddHHmmss	Y	14
hashString	해시 String	SHA256 암호화 (mid + ediDate + goodsAmt + 가맹점KEY)	Y	N/A
lmtDay	입금기한일	가상계좌 입금 기한(yyyyMMdd)		8
lmtTime	입금기한시간	가상계좌 입금 기한(hhmmss)		6

※결제수단 [ 신용카드, 휴대폰, 페이코, 스마일페이 ]는 현금영수증을 발급하지 않습니다. 현금영수증 발급 관련 파라미터를 전송해도 발급되지 않습니다.

인증 결과 데이터 필드

결제창을 통해 인증이 완료되면 결과를 가맹점으로 전달합니다.

필드명	한글 명칭	설명	최대 크기
resultCd	결과 코드	[0000: 정상, 기타: 실패]	4
resultMsg	결과 메시지	결과 메시지	100
nonce	전문 번호	전문 번호	30
tid	거래 아이디	거래 아이디	30
mid	상점 아이디	상점 아이디	21
pmCd	결제 수단 코드	01: 카드 02: 계좌이체 03: 가상계좌 05: 휴대폰 20: 네이버페이 21: 카카오페이 22: 스마일페이 23: 내통장결제 24: 토스페이 25: PAYCO	2
ordNo	주문 번호	주문 번호	40
goodsAmt	거래 금액	결제 금액	15
mbsReserved	상점 예약 필드	가맹점에서 보낸 데이터 그대로 리턴	500
ediDate	전문 응답 일시	yyyyMMddHHmmss	14
payData	암호화 데이터	결제 정보 암호화 데이터	N/A
signData	검증 데이터	SHA256 암호화 (tid + mid + ediDate + goodsAmt + ordNo + 가맹점KEY) 인증 데이터 정합성을 위해 가맹점에서 HASH값 비교	N/A
approvalUrl	승인 요청 URL	승인 요청 URL	N/A
netCancelUrl	망취소 요청 URL	망취소 요청 URL	N/A

코드샘플

                                    
public String payment(Model model) throws IOException, InterruptedException {
        String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청 일시(yyyyMMddHHmmss 형식)
        String merchantKey = "";  //가맹점키
        String payMethod = "";  //결제수단
        String mid = "";  //상점 아이디
        String goodsNm = "";  //상품명
        String goodsAmt = "";  //결제금액
        String ordNo = "";  //주문 번호
        String ordNm = "";  //주문자명
        String returnUrl = "";  //응답받을 URL
        String hashString = encoding(mid + ediDate + goodsAmt + merchantKey);  //SHA256 암호화

        model.addAttribute("ediDate", ediDate);
        model.addAttribute("payMethod", payMethod);
        model.addAttribute("mid", mid);
        model.addAttribute("goodsNm", goodsNm);
        model.addAttribute("goodsAmt", goodsAmt);
        model.addAttribute("ordNo", ordNo);
        model.addAttribute("ordNm", ordNm);
        model.addAttribute("returnUrl", returnUrl);
        model.addAttribute("hashString", hashString);

        return "template";
}
public String encoding(String input) throws NoSuchAlgorithmException {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
        return new String(Hex.encodeHex(hash));
}



<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta http-equiv="Cache-Control" content="no-cache" />
<meta name="viewport" content="width=device-width, height=device-height, initial-scale=1.0, minimum-scale=1.0, maximum-scale=3.0">
<title>결제 TEST</title>
<script src="https://testpaywin.lightpay.kr/js/pgAsistant.js"></script>
</head>
<body>
    <script>
        function doPaySubmit(){
            SendPay(document.payInit, "TEST");  //결제창 호출 함수
        }
    	// 결제창 return 함수(pay_result_submit 이름 변경 불가능)
        function pay_result_submit(){
            payResultSubmit();
        }
        // 결제창 종료 함수(pay_result_close 이름 변경 불가능)
        function pay_result_close(){
            alert('결제를 취소하였습니다.');
        }
    </script>
    <form name="payInit" method="post">
        <input type="text" name="mid" th:value="${mid}">
        <input type="text" name="payMethod" th:value="${payMethod}">
        <input type="text" name="payType" th:value="${payType}">
        <input type="text" name="goodsNm" th:value="${goodsNm}">
        <input type="text" name="ordNo" th:value="${ordNo}">
        <input type="text" name="goodsAmt" th:value="${goodsAmt}">
        <input type="text" name="ordNm" th:value="${ordNm}">
        <input type="text" name="returnUrl" th:value="${returnUrl}">
        <input type="hidden" name="ediDate" th:value="${ediDate}">
        <input type="hidden" name="hashString" th:value="${hashString}">
        <button type="submit" id="payBtn" style="padding: 10px;" onclick="doPaySubmit()">결제하기</button>
    </form>
</body>
</html>


                                

                                    
<?php
$ediDate = date("YmdHis");  //요청일시 (yyyy MMddHHmmss 형식)
$merchantKey = "";  //가맹점KEY
$mid = "";  //상점 아이디
$goodsAmt = "";  //결제금액
$hashString = hash("sha256", $mid.$ediDate.$goodsAmt.$merchantKey);  //SHA256 암호화
?>
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta http-equiv="Cache-Control" content="no-cache" />
<meta name="viewport" content="width=device-width, height=device-height, initial-scale=1.0, minimum-scale=1.0, maximum-scale=3.0">
<title>결제 TEST</title>
<script src="https://testpaywin.lightpay.kr/js/pgAsistant.js"></script>
</head>
<body>
    <script>
        function doPaySubmit(){
            SendPay(document.payInit, "TEST");  //결제창 호출 함수
        }
    	// 결제창 return 함수(pay_result_submit 이름 변경 불가능)
        function pay_result_submit(){
            payResultSubmit();
        }
        // 결제창 종료 함수(pay_result_close 이름 변경 불가능)
        function pay_result_close(){
            alert('결제를 취소하였습니다.');
        }
    </script>
    <form name="payInit" method="post">
        <input type="text" name="mid" value="<?php echo $mid; ?>">
        <input type="text" name="payMethod" value="">
        <input type="text" name="payType" value="">
        <input type="text" name="goodsNm" value="">
        <input type="text" name="ordNo" value="">
        <input type="text" name="goodsAmt" value="<?php echo $goodsAmt; ?>">
        <input type="text" name="ordNm" value="">
        <input type="text" name="returnUrl" value="">
        <input type="hidden" name="ediDate" value="<?php echo $ediDate; ?>">
        <input type="hidden" name="hashString" value="<?php echo $hashString; ?>">
        <button type="submit" id="payBtn" style="padding: 10px;" onclick="doPaySubmit()">결제하기</button>
    </form>
</body>
</html>


                                

                                    
curl -X POST 'https://testpaywin.lightpay.kr/payment/v1/view/request' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode "payMethod=CARD" \
     --data-urlencode "mid=testmidm" \
     --data-urlencode "goodsNm=테스트상품" \
     --data-urlencode "goodsAmt=100" \
     --data-urlencode "ordNo=234235373452" \
     --data-urlencode "ordNm=홍길동" \
     --data-urlencode "returnUrl=/" \
     --data-urlencode "ediDate=20250325103323" \
     --data-urlencode "hashString=47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"


                                

승인 요청

승인 요청 URL

운영	https://paywin.lightpay.kr/payment/v1/approval
개발	https://testpaywin.lightpay.kr/payment/v1/approval

인증 응답값의 approvalUrl과 동일

승인 요청 데이터 필드

결제창을 통해 받은 인증 결과로 승인 요청을 보냅니다.

필드명	한글 명칭	설명	필수 여부	최대 크기
nonce	전문 번호	인증 결과에서 받은 nonce	Y	30
tid	거래 아이디	인증 결과에서 받은 tid	Y	30
ediDate	전문 요청 일시	yyyyMMddHHmmss	Y	14
mid	상점 아이디	상점 아이디	Y	21
goodsAmt	거래 금액	결제 금액	Y	15
mbsReserved	상점 예약 필드	가맹점에서 보낸 데이터 그대로 리턴		500
hashString	해시 String	SHA256 암호화 (mid + ediDate + goodsAmt + 가맹점KEY)	Y	N/A
payData	암호화 데이터	인증결과에서 받은 payData	Y	N/A

결제 결과 데이터 필드

승인이 완료되면 결과를 가맹점으로 전달합니다.

필드명	한글 명칭	설명	최대 크기
resultCd	결과 코드	[0000: 정상, 기타: 실패]	4
resultMsg	결과 메세지	결과 메세지	100
tid	거래 아이디	거래 아이디	30
mid	상점 아이디	상점 아이디	21
pmCd	결제 수단 코드	01: 신용카드 02: 계좌이체 03: 가상계좌 05: 휴대폰 20: 네이버페이 21: 카카오페이 22: 스마일페이 23: 내통장결제 24: 토스페이 25: PAYCO	2
spmCd	서브 결제 수단 코드	신용카드 01: 인증 02: 수기(구인증) 04: 빌링 05: 수기(비인증) 07: 애플페이 나머지 결제수단 01: 고정	2
ediDate	전문 응답 일시	yyyyMMddHHmmss	14
ordNo	주문 번호	주문 번호	40
goodsNm	결제 상품명	결제 상품명 ※ spmCd가 [ 04 : 빌링 ]일 경우에는 제외	100
goodsAmt	거래 금액	결제 결과 금액 ※ spmCd가 [ 04 : 빌링 ]일 경우에는 제외	15
ordNm	구매자명	구매자 이름 ※ spmCd가 [ 04 : 빌링 ]일 경우에는 제외	30
mbsReserved	상점 예약 필드	가맹점에서 보낸 데이터 그대로 리턴	500
trxCd	‘0’ 고정	‘0’ 고정	1
trDt	거래일	yyyyMMdd	8
trTm	거래 시간	HHmmss	6
receiptUrl	거래명세서 URL	resultCd 값이 ‘0000’인 경우에만 반환 ※ spmCd가 [ 04 : 빌링 ]일 경우에는 제외	200

신용카드 결제 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
fnNm	발급 카드사명	카드사명	20
cardNo	카드 번호	마스킹된 카드번호	20
appNo	승인 번호	승인 번호 ※ spmCd가 [ 04 : 빌링 ]일 경우에는 응답제외	20
appCardCd	카드 발급사 코드	카드 발급사 코드 (카드사 코드표 참조)	2
acqCardCd	카드 매입사 코드	카드 매입사 코드 (카드사 코드표 참조)	2
quotaMon	카드 할부개월	할부 기간 (예: 00, 02, 03, …, 12, 두자리) ※ spmCd가 [ 04 : 빌링 ]일 경우에는 응답제외	2
noIntFlg	무이자 거래 여부	0: 일반 1: 무이자 ※ spmCd가 [ 04 : 빌링 ]일 경우에는 응답제외	1
noIntUseFlg	가맹점 무이자 적용 여부	0: 미적용 1: 적용 ※ spmCd가 [ 04 : 빌링 ]일 경우에는 응답제외	1
pointFlg	포인트 사용 여부	0: 미적용 1: 적용 ※spmCd가 [ 04 : 빌링 ]일 경우에는 응답제외	1
cardTypeCd	카드 타입 코드	01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	체크 카드 여부	0: 신용 1: 체크 데이터 없으면 공백 리턴	1
bid	빌키	빌키 아이디 ※ spmCd가 [ 04 : 빌링 ]일 경우에만 응답	30

가상계좌 결제(채번) 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
fnNm	은행명	은행명	20
bankCd	은행 코드	은행 코드	4
vacntNo	가상계좌 번호	가상계좌 번호	20
name	예금주 명	가상계좌 예금주 명	20
lmtDay	입금 기한	입금 기한(yyyyMMdd)	8
lmtTime	입금 기한 시간	입금 기한 시간(hhmmss)	6
crctReqType	현금영수증 요청타입	0: 미발행 1: 소득공제 2: 지출증빙 3: 자진발급	1

네이버페이 결제 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
payNm	주 결제수단	CARD : 카드 BANK : 은행 MONEY : 포인트머니	20
cardNm	발급 카드사명	카드사명	20
cardNo	카드 번호	마스킹된 카드번호	50
appNo	승인 번호	승인 번호	30
cardCd	카드 발급사 코드	카드 코드 (카드사 코드표 참조)	2
quotaMon	카드 할부개월	할부 기간 (예: 00, 02, 03, …, 12, 두자리)	2
bankNm	은행명	은행명	20
bankCd	은행 코드	은행 코드 (은행코드표 참고)	4
bankNo	계좌 번호	마스킹 된 계좌 번호	50
payAmt	주 결제수단 금액	거래금액 중 주 결제수단으로 결제 된 금액	15
npointPayAmt	포인트/머니 금액	거래금액 중 포인트/머니로 결제 된 금액	15
crctReqType	현금영수증 요청타입	0: 미발행 1: 소득공제 2: 지출증빙 3: 자진발급	1

카카오페이 결제 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
fnNm	발급 카드사명	카드사명	20
cardNo	카드 번호	마스킹된 카드번호 (카카오 머니 결제시 공백)	20
appNo	승인 번호	승인 번호 (카카오머니 결제시 000000)	20
appCardCd	카드 발급사 코드	카드 발급사 코드 (카드사 코드표 참조)	2
acqCardCd	카드 매입사 코드	카드 매입사 코드 (카드사 코드표 참조)	2
quotaMon	카드 할부개월	할부 기간 (예: 00, 02, 03, …, 12, 두자리)	2
cardTypeCd	카드 타입 코드	01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	체크 카드 여부	0: 신용 1: 체크 데이터 없으면 공백 리턴	1
multiPointAmt	복합결제 포인트 금액	카카오페이 머니 포함	12
multiCardAcquAmt	복합결제 신용카드 금액		12
multiCl	복합결제 사용여부	0: 미사용 1: 사용	1
multiCouponAmt	복합결제 쿠폰 금액		12
couponAmt	쿠폰금액		12
couponMinAmt	쿠폰 최소금액		12

스마일페이 결제 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
fnNm	발급 카드사명	카드사명	20
cardNo	카드 번호	마스킹된 카드번호 (스마일캐시 전액 결제시 공백)	20
appNo	승인 번호	승인 번호 (결제수단에 따라 양식 상이)	20
appCardCd	카드 발급사 코드	카드 발급사 코드 (카드사 코드표 참조)	2
acqCardCd	카드 매입사 코드	카드 매입사 코드 (카드사 코드표 참조)	2
quotaMon	카드 할부개월	할부 기간 (예: 00, 02, 03, …, 12, 두자리)	2
noIntUseFlg	가맹점 무이자 적용 여부	0: 미적용 1: 적용	1
cardTypeCd	카드 타입 코드	01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	체크 카드 여부	0: 신용 1: 체크 데이터 없으면 공백 리턴	1
smileCash	스마일캐시	거래금액 중 스마일캐시 사용 금액	15
cashAmt	현금성금액	거래금액 중 현금성 사용 금액	15
discountAmt	스마일페이 프로모션 할인금액	스마일페이 프로모션 할인금액	15

계좌이체 결제 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
bankNm	은행명	은행명	20
bankCd	은행 코드	은행 코드	4
crctReqType	현금영수증 요청타입	0: 미발행 1: 소득공제 2: 지출증빙 3: 자진발급	1

휴대폰 결제 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
telNm	통신사명	통신사명	20
telCd	통신사코드	통신사코드	4
phoneNo	전화번호	마스킹된 휴대폰 번호	11

내통장 결제 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
crctReqType	현금영수증 요청타입	0: 미발행 1: 소득공제 2: 지출증빙 3: 자진발급	1
criPrice	현금영수증 금액	현금영수증 발급 가능 금액	15
criTaxVatPrice	현금영수증 과세금액	현금영수증 과세 금액	15
criDutyFreePrice	현금영수증 비과세 금액	현금영수증 비과세 금액	15
discntPrice	할인금액	할인금액	15

PAYCO 결제 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
cardAmt	카드금액	카드금액	15
couponAmt	쿠폰금액	쿠폰금액 (페이코포인트 금액 포함)	15
paycoPointAmt	페이코포인트 금액	페이코포인트 금액	15
fnNm	발급 카드사명	카드사명	20
appCardCd	카드 발급사 코드	카드 발급사 코드 (카드사 코드표 참조)	2
acqCardCd	카드 매입사 코드	카드 매입사 코드 (카드사 코드표 참조)	2
quotaMon	카드 할부개월	할부 기간(예: 00, 02, 03, …, 12, 두자리)	2

토스페이 결제 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
cardTypeCd	카드 타입 코드	데이터 없으면 공백 리턴 01: 개인 02: 법인	2
acqCardCd	카드 매입사 코드	카드 매입사 코드 (카드사 코드표 참조)	2
appCardCd	카드 발급사 코드	카드 발급사 코드 (카드사 코드표 참조)	2
cardNo	카드 번호	마스킹된 카드번호 (계좌 결제 결제 시 공백)	20
quotaMon	카드 할부개월	할부 기간 (예: 00, 02, 03, …, 12, 두자리)	2
appNo	승인 번호	승인 번호 (계좌 결제시 000000)	20
fnNm	발급 카드사명	카드사명	20
cashAmt	현금성 금액	거래금액 중 현금성 사용 금액	15
discountAmt	적립성 포인트	토스포인트	15
crctReqType	현금영수증 요청타입	0: 미발행 1: 소득공제 2: 지출증빙 3: 자진발급	1

승인 요청 후 결제결과(responseBody)를 받아 내부처리(DB 저장 등) 하시기 바랍니다.

수신시 전송 필드명을 명확히하여 처리하시기 바랍니다. (필드명 대/소문자 구분)

승인에 실패하였을 경우 실패시 전달되는 데이터만 전송됩니다.

코드샘플

                                    
public void payResult(HttpServletRequest request) throws Exception {
    /* 결제창을 통해 받은 인증 결과 */
    String resultCd = request.getParameter("resultCd");  //인증결과
    String resultMsg = request.getParameter("resultMsg");  //인증결과 메시지
    String nonce = request.getParameter("nonce");  //전문 번호
    String tid = request.getParameter("tid");  //거래 아이디
    String mid = request.getParameter("mid");  //상점 아이디
    String ordNo = request.getParameter("ordNo");  //주문번호
    String goodsAmt = request.getParameter("goodsAmt");  //결제 금액
    String ediDate = request.getParameter("ediDate");  //응답 일시(yyyyMMddHHmmss)
    String payData = request.getParameter("payData");  //결제 정보 암호화 데이터
    String signData = request.getParameter("signData");  //검증데이터
    String approvalUrl = request.getParameter("approvalUrl");  //승인 요청 URL
    String netCancelUrl = request.getParameter("netCancelUrl");  //망취소 요청 URL

    String merchantKey = "";   //가맹점KEY
    String mSignData = encoding(tid + mid + ediDate + goodsAmt + ordNo + merchantKey);  //결과로 받은 검증 데이터(signData)와 비교용 검증 데이터
    String hashString = encoding(mid + ediDate + goodsAmt + merchantKey);  //SHA256 암호화

    //승인 요청(결제창을 통해 받은 인증 결과로 승인 요청을 보냅니다.)
    if(signData.equals(mSignData) && resultCd.equals("0000")){
        StringBuilder requestData = new StringBuilder();
        requestData.append("nonce=").append(nonce).append("&")
        .append("tid=").append(tid).append("&")
        .append("mid=").append(mid).append("&")
        .append("goodsAmt=").append(goodsAmt).append("&")
        .append("ediDate=").append(ediDate).append("&")
        .append("hashString=").append(hashString).append("&")
        .append("payData=").append(payData);

        HttpRequest httpRequest = HttpRequest.newBuilder()
                .uri(URI.create(approvalUrl))
                .header("Content-Type", "application/x-www-form-urlencoded")
                .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
                .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
/* 결제창을 통해 받은 인증 결과 */
$merchantKey = "";  //가맹점KEY
$mid = $_POST['mid'];  //상점 아이디
$resultCd = $_POST['resultCd'];  //인증결과
$resultMsg = $_POST['resultMsg'];  //인증결과 메시지
$nonce = $_POST['nonce'];  //전문 번호
$tid = $_POST['tid'];  //거래 아이디
$ordNo = $_POST['ordNo'];  //주문번호
$goodsAmt = $_POST['goodsAmt'];  //결제 금액
$ediDate = $_POST['ediDate'];  //응답 일시(yyyyMMddHHmmss 형식)
$payData = $_POST['payData'];  //결제 정보 암호화 데이터
$signData = $_POST['signData'];  //검증데이터
$approvalUrl = $_POST['approvalUrl'];  //승인 요청 URL
$netCancelUrl = $_POST['netCancelUrl'];  //망취소 요청 URL
$hashString = hash("sha256", $mid.$ediDate.$goodsAmt.$merchantKey);  //SHA256 암호화
$mSignData = hash("sha256", $tid.$mid.$ediDate.$goodsAmt.$ordNo.$merchantKey);  //결과로 받은 검증데이터(signData)와 비교용 검증 데이터

//승인 요청(결제창을 통해 받은 인증 결과로 승인 요청을 보냅니다.)
if($signData === $mSignData && $resultCd === "0000"){
    $data = [
        "nonce" => $nonce,
        "tid" => $tid,
        "mid" => $mid,
        "goodsAmt" => $goodsAmt,
        "ediDate" => $ediDate,
        "hashString" => $hashString,
        "payData" => $payData
    ];

    $ch = curl_init($approvalUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

    $response = curl_exec($ch);
    curl_close($ch);
    echo $response;
}
?>


                                

                                    
curl -X POST "https://testpaywin.lightpay.kr/payment/v1/approval" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "tid=testmidm0010125032558bde59688" \
     --data-urlencode "mid=testmidm" \
     --data-urlencode "goodsAmt=100" \
     --data-urlencode "ediDate=20250325103323" \
     --data-urlencode "payData=ruT509YNCv1DHo3EiKPVEbz9O731O5_7tGWd_TLu3BrA1zFy-X0hm-RfWTkAqh6WV_XcSFSaVFiNpD8BuuqS9uNFcCifoetq87UGBXR1rjwXnoMVK11Hm2F0n4_V-0kbQcLEct85WbqDe5yGxyAcTRlchwzYD9ojRo624KrJRtqA3Ib0n7UOXW4Lltcj1dV79ysauYcYfXQauvaZzYHVvDkqN1TF1danbp7d2L1fA_8xoAikRF7xtlOeqrf2JoDqqYTFMHkeRvtv5_KrJFWzRBkSJc8758DxUg1t_XtGl24Y8AFVSI" \
     --data-urlencode "hashString=47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c" \
     --data-urlencode "nonce=8ggjwifkgcw3r20250325093050425"


                                

빌링

개요

본 문서는 UDID의 지불결제 서비스를 이용하는 가맹점이 UDID에서 제공하는 빌링 결제를 이용하는 방법을 제공합니다.

과정

빌키 발급 정보 입력

사용자는 가맹점이 구성한 웹 페이지에서 카드정보를 입력합니다.

빌키 발급 요청, 응답

가맹점은 사용자로부터 전달받은 카드정보와 가맹점 정보를 가공하여 빌키 발급을 요청합니다.
발급된 빌키를 포함한 응답 값을 가공하여 이후 가맹점 프로세스를 진행합니다.

빌키 승인 요청, 응답

가맹점은 빌키를 포함한 결제 전문을 가공하여 승인 요청합니다.
승인 응답 값을 가공하여 이후 가맹점 프로세스를 진행합니다.
PG사의 응답데이터는 JSON 기본 포맷으로 응답되며, 기능 추가에 따라 응답 필드가 추가될 수 있습니다. 이에 따라 가맹점에서 응답필드가 추가 될 수 있음을 고려해야 합니다.

빌키 삭제 요청, 응답

가맹점은 빌키를 포함한 빌키 삭제 전문을 가공하여 빌키 삭제 요청합니다.
빌키 삭제 응답 값을 가공하여 이후 가맹점 프로세스를 진행합니다.

주의사항

가맹점에서는 사용자가 입력한 정보가 노출되지 않도록 주의해야합니다.

예외처리

빌키 발급 요청 시 주의 및 오류 사항

빌키 발급 요청시 암호화

빌키 발급 요청 시 사용자를 통해 받은 결제 정보를 암호화하여 전달합니다.

호출 오류

방화벽 설정이 정상인지 확인합니다.

사용자 카드로 인한 빌키 발급 에러 발생

사용자 카드 유효성 문제가 있는 경우 빌키가 발급되지 않습니다.
유효성 문제로 인한 빌키 발급 실패 원인은 TID를 통해 오류 사유 추적이 가능합니다.

빌키 승인 요청시 주의 및 오류

Connection 오류가 발생하지 않도록 가맹점 네트워크의 이상 유무 체크가 필요합니다.
TID 생성 시 다른 거래건의 TID와 중복되지 않아야 합니다.
결제정보 암호화
• 빌키 승인 시 결제하려는 빌키를 포함한 결제정보를 암호화하여 전달합니다.

빌키 승인 응답 중 오류 발생

빌키 발급 시에는 유효하였으나 빌키 승인 시점에 문제가 발생한 카드일 수 있습니다.
승인 시점에 문제가 발생하는 경우 결제 취소 프로세스를 적용하여 거래를 취소할 수 있습니다.

빌키 삭제 요청 시 주의 및 오류

한 번 삭제한 빌키는 동일한 값으로 원복하거나 재생성할 수 없습니다.

빌키 발급

요청 URL

운영	https://paywin.lightpay.kr/payment/bill/regist
개발	https://testpaywin.lightpay.kr/payment/bill/regist

요청 정보

Protocol	Method	Encoding	Content-type
HTTP/1.1	POST	UTF-8	application/x-www-form-urlencoded;
HTTP/1.1	POST	UTF-8	application/json

요청 파라미터

필드명	설명	필수 여부	최대 크기
payMethod	지불 수단(CARD)	Y	N/A
mid	가맹점 아이디	Y	21
ordNo	주문번호 – Unique 한 값	Y	40
goodsNm	상품명(예: 테스트상품)	Y	100
goodsAmt	‘0’ 고정	Y	15
ordNm	구매자명(예: 빌링이)	Y	30
ordIp	구매자 IP(IPv4, IPv6 지원)		20
ordTel	구매자 전화번호(예: 01012341234)		20
ordEmail	구매자 Email		60
mbsReserved	상점 예약 필드		500
cpCd	카드사 코드		4
cardTypeCd	카드 타입 코드 0: 일반 1: 법인		2
cardNo	카드번호	Y	20
expireYymm	유효기간(yyMM)	Y	4
ordAuthNo	카드 인증번호(생년월일/사업자번호)		10
cardPw	카드 비밀번호		4
connCd	접속타입 Default: userAgent 값을 확인하여 0001/0002 세팅 0001: PC Web 0002: Smartphone		4
ediDate	전문 요청 일시(yyyyMMddHHmmss)	Y	14
hashString	SHA256 암호화(mid + ediDate + goodsAmt + 가맹점KEY)	Y	256

응답 파라미터

파라미터	설명	최대 크기
resultCd	결과 코드 [0000: 정상, 기타: 실패]	4
resultMsg	결과 메세지	100
bid	빌키 아이디	30
tid	거래 아이디	30
mid	상점 아이디	21
pmCd	결제 수단 코드(01: 신용카드)	2
spmCd	서브 결제 수단 코드(04: 빌링)	2
ediDate	전문 응답 일시(yyyyMMddHHmmss)	14
ordNo	주문 번호	40
fnNm	발급 카드사명	20
cardNo	마스킹된 카드번호	20
cpCd	카드 발급사 코드	2
acqCardCd	카드 매입사 코드	2
cardTypeCd	01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	0: 신용 1: 체크 데이터 없으면 공백 리턴	1
mbsReserved	상점 예약 필드	500
trDt	거래일(yyyyMMdd)	8
trTm	거래 시간(HHmmss)	6

코드샘플

                                    
public void billReg() throws IOException, InterruptedException {
    String merchantKey = "";  //가맹점KEY
    String payMethod = "CARD";  //지불 수단
    String mid = "";  //상점 아이디
    String ordNo = "";  //주문번호
    String goodsNm = "";  //상품명
    String goodsAmt = "0";  //결제 금액 '0'으로 고정
    String ordNm = "";  //구매자명
    String cardNo = "";  //카드번호
    String expireYymm = "";  //유효기간(yyMM 형식)
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청일시 (yyyyMMddHHmmss 형식)
    String hashString = encoding(mid + ediDate + goodsAmt + merchantKey); //SHA256 암호화

    StringBuilder requestData = new StringBuilder();
    requestData.append("payMethod=").append(payMethod).append("&")
    .append("mid=").append(mid).append("&")
    .append("ediDate=").append(ediDate).append("&")
    .append("cardNo=").append(cardNo).append("&")
    .append("expireYymm=").append(expireYymm).append("&")
    .append("goodsNm=").append(goodsNm).append("&")
    .append("ordNo=").append(ordNo).append("&")
    .append("goodsAmt=").append(goodsAmt).append("&")
    .append("ordNm=").append(ordNm).append("&")
    .append("hashString=").append(hashString);

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testpaywin.lightpay.kr/payment/bill/regist"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$payMethod = "CARD";  //지불 수단
$mid = "";  //상점 아이디
$ordNo = "";  //요청 일시
$goodsNm = "";  //상품명
$goodsAmt = "0";  //결제 금액 '0'으로 고정
$ordNm = "";  //구매자명
$cardNo = "";  //카드번호
$expireYymm = "";  //유효기간(yyMM 형식)
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$merchantKey = "";  //가맹점KEY
$hashString = hash("sha256", $mid.$ediDate.$goodsAmt.$merchantKey);  //SHA256 암호화
$url = "https://testpaywin.lightpay.kr/payment/bill/regist";

$data = [
    "payMethod" => $payMethod,
    "mid" => $mid,
    "ordNo" => $ordNo,
    "goodsNm" => $goodsNm,
    "goodsAmt" => $goodsAmt,
    "ordNm" => $ordNm,
    "cardNo" => $cardNo,
    "expireYymm" => $expireYymm,
    "ediDate" => $ediDate,
    "hashString" => $hashString
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testpaywin.lightpay.kr/payment/bill/regist' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode "payMethod=CARD" \
     --data-urlencode "mid=testmidm" \
     --data-urlencode "ordNo=1234123451234" \
     --data-urlencode "goodsNm=테스트상품" \
     --data-urlencode "goodsAmt=100" \
     --data-urlencode "ordNm=홍길동" \
     --data-urlencode "cardNo=1234123412341234" \
     --data-urlencode "expireYymm=2503" \
     --data-urlencode "ediDate=20250325103323" \
     --data-urlencode "hashString=47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"


                                

빌키 결제(승인)

요청 URL

운영	https://paywin.lightpay.kr/payment/bill/pay
개발	https://testpaywin.lightpay.kr/payment/bill/pay

요청 정보

Protocol	Method	Encoding	Content-type
HTTP/1.1	POST	UTF-8	application/x-www-form-urlencoded;
HTTP/1.1	POST	UTF-8	application/json

요청 파라미터

파라미터	설명	필수 여부	최대 크기
bid	빌링 아이디(빌키)	Y	30
payMethod	지불 수단(CARD)	Y	N/A
mid	가맹점 아이디	Y	21
ordNo	주문번호 – Unique 한 값	Y	40
goodsNm	상품명(예: 테스트상품)	Y	100
goodsAmt	결제 금액(예: 1000)	Y	15
goodsSplAmt	공급가(부가세 설정이 전송금액 기준이면 필수)		15
goodsVat	부가세(부가세 설정이 전송금액 기준이면 필수)		15
goodsTaxfreeAmt	면세금액(부가세 설정이 전송금액 기준이면 필수)		15
ordNm	구매자명(예 : 빌링이)	Y	30
ordIp	구매자 IP(예: 127.0.0.1 or 0:0:0:0:0:0:0:1, IPv4, IPv6 지원)		20
ordTel	구매자 전화번호(예: 01012341234)		20
ordEmail	구매자 Email		60
mbsReserved	상점 예약 필드		500
quotaMon	할부기간(예: 00, 02, 03, …, 12, 두자리)	Y	2
noIntUseFlg	가맹점 무이자 적용 여부 0: 미적용(default) 1: 적용		1
pointFlg	포인트 사용 여부 0: 미사용 1: 사용		1
connCd	접속타입 Default: userAgent 값을 확인하여 0001/0002 세팅 0001: PC Web 0002: Smartphone		4
ediDate	전문 요청 일시(yyyyMMddHHmmss)	Y	14
hashString	SHA256 암호화(mid + ediDate + goodsAmt + 가맹점KEY)	Y	256

응답 파라미터

파라미터	설명	최대 크기
resultCd	결과 코드 [0000: 정상, 기타: 실패]	4
resultMsg	결과 메세지	100
tid	거래 아이디	30
mid	상점 아이디	21
pmCd	결제 수단 코드(01: 신용카드)	2
spmCd	서브 결제 수단 코드(04: 빌링)	2
ediDate	전문 응답 일시(yyyyMMddHHmmss)	14
ordNo	주문 번호	40
goodsNm	결제 상품명	100
goodsAmt	거래 금액	15
ordNm	구매자명	30
mbsReserved	상점 예약 필드	500
trxCd	‘0’ 고정	1
trDt	거래일(yyyyMMdd)	8
trTm	거래 시간(HHmmss)	6
fnNm	발급 카드사명	20
cardNo	카드 번호	20
appNo	승인 번호	20
appCardCd	카드 발급사 코드	2
acqCardCd	카드 매입사 코드	2
quotaMon	카드 할부개월(예: 00, 02, 03, …, 12, 두자리)	2
noIntFlg	무이자 거래 여부 0: 일반 1: 무이자	1
noIntUseFlg	가맹점 무이자 적용 여부 0: 미적용 1: 적용	1
pointFlg	포인트 사용 여부 0: 미사용 1: 사용	1
cardTypeCd	카드 타입 코드 01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	체크카드 여부 0: 신용 1: 체크 데이터 없으면 공백 리턴	1
receiptUrl	거래명세서 URL. resultCd 값이 ‘0000’인 경우에만 리턴	200

코드샘플

                                    
public void billPay() throws IOException, InterruptedException {
    String merchantKey = "";  //가맹점KEY
    String payMethod = "CARD";  //결제수단
    String bid = "";  //빌링 아이디
    String mid = "";  //mid
    String ordNo = "";  //주문번호
    String goodsNm = "";  //상품명
    String goodsAmt = "";  //결제금액
    String ordNm = "";  //구매자명
    String quotaMon = "";  //할부기간
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청 일시
    String hashString = encoding(mid + ediDate + goodsAmt + merchantKey); //SHA256 암호화

    StringBuilder requestData = new StringBuilder();
    requestData.append("payMethod=").append(payMethod).append("&")
            .append("bid=").append(bid).append("&")
            .append("mid=").append(mid).append("&")
            .append("ordNo=").append(ordNo).append("&")
            .append("goodsNm=").append(goodsNm).append("&")
            .append("goodsAmt=").append(goodsAmt).append("&")
            .append("ordNm=").append(ordNm).append("&")
            .append("quotaMon=").append(quotaMon).append("&")
            .append("ediDate=").append(ediDate).append("&")
            .append("hashString=").append(hashString);

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testpaywin.lightpay.kr/payment/bill/pay"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$bid = "";  //빌링 아이디
$payMethod = "";  //지불 수단
$mid = "";  //상점 아이디
$ordNo = "";  //요청 일시
$goodsNm = "";  //상품명
$goodsAmt = "";  //결제 금액
$ordNm = "";  //구매자명
$quotaMon = "";  //할부기간
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$merchantKey = "";  //가맹점KEY
$hashString = hash("sha256", $mid.$ediDate.$goodsAmt.$merchantKey);  //SHA256 암호화
$url = "https://testpaywin.lightpay.kr/payment/bill/pay";

$data = [
    "bid" => $bid,
    "payMethod" => $payMethod,
    "mid" => $mid,
    "ordNo" => $ordNo,
    "goodsNm" => $goodsNm,
    "goodsAmt" => $goodsAmt,
    "ordNm" => $ordNm,
    "quotaMon" => $quotaMon,
    "ediDate" => $ediDate,
    "hashString" => $hashString
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST "https://testpaywin.lightpay.kr/payment/bill/pay" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "payMethod=CARD" \
     --data-urlencode "mid=testmidm" \
     --data-urlencode "goodsNm=테스트상품" \
     --data-urlencode "goodsAmt=100" \
     --data-urlencode "ordNo=7231415352432563" \
     --data-urlencode "ordNm=홍길동" \
     --data-urlencode "quotaMon=00" \
     --data-urlencode "bid=testmidm0104250325565904a686" \
     --data-urlencode "ediDate=20250325103323" \
     --data-urlencode "hashString=47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"


                                

빌키 삭제

요청 URL

운영	https://paywin.lightpay.kr/payment/bill/delete
개발	https://testpaywin.lightpay.kr/payment/bill/delete

요청 정보

Protocol	Method	Encoding	Content-type
HTTP/1.1	POST	UTF-8	application/x-www-form-urlencoded;
HTTP/1.1	POST	UTF-8	application/json

요청 파라미터

파라미터	설명	필수 여부	최대 크기
bid	빌링 아이디(빌키)	Y	30
mid	가맹점 아이디	Y	10
ordNo	주문번호 – Unique 한 값		40
mbsReserved	상점 예약 필드		500
ediDate	전문 요청 일시(yyyyMMddHHmmss)	Y	14
hashString	SHA256 암호화(mid + ediDate + bid + 가맹점KEY)	Y	256

응답 파라미터

파라미터	설명	최대 크기
resultCd	결과 코드 [0000: 정상, 기타: 실패]	4
resultMsg	결과 메세지	100
bid	빌키 아이디	30
tid	거래 아이디	30
mid	상점 아이디	21
pmCd	결제 수단 코드(01: 신용카드)	21
spmCd	서브 결제 수단 코드(04: 빌링)	2
ediDate	전문 응답 일시(yyyyMMddHHmmss)	14
ordNo	주문 번호	40
mbsReserved	상점에서 보낸 데이터 그대로 리턴	500
trDt	거래일(yyyyMMdd)	8
trTm	거래 시간(HHmmss)	6

코드샘플

                                    
public void billDel() throws IOException, InterruptedException {
    String merchantKey = "";  //가맹점KEY
    String bid = "";  //빌링 아이디
    String mid = "";  //mid
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청 일시
    String hashString = encoding(mid + ediDate + bid + merchantKey);  //SHA256 암호화

    StringBuilder requestData = new StringBuilder();
    requestData.append("bid=").append(bid).append("&")
    .append("mid=").append(mid).append("&")
    .append("ediDate=").append(ediDate).append("&")
    .append("hashString=").append(hashString);

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testpaywin.lightpay.kr/payment/bill/delete"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$bid = "";  //빌링 아이디
$mid = "";  //상점 아이디
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$merchantKey = "";  //가맹점KEY
$hashString = hash("sha256", $mid.$ediDate.$bid.$merchantKey);  //SHA256 암호화
$url = "https://testpaywin.lightpay.kr/payment/bill/delete";

$data = [
    "bid" => $bid,
    "mid" => $mid,
    "ediDate" => $ediDate,
    "hashString" => $hashString
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST "https://testpaywin.lightpay.kr/payment/bill/delete" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "mid=testmidm" \
     --data-urlencode "bid=testmidm0104250325565904a686" \
     --data-urlencode "ediDate=20250325103323" \
     --data-urlencode "hashString=47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"


                                

키인

개요

결제 진행을 위해 사용자는 가맹점이 구성한 웹 페이지에서 카드정보를 입력합니다.

결제 요청

요청 URL

운영	https://paywin.lightpay.kr/payment/v1/keyin
개발	https://testpaywin.lightpay.kr/payment/v1/keyin

요청 정보

Protocol	HTTP/1.1
Method	POST
Encoding	UTF-8
Content-type	application/x-www-form-urlencoded;

결제 기본 요청데이터 필드

필드명	한글 명칭	설명	필수 여부	최대 크기
payMethod	결제 방법	결제 방법 (CARD)	Y	10
mid	상점 아이디	상점 아이디	Y	21
payType	결제 유형	KEYIN: 구인증(default) NONE: 비인증		N/A
keyInType	키인 타입	payType 이 NONE인 경우에만 적용 01: 후불교통카드(payOn) 02: 카메라 (OCR) 03: 키인 (default)		2
goodsNm	상품명	상품 이름	Y	100
ordNo	주문 번호	Unique한 값	Y	40
goodsAmt	결제 금액	숫자만 입력 가능	Y	15
ordNm	구매자명	한글/특수기호 입력 가능	Y	30
ordTel	구매자 전화번호	숫자만 허용		20
ordEmail	구매자 Email	이메일 형식에 맞도록		60
ordIp	구매자 아이피	유저 접속 아이피(IPv4, IPv6 지원)		20
mbsReserved	상점 예약 필드	가맹점에서 보낸 데이터 그대로 리턴		500
cpCd	카드사 코드	카드사 코드		2
cardNo	카드 번호	카드 번호	Y	16
cardTypeCd	카드 타입 코드	01: 개인 02: 법인	Y	2
expireYymm	카드 유효기간	yyMM(2403)	Y	4
ordAuthNo	카드 인증 번호	payType이 KEYIN 일 경우 필수 생년월일(사업자번호)		10
cardPw	카드 비밀번호	payType이 KEYIN 일 경우 필수 카드 비밀번호 앞 2자리		2
quotaMon	할부개월	00: 일시불 02:03:04	Y	2
noIntUseFlg	가맹점 무이자 적용 여부	0: 미적용(default) 1: 적용		1
pointFlg	포인트 여부	0: 미적용(default) 1: 적용		1
goodsSplAmt	공급가	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
goodsVat	부가세	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
goodsTaxfreeAmt	면세 금액	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
connCd	접속 타입	Default: userAgent 값을 확인하여 0001/0002 세팅 0001: PC Web 0002: Smartphone		4
ediDate	전문 요청 일시	yyyyMMddHHmmss	Y	14
hashString	해시 String	SHA256 암호화 (mid + ediDate + goodsAmt + 가맹점KEY)	Y	N/A

결제 결과 데이터 필드

승인이 완료되면 결과를 가맹점으로 전달합니다.

필드명	한글 명칭	설명	최대 크기
resultCd	결과 코드	[0000: 정상, 기타: 실패]	4
resultMsg	결과 메세지	결과 메세지	100
tid	거래 아이디	거래 아이디	30
mid	상점 아이디	상점 아이디	21
pmCd	결제 수단 코드	01: 신용카드	2
spmCd	서브 결제 수단 코드	02: 수기(구인증) 05: 수기(비인증)	2
ediDate	전문 요청 일시	yyyyMMddHHmmss	14
ordNo	주문 번호	주문 번호	40
goodsNm	결제 상품명	결제 상품명	100
goodsAmt	거래 금액	결제 결과 금액	15
ordNm	구매자명	결제자 이름	30
mbsReserved	상점 예약 필드	가맹점에서 보낸 데이터 그대로 리턴	500
trxCd	‘0’ 고정	‘0’ 고정	1
trDt	거래일	yyyyMMdd	8
trTm	거래 시간	HHmmss	6
fnNm	발급 카드사명	카드사명	20
cardNo	카드 번호	마스킹된 카드번호	20
appNo	승인 번호	승인 번호	20
appCardCd	카드 발급사 코드	카드 발급사 코드	2
acqCardCd	카드 매입사 코드	카드 매입사 코드	2
quotaMon	카드 할부 개월	할부 개월	2
noIntFlg	무이자 거래 여부	0: 일반 1: 무이자	1
noIntUseFlg	가맹점 무이자 적용 여부	0: 미적용 1: 적용	1
pointFlg	포인트 사용 여부	0: 미사용 1: 사용	1
cardTypeCd	카드 타입 코드	01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	체크 카드 여부	0: 신용 1: 체크 데이터 없으면 공백 리턴	1
receiptUrl	거래명세서 URL	resultCd 값이 ‘0000’ 인 경우에만 리턴	200

코드샘플

                                    
public void keyin() throws IOException, InterruptedException {
    String payMethod = "CARD";  //결제수단
    String mid = "";  //상점 아이디
    String goodsNm = "";  //상품명
    String ordNo = "";  //주문번호
    String goodsAmt = "";  //결제금액
    String ordNm = "";  //구매자명
    String cardTypeCd = "";  //카드타입코드
    String expireYymm = "";  //카드 유효기간
    String quotaMon = "00";  //할부기간
    String ordAuthNo = "";  //카드 인증번호 생년월일(사업자번호)
    String cardPw = "";  //카드 비밀번호 앞 2자리
    String cardNo = "";  //카드번호
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청일시 (yyyyMMddHHmmss 형식)
    String merchantKey = "";  //가맹점KEY
    String hashString = encoding(mid + ediDate + goodsAmt + merchantKey); //SHA256 암호화

    StringBuilder requestData = new StringBuilder();
    requestData.append("payMethod=").append(payMethod).append("&")
            .append("mid=").append(mid).append("&")
            .append("goodsNm=").append(goodsNm).append("&")
            .append("ordNo=").append(ordNo).append("&")
            .append("goodsAmt=").append(goodsAmt).append("&")
            .append("ordNm=").append(ordNm).append("&")
            .append("cardTypeCd=").append(cardTypeCd).append("&")
            .append("expireYymm=").append(expireYymm).append("&")
            .append("quotaMon=").append(quotaMon).append("&")
            .append("ordAuthNo=").append(ordAuthNo).append("&")
            .append("cardNo=").append(cardNo).append("&")
            .append("cardPw=").append(cardPw).append("&")
            .append("ediDate=").append(ediDate).append("&")
            .append("hashString=").append(hashString);

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testpaywin.lightpay.kr/payment/bill/pay"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$payMethod = "CARD";  //결제수단
$mid = "";  //상점 아이디
$goodsNm = "";  //상품명
$ordNo = "";  //주문번호
$goodsAmt = "";  //결제금액
$ordNm = "";  //구매자명
$cardTypeCd = "";  //카드타입코드
$expireYymm = "";  //카드 유효기간
$quotaMon = "";  //할부기간
$ordAuthNo = "";  //카드 인증번호 생년월일(사업자번호)
$cardPw = "";  //카드 비밀번호 앞 2자리
$cardNo = "";  //카드번호
$ediDate = date("YmdHis");  //요청 일시(yyyyMMddHHmmss 형식)
$merchantKey = "";  //가맹점KEY
$hashString = hash("sha256", $mid.$ediDate.$goodsAmt.$merchantKey);  //SHA256 암호화

$data = [
    "payMethod" => $payMethod,
    "mid" => $mid,
    "goodsNm" => $goodsNm,
    "ordNo" => $ordNo,
    "goodsAmt" => $goodsAmt,
    "ordNm" => $ordNm,
    "cardTypeCd" => $cardTypeCd,
    "expireYymm" => $expireYymm,
    "quotaMon" => $quotaMon,
    "ordAuthNo" => $ordAuthNo,
    "cardNo" => $cardNo,
    "cardPw" => $cardPw,
    "ediDate" => $ediDate,
    "hashString" => $hashString
];

$ch = curl_init($approvalUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>


                                

                                    
curl -X POST 'https://testpaywin.lightpay.kr/payment/v1/keyin' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode "payMethod=CARD" \
     --data-urlencode "mid=testmidm" \
     --data-urlencode "goodsNm=테스트상품" \
     --data-urlencode "ordNo=12423243523353" \
     --data-urlencode "goodsAmt=100" \
     --data-urlencode "ordNm=홍길동" \
     --data-urlencode "cardNo=1234123412341234" \
     --data-urlencode "cardTypeCd=01" \
     --data-urlencode "expireYymm=2503" \
     --data-urlencode "quotaMon=00" \
     --data-urlencode "ediDate=20250325103323" \
     --data-urlencode "hashString=47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"


                                

결제 취소

결제 취소 요청 페이지 작성

요청 URL

운영	https://paywin.lightpay.kr/payment/v1/cancel
개발	https://testpaywin.lightpay.kr/payment/v1/cancel

결제 취소 요청 정보

Protocol	Method	Encoding	Content-type
HTTP/1.1	POST	UTF-8	application/x-www-form-urlencoded;
HTTP/1.1	POST	UTF-8	application/json

기본 취소요청데이터 필드

필드명	한글 명칭	설명	필수 여부	최대 크기
tid	거래 아이디	거래 아이디	Y	30
mid	상점 아이디	상점 아이디	Y	21
ordNo	주문 번호	주문 번호		40
ccAmt	취소 금액	숫자만 입력 가능	Y	15
ccId	취소자 아이디	한글/특수기호 입력가능		21
ccNm	취소자명	취소자 이름		30
ccMsg	취소 사유	취소 사유	Y	100
ccIp	취소 아이피	취소 아이피(IPv4, IPv6 지원)		20
partCanFlg	부분 취소 여부	0: 전체취소 1: 부분취소	Y	1
mbsReserved	상점 예약 필드	가맹점에서 보낸 데이터 그대로 리턴		500
ediDate	전문 요청 일시	yyyyMMddHHmmss	Y	14
hashString	해시 String	SHA256 암호화 (mid + ediDate + ccAmt + 가맹점KEY)	Y	N/A
goodsSplAmt	공급가	숫자만 입력 대상: ‘전송금액기준’ 설정업체, 부분취소에 한함		15
goodsVat	부가세	숫자만 입력 대상: ‘전송금액기준’ 설정업체, 부분취소에 한함		15
goodsTaxfreeAmt	면세금액	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15

결제 취소 요청 후 취소결과(responseBody)를 받아 내부처리(DB 저장 등) 하시기 바랍니다.

수신 시 전송 필드명을 명확히하여 처리하시기 바랍니다. (필드명 대/소문자 구분)

결제 취소에 실패하였을 경우 실패시 전달되는 데이터만 전송됩니다.

결제취소 기본 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
resultCd	결과 코드	[0000: 정상, 기타: 실패]	4
resultMsg	결과 메세지	결과 메세지	100
tid	거래 아이디	거래 아이디	30
mid	상점 아이디	상점 아이디	21
trDt	취소일	yyyyMMdd	8
trTm	취소시간	HHmmss	6
trxStCd	거래 상태	0: 승인 1: 전취소 2: 후취소 3: 채번완료 4: 채번취소 9: 망취소	2
pmCd	결제 수단 코드	01: 신용카드 02: 계좌이체 03: 가상계좌 05: 휴대폰 20: 네이버페이 21: 카카오페이 22: 스마일페이 23: 내통장결제 24: 토스페이 25: PAYCO	2
spmCd	서브 결제 수단 코드	신용카드 01: 인증 02: 수기(구인증) 04: 빌링 05: 수기(비인증) 07: 애플페이 나머지 결제 수단 01: 고정	2
ccAmt	거래 금액	결제 취소 결과 금액	15
ordNo	주문 번호	주문 번호	40
otid	원거래 아이디	원거래 아이디	30
partCanFlg	부분 취소 여부	0: 전체취소 1: 부분취소	1
netCanFlg	망취소 여부	0: 일반취소 1: 망취소	1
mbsReserved	상점예약필드	가맹점에서 보낸 데이터 그대로 리턴	500
ediDate	전문 응답 일시	yyyyMMddHHmmss	14
receiptUrl	거래명세서 URL	resultCd 값이 ‘0000’인 경우에만 반환	200

네이버페이 결제취소 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
payNm	주 결제수단	CARD: 카드 BANK: 은행 MONEY: 포인트머니	20
ccPayAmt	주 결제수단 취소금액	거래금액 중 주 결제수단으로 취소 된 금액	15
ccNpointPayAmt	포인트/머니 취소금액	거래금액 중 포인트/머니로 취소 된 금액	15

스마일페이 결제취소 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
discountAmt	프로모션 결제 금액	거래금액 중 취소된 프로모션 결제 금액	15
cashAmt	현금성 금액	거래금액 중 취소된 현금성 금액	15
smileCash	스마일 캐시	거래금액중 취소된 스마일 캐시	15

내통장 결제취소 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
criPrice	현금영수증 금액	현금영수증 발급 가능 금액	15
criTaxVatPrice	현금영수증 과세 금액	현금영수증 과세 금액	15
criDutyFreePrice	현금영수증 비과세 금액	현금영수증 비과세 금액	15
discntPrice	할인 금액	할인 금액	15

PAYCO 결제취소 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
cardAmt	카드 금액	취소된 카드 금액	15
couponAmt	쿠폰 금액 (페이코포인트 금액 포함)	취소된 쿠폰 금액	15
paycoPointAmt	페이코 포인트 금액	취소된 페이코 포인트 금액	15

토스페이 결제취소 추가 응답데이터 필드

필드명	한글 명칭	설명	최대 크기
cashAmt	현금성 금액	취소된 거래금액 중 현금성 사용 금액	15
discountAmt	적립성 포인트	취소된 토스포인트	15

코드샘플

                                    
public void cancel() throws IOException, InterruptedException {
    String tid = "";  //거래 아이디
    String mid = "";  //상점 아이디
    String ccAmt = "";  //취소 금액
    String ccMsg = "";  //취소 사유
    String partCanFlg = "";  //부분 취소 여부
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청일시 (yyyyMMddHHmmss 형식)
    String merchantKey = "";  //가맹점KEY
    String hashString = encoding(mid + ediDate + ccAmt + merchantKey); //SHA256 암호화

    StringBuilder requestData = new StringBuilder();
    requestData.append("tid=").append(tid).append("&")
            .append("mid=").append(mid).append("&")
            .append("ccAmt=").append(ccAmt).append("&")
            .append("ccMsg=").append(ccMsg).append("&")
            .append("partCanFlg=").append(partCanFlg).append("&")
            .append("ediDate=").append(ediDate).append("&")
            .append("hashString=").append(hashString).append("&");

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testpaywin.lightpay.kr/payment/v1/cancel"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$tid = "";  //거래 아이디
$mid = "";  //상점 아이디
$ccAmt = "";  //취소 금액
$ccMsg = "";  //취소 사유
$partCanFlg = "";  //부분 취소 여부
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$merchantKey = "";  //가맹점KEY
$hashString = hash("sha256", $mid.$ediDate.$ccAmt.$merchantKey);  //SHA256 암호화
$url = "https://testpaywin.lightpay.kr/payment/v1/cancel";

$data = [
    "tid" => $tid,
    "mid" => $mid,
    "ccAmt" => $ccAmt,
    "ccMsg" => $ccMsg,
    "partCanFlg" => $partCanFlg,
    "ediDate" => $ediDate,
    "hashString" => $hashString
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testpaywin.lightpay.kr/payment/v1/cancel' \
     --header 'Content-Type: application/json' \
     --data '{"tid":"testmidm010327032558bde59688","mid":"testmidm","ccAmt":"100","partCanFlg":"0","ccMsg":"고객희망","ediDate":"20250325103323","hashString":"47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"}'


                                

망취소 요청

망취소 요청 URL

운영	https://paywin.lightpay.kr/payment/v1/netCancel
개발	https://testpaywin.lightpay.kr/payment/v1/netCancel

결제 취소 요청 정보

Protocol	Method	Encoding	Content-type
HTTP/1.1	POST	UTF-8	application/x-www-form-urlencoded;
HTTP/1.1	POST	UTF-8	application/json

망취소 요청데이터 필드

필드명	한글 명칭	설명	필수 여부	최대 크기
tid	거래 아이디	거래 아이디	Y	30
mid	상점 아이디	상점 아이디	Y	21
ordNo	주문 번호	주문 번호		40
ccAmt	취소 금액	숫자만 입력 가능	Y	15
ccId	취소자 아이디	한글/특수기호 입력가능		21
ccNm	취소자명	취소자 이름		30
ccMsg	취소 사유	취소 사유	Y	100
ccIp	취소 아이피	취소 아이피(IPv4, IPv6 지원)		20
mbsReserved	상점 예약 필드	가맹점에서 보낸 데이터 그대로 리턴		500
ediDate	전문 요청 일시	yyyyMMddHHmmss	Y	14
hashString	해시 String	SHA256 암호화 (mid + ediDate + ccAmt + 가맹점KEY)	Y	N/A
goodsSplAmt	공급가	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
goodsVat	부가세	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
goodsTaxfreeAmt	면세금액	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15

코드샘플

                                    
public void netCancel() throws IOException, InterruptedException {
    String tid = "";  //거래 아이디
    String mid = "";  //상점 아이디
    String ccAmt = "";  //취소 금액
    String ccMsg = "";  //취소 사유
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청일시 (yyyyMMddHHmmss 형식)
    String merchantKey = "";  //가맹점KEY
    String hashString = encoding(mid + ediDate + ccAmt + merchantKey); //SHA256 암호화

    StringBuilder requestData = new StringBuilder();
    requestData.append("tid=").append(tid).append("&")
            .append("mid=").append(mid).append("&")
            .append("ccAmt=").append(ccAmt).append("&")
            .append("ccMsg=").append(ccMsg).append("&")
            .append("ediDate=").append(ediDate).append("&")
            .append("hashString=").append(hashString).append("&");

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testpaywin.lightpay.kr/payment/v1/netCancel"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$tid = "";  //거래 아이디
$mid = "";  //상점 아이디
$ccAmt = "";  //결제 금액
$ccMsg = "";  //취소 사유
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$merchantKey = "";  //가맹점KEY
$hashString = hash("sha256", $mid.$ediDate.$ccAmt.$merchantKey);  //SHA256 암호화
$url = "https://testpaywin.lightpay.kr/payment/v1/netCancel";

$data = [
    "tid" => $tid,
    "mid" => $mid,
    "ccAmt" => $ccAmt,
    "ccMsg" => $ccMsg,
    "ediDate" => $ediDate,
    "hashString" => $hashString
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testpaywin.lightpay.kr/payment/v1/netCancel' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode "tid=testmidm001012503248fa303c674" \
     --data-urlencode "mid=testmidm" \
     --data-urlencode "ccAmt=100" \
     --data-urlencode "ccMsg=고객희망" \
     --data-urlencode "ediDate=20250325103323" \
     --data-urlencode "hashString=47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"


                                

현금영수증

개요

본 문서는 UDID의 지불결제 서비스를 이용하는 가맹점이 UDID에서 제공하는 현금영수증 발급, 조회, 취소를 이용하는 방법을 제공합니다.

과정

현금영수증 발급 정보 입력

사용자는 가맹점이 구성한 웹 페이지에서 현금영수증 발급과 관련된 정보를 입력합니다.

현금영수증 발급 요청, 응답

가맹점은 사용자로부터 전달받은 정보와 가맹점 정보를 가공하여 현금영수증 발급을 요청합니다.

현금영수증 조회 요청, 응답

가맹점은 요청아이디를 포함한 조회 전문을 요청합니다.
조회 응답 값을 가공하여 이후 가맹점 프로세스를 진행합니다.
PG사의 응답데이터는 JSON 기본 포맷으로 응답되며, 기능 추가에 따라 응답 필드가 추가될 수 있습니다. 이에 따라 가맹점에서 응답필드가 추가 될 수 있음을 고려해야 합니다.

주의사항

가맹점에서는 사용자가 입력한 정보가 노출되지 않도록 주의해야합니다.

현금영수증 발급요청

요청 URL

운영	https://paywin.lightpay.kr/crct/v1/regist
개발	https://testpaywin.lightpay.kr/crct/v1/regist

요청 정보

Protocol	Method	Encoding	Content-type
HTTP/1.1	POST	UTF-8	application/x-www-form-urlencoded;
HTTP/1.1	POST	UTF-8	application/json

요청 파라미터

필드명	설명	필수 여부	최대 크기
payMethod	지불 수단(RECEIPT)	Y	N/A
mid	가맹점 아이디	Y	21
ordNo	주문번호 – Unique 한 값	Y	40
goodsNm	상품명(예 : 테스트상품)		100
goodsAmt	결제 금액(예 : 1000)	Y	15
goodsSplAmt	공급가(예 : 0, default : 0, 부가세 설정이 전송금액 기준이면 필수)		15
goodsVat	부가세(예 : 0, default : 0, 부가세 설정이 전송금액 기준이면 필수)		15
goodsSvsAmt	상품 봉사료(예 : 0, default : 0, 부가세 설정이 전송금액 기준이면 필수)		15
ordNm	구매자명(예 : 홍길동)		30
ordTel	구매자 전화번호(예 : 01012341234)		20
ordEmail	구매자 이메일		60
ordIp	구매자 아이피		20
crctReqType	요청구분 0 : 미발행 1 : 소득공제 2 : 지출증빙 3 : 자진발급	Y	2
crctPubType	영수증 발행 구분 1:카드번호 2:주민등록번호 3:사업자번호 4:휴대폰번호	Y	1
crctId	영수증 ID번호 주민등록/사업자/휴대폰/카드번호	Y	20
orgTid	원거래 ID, 결제 + 현금영수증 발급시 결제 거래 TID, 원거래가 없을 수도 있음		30
orgPmCd	원거래지불수단, 결제 + 현금영수증 발급시 결제거래 지불수단, 원거래가 없을 수도 있음		2
orgSpmCd	원거래Sub지불수단,결제 + 현금영수증 발급시 결제거래 SUB지불수단, 원거래가 없을 수도 있음		2
taxType	과세유형 과세: T01 면세: T02 복합과세: T03		3
coNo3p	입점몰 사업자 번호, 입점몰일 경우 필수		10
coNm3p	3P (입점몰) 사업자 상호		100
repNm3p	3P (입점몰) 사업자 대표자명		30
addr3p	3P (입점몰) 사업자 주소		100
telNo3p	3P (입점몰) 사업자 대표 연락처		40
url3p	3P (입점몰) 사업자 입점몰 사이트 주소		100
crctCultFlg	현금영수증 문화비소득공제 0:아니오 1:예		1
mbsUsrId	가맹점고객ID		20
mbsReserved	상점예약필드		500
trDnt	거래일시(yyyyMMddHHmmss)		14
ediDate	전문요청일시(yyyyMMddHHmmss)	Y	14
hashString	SHA256 암호화(mid + ediDate + goodsAmt + 가맹점KEY)	Y	256

입점몰의 사업자번호를 이용해 현금영수증을 발행할 경우 3p관련 파라미터, crctCultFlg 필수 (입점몰 사이트 주소와 입점몰 대표 연락처 정보는 선택입니다.)

거래일시 형식이 지정한 형식과 다를 때, 또는 거래 일시와 현재 일시의 간격이 5일 이상 차이가 발생할 경우 발급요청이 거부됩니다.

입점몰이 아닐 경우 crctCultFlg는 등록된 가맹점 아이디 기준정보로 설정됩니다.

부가세 계산 방법이 전송금액 기준으로 설정된 가맹점이 아닌 경우 공급가와 부가세는 결제 금액을 이용해 자동으로 계산되며, 입력한 공급가와 부가세는 무시됩니다.

응답 파라미터

파라미터	설명	최대 크기 (Byte)
resultCd	결과 코드	4
resultMsg	결과 메세지	100
crctReqTid	현금영수증 요청 아이디	30
mid	상점 아이디	21
ordNo	주문번호 – Unique 한 값	40
appNo	승인 번호	20
pmCd	결제 수단 코드	2
spmCd	결제 수단 Sub 코드	2
goodsAmt	상품 금액	15
goodsSplAmt	공급가	15
goodsVat	부가세	15
goodsSvsAmt	봉사료	15
ediDate	전문 요청 일시	14
mbsReserved	상점 예약 필드	500

appNo는 가 승인번호로 발급요청 결과는 요청일 기준 익일 오전 10시 30분에 발급완료가 됩니다.

코드샘플

                                    
public void crctReg() throws IOException, InterruptedException {
    String merchantKey = "";  //가맹점KEY
    String payMethod = "RECEIPT";  //지불 수단
    String mid = "";  //상점 아이디
    String ordNo = "";  //주문번호
    String crctReqType = "";  //요청구분
    String goodsAmt = "";  //결제금액
    String crctPubType = "";  //영수증 발행 구분영수증 발행 구분
    String crctId = "";  //영수증 ID번호
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청 일시
    String hashString = encoding(mid + ediDate + goodsAmt + merchantKey); //SHA256 암호화

    StringBuilder requestData = new StringBuilder();
    requestData.append("payMethod=").append(payMethod).append("&")
            .append("mid=").append(mid).append("&")
            .append("ordNo=").append(ordNo).append("&")
            .append("crctReqType=").append(crctReqType).append("&")
            .append("goodsAmt=").append(goodsAmt).append("&")
            .append("crctPubType=").append(crctPubType).append("&")
            .append("crctId=").append(crctId).append("&")
            .append("ediDate=").append(ediDate).append("&")
            .append("hashString=").append(hashString);

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testpaywin.lightpay.kr/payment/crct/v1/regist"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$merchantKey = "";  //가맹점KEY
$payMethod = "RECEIPT";  //지불 수단
$mid = "";  //상점 아이디
$ordNo = "";  //주문 번호
$crctReqType = "";  //요청구분
$goodsAmt = "";  //결제금액
$crctPubType = "";  //영수증 발행 구분영수증 발행 구분
$crctId = "";  //영수증 ID번호
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$hashString = hash("sha256", $mid.$ediDate.$goodsAmt.$merchantKey);  //SHA256 암호화
$url = "https://testpaywin.lightpay.kr/crct/v1/regist";

$data = [
    "payMethod" => $payMethod,
    "mid" => $mid,
    "ordNo" => $ordNo,
    "crctReqType" => $crctReqType,
    "goodsAmt" => $goodsAmt,
    "crctPubType" => $crctPubType,
    "crctId" => $crctId,
    "ediDate" => $ediDate,
    "hashString" => $hashString
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testpaywin.lightpay.kr/crct/v1/regist' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode "payMethod=RECEIPT" \
     --data-urlencode "mid=testmidm" \
     --data-urlencode "ordNo=624232423523353" \
     --data-urlencode "goodsAmt=100" \
     --data-urlencode "cardReqType=1" \
     --data-urlencode "crctPubType=4" \
     --data-urlencode "crctId=01011111111" \
     --data-urlencode "ediDate=20250325132615" \
     --data-urlencode "hashString=47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"


                                

현금영수증 조회

요청 URL

운영	https://paywin.lightpay.kr/crct/v1/search
개발	https://testpaywin.lightpay.kr/crct/v1/search

요청 정보

Protocol	HTTP/1.1
Method	POST
Encoding	UTF-8
Content-type	application/json

요청 파라미터 ( type: 0, 단건조회)

파라미터	설명	필수 여부	최대 크기 (Byte)
type	0: 단건조회 1: 다건조회	Y	1
crctReqTid	현금영수증 요청 아이디	Y	30
mid	가맹점 아이디	Y	21
ediDate	전문 요청 일시(yyyyMMddHHmmss)	Y	14
hashString	SHA256 암호화(mid + ediDate + 가맹점KEY)	Y	256

요청 파라미터 ( type: 1, 다건 조회)

파라미터	설명	필수 여부	최대 크기 (Byte)
type	0: 단건조회 1: 다건조회	Y	1
mid	가맹점 아이디	Y	21
regReqFrDt	조회 시작일 (발급요청 일 기준)	Y	8
regReqToDt	조회 종료일 (발급요청 일 기준)	Y	8
ediDate	전문요청일시(yyyyMMddHHmmss)	Y	14
hashString	SHA256 암호화(mid + ediDate + 가맹점KEY)	Y	256

Type1만 dataList Json Array로 응답

응답 파라미터

파라미터	설명	최대 크기
resultCd	결과 코드	4
resultMsg	결과 메시지	100
data	하단 파라미터를 담은 Json 배열입니다. (type 1 인 경우만 존재)
crctReqTid	요청 아이디	30
tid	현금영수증 거래 아이디 (발급 완료 시)	30
crctRegCd	요청 현금영수증 현재 상태 1: 발급 2: 취소 3: 부분취소 재발급	1
crctRegRslt	요청 현금영수증 국세청 처리결과 0:미처리 1:성공 2:실패 3:요청중	1
remainAmt	국세청 발급 잔액 (부분취소 시)	15
crctRsltMsg	국세청 처리결과 메시지 (실패 시)	255
regReqDnt	발급요청 일시	14
regDnt	발급 일시 (발급 성공 시)	14
reqCcDnt	취소요청 일시 (취소 요청 시)	14
ccDnt	취소 일시 (발행 취소 성공 시)	14
mid	상점 아이디	21
gid	그룹 아이디	10
vid	가상그룹 아이디	10
goodsAmt	거래 금액	15
goodsNm	결제 상품명	100
ordNm	구매자명	30
ordTel	구매자 전화번호	20
ordEmail	구매자 이메일	60
orgTid	원거래 ID, 결제+현금영수증 발급시 결제 거래 TID, 원거래 없을 수 있음	30
ordNo	주문번호 – Unique 한 값	40
crctReqType	요청구분 0: 미발행 1: 소득공제 2: 지출증빙 3: 자진발급	2
crctPuybType	영수증 발행 구분영수증 발행 구분 1:카드번호 2:주민등록번호 3:사업자번호 4:휴대폰번호	1
crctId	영수증 ID번호 주민등록/사업자/휴대폰/카드번호	20
coNo3p	입점몰 사업자 번호, 입점몰일 경우 필수	10
coNm3p	3P (입점몰) 사업자 상호	100
repNm3p	3P (입점몰) 사업자 대표자명	30
addr3p	3P (입점몰) 사업자 주소	100
telNo3p	3P (입점몰) 사업자 대표 연락처	40
url3p	3P (입점몰) 사업자 입점몰 사이트 주소	100
crctCultFlg	현금영수증 문화비소득공제 0:아니오 1:예	1
ediDate	전문 요청 일시	14
mbsReserved	상점 예약 필드	500

국세청 완료(발급,취소) 결과는 요청일 기준 익일 오전 10시30분 부터 조회 가능합니다.

코드샘플

                                    
public void crctSearch() throws IOException, InterruptedException {
    String merchantKey = "";  //가맹점KEY
    /* 공통 필수 필드 */
    String type = "0";  //0: 단건조회 | 1:다건조회
    String mid = "";  //상점 아이디
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청일시 (yyyyMMddHHmmss 형식)
    String hashString = encoding(mid + ediDate + merchantKey); //SHA256 암호화

    /* 단건조회시 필수 필드 */
    String crctReqTid = "";  //현금영수증 요청 아이디

    /* 다건조회시 필수 필드 */
    String regReqFrDt = "";  //조회 시작일 (발급요청일 기준)
    String regReqToDt = "";  //조회 종료일 (발급요청일 기준)

    Map<String, String> data = Map.of(
            "type", type,
            "mid", mid,
            "crctReqTid", crctReqTid,
            "ediDate", ediDate,
            "hashString", hashString
    );
    String requestData = new ObjectMapper().writeValueAsString(data);
    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testpaywin.lightpay.kr/crct/v1/search"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$merchantKey = "";  //가맹점KEY
/* 공통 필수 필드 */
$type = "0";  //0: 단건조회 | 1: 다건조회
$mid = "";  //상점 아이디
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$hashString = hash("sha256", $mid.$ediDate.$merchantKey);  //SHA256 암호화

/* 단건조회시 필수 필드 */
$crctReqTid = "";  //현금영수증 요청 아이디

/* 다건조회시 필수 필드 */
$regReqFrDt = "";  //조회시작일 (발급요청일 기준)
$regReqToDt = "";  //조회종료일 (발급요청일 기준)

$url = "https://testpaywin.lightpay.kr/crct/v1/search";
$data = [
    "type" => $type,
    "mid" => $mid,
    "ediDate" => $ediDate,
    "hashString" => $hashString,
    "crctReqTid" => $crctReqTid
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testpaywin.lightpay.kr/crct/v1/search' \
     --header 'Content-Type: application/json' \
     --data '{"type":"0","crctReqTid":"testmidm04012401166118258006","mid":"testmidm","ediDate":"20250325131918","hashString":"47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"}'


                                

현금영수증 취소 (요청전: 요청취소, 요청완료: 발행취소)

요청 URL

운영	https://paywin.lightpay.kr/payment/v1/cancel
개발	https://testpaywin.lightpay.kr/payment/v1/cancel

요청 정보

Protocol	Method	Encoding	Content-type
HTTP/1.1	POST	UTF-8	application/x-www-form-urlencoded;
HTTP/1.1	POST	UTF-8	application/json

요청 파라미터

필드명	한글 명칭	설명	필수 여부	최대 크기
tid	거래 아이디	거래 아이디 (현금영수증 발급 요청 아이디: crctReqTid)	Y	30
mid	상점 아이디	상점 아이디	Y	21
ccAmt	취소 금액	숫자만 입력 가능	Y	15
ccId	취소자 아이디	한글/특수기호 입력가능		21
ccNm	취소자명	취소자 이름		30
ccMsg	취소 사유	취소 사유	Y	100
ccIp	취소 아이피	취소 아이피(IPv4, IPv6 지원)		20
partCanFlg	부분 취소 여부	0: 전체취소 1: 부분취소	Y	1
mbsReserved	상점 예약 필드	가맹점에서 보낸 데이터 그대로 리턴		500
ediDate	전문 요청 일시	yyyyMMddHHmmss	Y	14
hashString	해시 String	SHA256 암호화 (mid + ediDate + ccAmt + 가맹점KEY)	Y	N/A
goodsSplAmt	공급가	숫자만 입력 대상: ‘전송금액기준’ 설정업체, 부분취소에 한함		15
goodsVat	부가세	숫자만 입력 대상: ‘전송금액기준’ 설정업체, 부분취소에 한함		15
goodsSvsAmt	상품 봉사료	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15

응답 파라미터

파라미터	설명	최대 크기 (Byte)
resultCd	결과 코드 0000 : 정상 기타 : 실패	4
resultMsg	결과 메시지 성공시 : 정상처리 실패시 : 기타 오류 메시지	100
crctReqTid	현금영수증 요청 아이디	30
mid	상점 아이디	21
pmCd	결제 수단 코드 (04: 현금영수증)	2
spmCd	결제 수단 Sub 코드 01: 고정	2
ccAmt	취소 금액	15
ordNo	주문 번호	40
partCanFlg	부분 취소 여부 0:전체취소 1:부분취소	1
crctReqRslt	현금영수증 처리결과 0:미처리 1:성공 2:실패	1
appNo	취소 승인번호	20
mbsReserved	상점 예약 필드	500
ediDate	전문 요청 일시 (yyyyMMddHHmmss)	14

국세청 요청전(요청 취소) 일 경우 발급요청 응답의 appNo와 취소 응답의 appNo는 동일합니다.
국세청 요청완료(발행 취소) 일 경우 발급요청 응답의 appNo와 취소 응답의 appNo는 상이합니다.

코드샘플

                                    
public void cancel() throws IOException, InterruptedException {
    String tid = "";  //거래 아이디
    String mid = "";  //상점 아이디
    String ccAmt = "";  //취소 금액
    String ccMsg = "";  //취소 사유
    String partCanFlg = "";  //부분 취소 여부
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청일시 (yyyyMMddHHmmss 형식)
    String merchantKey = "";  //가맹점KEY
    String hashString = encoding(mid + ediDate + ccAmt + merchantKey); //SHA256 암호화

    StringBuilder requestData = new StringBuilder();
    requestData.append("tid=").append(tid).append("&")
            .append("mid=").append(mid).append("&")
            .append("ccAmt=").append(ccAmt).append("&")
            .append("ccMsg=").append(ccMsg).append("&")
            .append("partCanFlg=").append(partCanFlg).append("&")
            .append("ediDate=").append(ediDate).append("&")
            .append("hashString=").append(hashString).append("&");

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testpaywin.lightpay.kr/payment/v1/cancel"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$tid = "";  //거래 아이디
$mid = "";  //상점 아이디
$ccAmt = "";  //취소 금액
$ccMsg = "";  //취소 사유
$partCanFlg = "";  //부분 취소 여부
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$merchantKey = "";  //가맹점KEY
$hashString = hash("sha256", $mid.$ediDate.$ccAmt.$merchantKey);  //SHA256 암호화
$url = "https://testpaywin.lightpay.kr/payment/v1/cancel";

$data = [
    "tid" => $tid,
    "mid" => $mid,
    "ccAmt" => $ccAmt,
    "ccMsg" => $ccMsg,
    "partCanFlg" => $partCanFlg,
    "ediDate" => $ediDate,
    "hashString" => $hashString
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testpaywin.lightpay.kr/payment/v1/cancel' \
     --header 'Content-Type: application/json' \
     --data '{"tid":"testmidm010327032558bde59688","mid":"testmidm","ccAmt":"100","partCanFlg":"0","ccMsg":"고객희망","ediDate":"20250325103323","hashString":"47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"}'


                                

거래요청

개요

SMS 결제 요청 API를 사용하면, 가맹점은 구매자의 정보와 결제 정보를 입력하고 결제 요청을 진행할 수 있습니다. 이 과정에서 API는 결제를 수행할 URL과 해당 URL의 QR 코드를 생성하여 반환합니다. 또한, 선택적으로 구매자에게 결제 링크를 포함한 SMS를 전송할 수 있습니다.

결제 요청

결제 요청 URL

운영	https://mms.lightpay.kr/api/v1/payreq
개발	https://testmms.lightpay.kr/api/v1/payreq

결제 요청 정보

Protocol	Method	Encoding	Content-type
HTTP/1.1	POST	UTF-8	application/x-www-form-urlencoded;
HTTP/1.1	POST	UTF-8	application/json

SMS 결제 요청 파라미터

필드명	한글 명칭	설명	필수 여부	최대 크기
payType	결제 수단	AUTH : 인증 결제 – 신용카드 KEYIN : 수기 결제 (구인증) – 신용카드 NONE : 수기 결제 (비인증) – 신용카드 APPLEPAY : 애플페이 – 신용카드 NPAY : 네이버페이 KAKAOPAY : 카카오페이 SMILEPAY : 스마일페이 MYACCOUNT : 내통장결제 TRANS : 계좌이체 VACNT : 가상계좌 MOBILE : 휴대폰결제 PAYCO : 페이코 TOSSPAY : 토스페이	Y	10
mid	상점 아이디	상점 아이디	Y	21
goodsNm	상품명	상품 이름	Y	100
ordNo	주문 번호	Unique한 값	Y	40
goodsAmt	결제 금액	숫자만 입력 가능	Y	15
reqMent	결제 요청 문구	SMS로 발송되는 문구를 입력 ‘결제하기’ 앞에 붙을 내용으로, 빈값이 넘어오면 가맹점명을 기본으로 사용		30
ordNm	구매자명	한글/특수기호 입력가능	Y	30
rcvrTel	구매자 전화번호	숫자만 허용 (SMS 전송 시 해당 번호로 결제 링크 전송)		20
rcvrTel	구매자 전화번호	숫자만 허용 (SMS 전송 시 해당 번호로 결제 링크 전송) sendSms 옵션이 true인 경우에는 반드시 입력되어야 함 길이는 10~11 자리		20
goodsSplAmt	공급가	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
goodsVat	부가세	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
goodsTaxfreeAmt	면세금액	숫자만 입력 대상: ‘전송금액기준’ 설정업체에 한함		15
mbsReserved	가맹점 예약 필드	가맹점 예약필드에 입력한 값은 결제확인 API 및 결제통보를 통해서 확인이 가능합니다.		200
ediDate	전문 요청 일시	yyyyMMddHHmmss	Y	14
hashString	해시 String	SHA256 암호화 (mid + ediDate + goodsAmt + 가맹점KEY)	Y	N/A
limitDate	결제 기한 일자	yyyyMMdd	Y	8
limitTime	결제 기한 시간	HH (00 ~ 23 사이 2자리 숫자만 허용)	Y	2
sendSms	SMS 전송 유무	전송: true 전송하지 않음: false (기본값 false)		N/A
appqr	앱 실행 QR 생성	true인 경우 sendSms 파라미터를 무시하고 SMS 미발송		N/A
returnUrl	URL	결제 완료 후 이동할 URL		200
resultUrl	결과 후 이동 URL	라이트페이 결제 완료 화면에서 이동할 URL적용 (PC 결제 화면만 적용) ※URL 형식이 아닐 경우, 공백처리		N/A

계약되지 않은 결제수단(payType)을 입력할 경우 구매자 거래 과정에서 오류가 발생할 수 있습니다. 참고 바랍니다.

SMS 결제요청 성공 시 응답 파라미터

필드명		한글 명칭	설명	최대 크기
result		결과 여부	결과 성공 실패 여부 (true, false)	N/A
code		결과 코드	[0000: 정상, 기타: 실패]	10
message		결과 메세지	결과 메세지	100
data	rid	결제 요청 아이디	결제 요청 아이디 (현재는 12자 고정이나, 추후 늘어날 수도 있음)	12
	smsPayUrl	결제 URL	결제 URL (SMS 전송 유무가 true인 경우에만 URL 반환)	N/A
	smsPayQRCodeUrl	SMS 결제 QR 코드 URL	appqr 파라미터가 true인 경우 - 라이트페이 결제 앱 기동을 위한 QR URL appqr 파라미터가 false인 경우 - 결제요청 URL 데이터의 QR Code 페이지 URL	N/A

SMS 결제요청 실패 시 응답 파라미터

필드명	한글 명칭	설명	최대 크기
result	결과 여부	결과 성공 실패 여부 (true, false)	N/A
code	결과 코드	[0000: 정상, 기타: 실패]	10
message	결과 메세지	결과 메세지	100
data	상세 에러 내역	문자열 리스트 형태의 에러 상세내역 반환 Ex) [ “limitTime : 0 ~ 23 사이 숫자만 가능합니다” ]	100

코드샘플

                                    
public void payReq() throws IOException, InterruptedException {
    String merchantKey = "";  //가맹점KEY
    String payType = "";  //결제 수단
    String mid = "";  //상점 아이디
    String goodsNm = "";  //상품명
    String ordNo = "";  //주문 번호
    String goodsAmt = "";  //결제 금액
    String ordNm = "";  //구매자명
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청일시 (yyyyMMddHHmmss 형식)
    String limitDate = "";  //결제 기한 일자 (yyyyMMdd 형식)
    String limitTime = "";  //결제 기한 시간 (HH 형식)
    String hashString = encoding(mid + ediDate + goodsAmt + merchantKey); //SHA256 암호화

    Map<String, String> data = new HashMap<>();
    data.put("payType", payType);
    data.put("mid", mid);
    data.put("goodsNm", goodsNm);
    data.put("ordNo", ordNo);
    data.put("goodsAmt", goodsAmt);
    data.put("ordNm", ordNm);
    data.put("ediDate", ediDate);
    data.put("limitDate", limitDate);
    data.put("limitTime", limitTime);
    data.put("hashString", hashString);
    String requestData = new ObjectMapper().writeValueAsString(data);

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testmms.lightpay.kr/api/v1/payreq"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData))
            .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$merchantKey = "";  //가맹점KEY
$payType = "";  //결제 수단
$mid = "";  //상점 아이디
$goodsNm = "";  //상품명
$ordNo = "";  //주문 번호
$goodsAmt = "";  //결제 금액
$ordNm = "";  //구매자명
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$limitDate = "";  //결제 기한 일자 (yyyyMMdd 형식)
$limitTime = "";  //결제 기한 시간 (HH 형식)
$hashString = hash("sha256", $mid.$ediDate.$goodsAmt.$merchantKey);  //SHA256 암호화
$url = "https://testmms.lightpay.kr/api/v1/payreq";

$data = [
    "payType" => $payType,
    "mid" => $mid,
    "goodsNm" => $goodsNm,
    "ordNo" => $ordNo,
    "goodsAmt" => $goodsAmt,
    "ordNm" => $ordNm,
    "ediDate" => $ediDate,
    "limitDate" => $limitDate,
    "limitTime" => $limitTime,
    "hashString" => $hashString
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testmms.lightpay.kr/api/v1/payreq' \
     --header 'Content-Type: application/json' \
     --data '{"payType":"AUTH","goodsNm":"테스트상품","mid":"testmidm","goodsAmt":"100","ordNo":"3150982309423","ordNm":"홍길동","ediDate":"20250325134223","hashString":"47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c","limitDate":"20250326","limitTime":"00"}'


                                

결제 수단 변경 요청

라이트페이 결제수단 변경 요청 URL

운영	https://mms.lightpay.kr/api/v1/changepm
개발	https://testmms.lightpay.kr/api/v1/changepm

요청 정보

Protocol	HTTP/1.1
Method	POST
Encoding	UTF-8
Content-type	application/x-www-form-urlencoded;

요청 파라미터

필드명	한글 명칭	설명	필수 여부	최대 크기
rid	결제 요청 아이디	결제 요청 아이디	Y	12
pmethod	변경할 결제수단	QR : 신용카드 NPAY : 네이버페이 KAKAOPAY : 카카오페이 SMILEPAY : 스마일페이 TRANS : 계좌이체 VACNT : 가상계좌 MOBILE : 휴대폰 MYACCOUNT : 내통장결제 PAYCO : 페이코 TOSSPAY : 토스페이	Y	10
mid	가맹점 아이디	가맹점 아이디	Y	21
reqDnt	요청일시	yyyyMMddHHmmss	Y	14
hashString	검증 해시	SHA256(mid + reqDnt + 가맹점 키)	Y	64

응답 파라미터

필드명	한글 명칭	설명	최대 크기
result	결과 여부	결과 성공 실패 여부 (true, false)	N/A
code	결과 코드	[0000: 정상, 기타: 실패]	10
message	결과 메세지	결과 메세지	100
date	요청 처리 시간

코드샘플

                                    
public void change() throws IOException, InterruptedException {
    String merchantKey = "";  //가맹점KEY
    String rid = "";  //결제 요청 아이디
    String mid = "";  //상점 아이디
    String pmethod = "";  //변경할 결제수단
    String reqDnt = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청 일시(yyyyMMddHHmmss 형식)
    String hashString = encoding(mid + reqDnt + merchantKey); //SHA256 암호화
    StringBuilder requestData = new StringBuilder();
    requestData.append("rid=").append(rid).append("&")
            .append("pmethod=").append(pmethod).append("&")
            .append("mid=").append(mid).append("&")
            .append("reqDnt=").append(reqDnt).append("&")
            .append("hashString=").append(hashString);

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testmms.lightpay.kr/api/v1/changepm"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$merchantKey = "";  //가맹점KEY
$mid = "";  //상점 아이디
$rid = "";  //결제 요청 아이디
$pmethod = "";  //변경할 결제수단
$reqDnt = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$hashString = hash("sha256", $mid . $reqDnt . $merchantKey);  //SHA256 암호화

$url = "https://testmms.lightpay.kr/ap1/v1/changepm";
$data = [
    "rid" => $rid,
    "pmethod" => $pmethod,
    "mid" => $mid,
    "reqDnt" => $reqDnt,
    "hashString" => $hashString
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testmms.lightpay.kr/api/v1/changepm' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode "rid=JZGBgEtwXbOe" \
     --data-urlencode "mid=testmidm" \
     --data-urlencode "pmethod=QR" \
     --data-urlencode "reqDnt=20250325135020" \
     --data-urlencode "hashString=47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"


                                

라이트페이 앱 기동 요청

라이트페이 결제 앱 기동 요청 URL

운영	https://mms.lightpay.kr/sdk-app
개발	https://testmms.lightpay.kr/sdk-app

요청 정보

Protocol	HTTP/1.1
Method	GET
Encoding	UTF-8
Content-type	application/x-www-form-urlencoded;

SMS 결제 요청 파라미터

필드명	한글 명칭	설명	필수 여부	최대 크기
rid	결제 요청 아이디	결제 요청 아이디 (현재는 12자 고정이나 추후 늘어날 수도 있음)	Y	12

라이트페이 결제 앱 기동 요청 성공 시 응답 파라미터

appqr 파라미터가 true인 경우

필드명		한글 명칭	설명	최대 크기
result		결과 여부	결과 성공 실패 여부 (true, false)	N/A
code		결과 코드	[0000: 정상, 기타: 실패]	10
message		결과 메세지	결과 메세지	100
data	rid	결제 요청 아이디	결제 요청 아이디 (현재는 12자 고정이나, 추후 늘어날 수도 있음)	12
	mid	가맹점 아이디	가맹점 아이디	21
	ordNo	주문번호	주문번호	40
	ordNm	주문자명	주문자명	30
	ordHp	주문자 휴대폰	주문자 휴대폰	20
	ordTel	주문자 전화번호	주문자 전화번호	20
	goodsNm	상품명	상품명	100
	goodsAmt	상품가격	상품가격	15
	goodsSplAmt	공급가	공급가	15
	goodsVat	부가세	부가세	15
	goodsSvs	공급가	deprecated	15
	goodsTaxfreeAmt	면세금액	면세금액	15
	quotaMon	할부개월	일시불은 00 또는 01	2
	payType	인증 형태	01: 인증 02: 수기(구인증) 05: 수기(비인증) 07: 애플페이	2
	mbsReserved	가맹점 예약필드	가맹점 예약필드	500
	smsPayQRCodeUrl	SMS 결제 QR 코드 URL	결제요청 URL 데이터의 QR Code 페이지 URL	200

코드샘플

                                    
public void sdkApp() throws IOException, InterruptedException {
    String rid = "";  //결제 요청 아이디

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testmms.lightpay.kr/sdk-app"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("GET", HttpRequest.BodyPublishers.ofString("rid=" + rid))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}


                                

                                    
<?php
$rid = "";  //결제 요청 아이디
$url = "https://testmms.lightpay.kr/sdk-app?rid=$rid";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X GET 'https://testmms.lightpay.kr/sdk-app' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode "rid=JZGBgEtwXbOe"

                                

결제 확인

결제 확인 URL

운영	https://mms.lightpay.kr/api/v1/paychk
개발	https://testmms.lightpay.kr/api/v1/paychk

요청 정보

Protocol	Method	Encoding	Content-type
HTTP/1.1	POST	UTF-8	application/x-www-form-urlencoded;
HTTP/1.1	POST	UTF-8	application/json

SMS 결제 요청 파라미터

필드명	한글 명칭	설명	필수 여부	최대 크기
rid	결제 요청 아이디	결제 요청 아이디 (현재는 12자 고정이나 추후 늘어날 수도 있음)	Y	12
mid	상점 아이디	상점 아이디	Y	21
hashString	해시 String	SHA256 암호화 (mid + rid + 가맹점KEY)	Y	N/A

결제 확인 요청 성공 시 응답 파라미터

appqr 파라미터가 true인 경우

필드명		한글 명칭	설명	최대 크기
result		결과 여부	결과 성공 실패 여부 (true, false)	N/A
code		결과 코드	[0000: 정상, 기타: 실패]	10
message		결과 메세지	결과 메세지	100
data	rid	결제 요청 아이디	결제 요청 아이디 (현재는 12자 고정이나, 추후 늘어날 수도 있음)	12
	mid	가맹점 아이디	가맹점 아이디	21
	mbsReserved	가맹점 예약필드	가맹점 예약필드	500
	reqStCd	요청상태	R: 결제요청 대기 0: 결제요청 1: 결제재요청 2: 요청취소 3: 삭제 4: 인증완료 (인증 요청 시) 9: 결제완료 10: 결제취소	2

코드샘플

                                    
public void payChk() throws IOException, InterruptedException {
    String rid = "";  //결제 요청 아이디
    String mid = "";  //상점 아이디
    String merchantKey = "";  //가맹점KEY
    String hashString = encoding(mid + rid + merchantKey);  //SHA256 암호화

    StringBuilder requestData = new StringBuilder();
    requestData.append("rid=").append(rid).append("&")
            .append("mid=").append(mid).append("&")
            .append("hashString=").append(hashString);

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testmms.lightpay.kr/api/v1/paychk"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData.toString()))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$merchantKey = "";  //가맹점KEY
$mid = "";  //상점 아이디
$rid = "";  //결제 요청 아이디
$hashString = hash("sha256", $mid.$rid.$merchantKey);  //SHA256 암호화

$data = [
    "mid" => $mid,
    "rid" => $rid,
    "hashString" => $hashString
];
$url = "https://testmms.lightpay.kr/api/v1/paychk?" . http_build_query($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/x-www-form-urlencoded"]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testmms.lightpay.kr/api/v1/paychk' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode "rid=JZGBgEtwXbOe" \
     --data-urlencode "mid=testmidm" \
     --data-urlencode "hashString=47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"


                                

거래 영수증

거래 영수증 URL

운영	https://mms.lightpay.kr/receipt/{거래아이디}/{거래상태}/view
개발	https://testmms.lightpay.kr/receipt/{거래아이디}/{거래상태}/view

거래 상태는 승인의 경우 ‘0’, 취소의 경우 ‘2’를 입력합니다.

Ex) https://testmms.lightpay.kr/receipt/tid000..../0/view
→ 승인거래 영수증 화면 표시

Ex) https://testmms.lightpay.kr/receipt/tid000.../2/view
→ 취소 거래 영수증 화면 표시

결제 확인 요청 정보

필드명	한글 명칭	설명	필수 여부	최대 크기
qr	영수증 QR	1인 경우 영수증 QR코드를 영수증 화면 하단에 표시한다.		1
save	영수증 저장 버튼	1인 경우 영수증 저장 버튼을 화면 하단에 표시한다. 저장 버튼 클릭 시 영수증을 이미지로 변환하여 다운로드한다.		1

Ex) https://testmms.lightpay.kr/receipt/tid000.../0/view?qr=1
→ QR 코드가 포함된 영수증 표시

Ex) https://testmms.lightpay.kr/receipt/tid000.../0/view?save=1
→ 영수증 화면 하단에 저장 버튼 표시

결제통보

개요

본 문서는 UDID의 지불결제 서비스를 이용하는 가맹점이 UDID에서 제공하는 결제 결과 데이터를 URL로 전달 받는 방법을 제공합니다.

과정

가맹점은 UDID에서 제공하는 결제 결과 데이터를 받기 위한 URL을 가맹점 관리 페이지에 등록합니다.
결제가 이루어지면 UDID는 결과 데이터를 1분 단위로 가맹점에 통보합니다.
결과 데이터를 정상 수신한 이후 가맹점 프로세스를 진행합니다.

주의사항

가맹점에 결제 데이터 통보 이후 UDID에서 통보 정상 수신에 대한 응답을 확인하지 못 할 경우 송신 실패로 처리합니다.

방화벽 설정

프로토콜	연결대상	연결방향
HTTPS	175.119.158.112	INBOUND
HTTPS	175.119.158.98	OUTBOUND

예외처리

결제 데이터 통보 수신 시 주의사항

URL 유효성 검증

결제 결과 데이터를 수신할 URL이 유효하지 않은 경우 결제 통보가 정상적으로 진행되지 않습니다.
(URL 접근 시 http status 값이 200이 아닌 다른 값(404, 500 등) 발생

호출 오류

방화벽 설정이 정상인지 확인

통보 실패

통보 실패가 발생하는 경우 기술담당자 메일로 통보 실패 사유를 전달합니다.

결제 데이터 통보 URL 설정

가맹점 관리자 페이지 접속

https://mms.lightpay.kr > 로그인 > 가맹점정보 > 결제환경 설정 > 결제결과 통보관리

결제 데이터 통보 항목

결제 데이터 통보 상세 설명

지불수단: 결제 데이터 통보를 수신할 결제 수단의 종류입니다.
시작일자: 설정한 당일의 날짜로 지정됩니다.
URL: 결제 결과 데이터를 수신할 URL을 입력합니다.
인코딩방식: UTF-8, EUC-KR 중 하나를 선택합니다.
메시지타입: JSON, XML, Query String 중 하나를 선택합니다.
재전송간격: 결제 데이터 통보 실패 시점에서 다음 통보 간격을 입력합니다. (최대 60분)
재전송횟수: 최초 결제 데이터 통보 실패 이후 재통보할 횟수를 입력합니다. (최대 10회)
초기화: URL, 인코딩방식, 메시지타입, 재전송간격, 재전송횟수를 초기화합니다.
저장: 변경 사항을 저장합니다.

통보 재전송 기준

가맹점으로 통보 송신 후 HTTP Return Status 응답이 200이 아닌 경우, 설정한 기준에 따라 재전송 처리합니다.

결제 데이터 통보 파라미터

결제 데이터 통보 전문 예시

응답전문은 name=value 형태의 쿼리 문자열 형식 (Content-Type: application/x-www-form-urlencoded)으로 호출합니다.
JSON (application/json) 또는 XML (application/xml) 형식으로 호출을 원하시면 제휴사업부를 통해 요청하시기 바랍니다.
인코딩 방식을 설정하지 않는 경우 UTF-8을 기본으로 사용합니다.
HTTP 메소드는 POST 를 기본으로 사용합니다. GET 방식의 호출이 필요한 경우 제휴사업부를 통해 요청하시기 바랍니다.

결제 공통 데이터

파라미터	설명	최대 크기
resultCd	[0000: 정상, 기타: 실패]	4
resultMsg	결과 메시지	100
tid	거래 아이디	30
mid	상점 아이디	21
pmCd	결제 수단 코드 01: 신용카드 02: 계좌이체 03: 가상계좌 05: 휴대폰 20: 네이버페이 21: 카카오페이 22: 스마일페이 23: 내통장결제 24: 토스페이 25: PAYCO	2
spmCd	서브 결제 수단 코드 신용카드 01: 인증 02: 수기(비인증) 03: 오프라인 04: 빌링 05: 수기(구인증) 07: 애플페이 나머지 결제 수단 01: 고정	2
ediDate	전문 생성 일시(yyyyMMddHHmmss)	14
ordNo	주문번호	40
goodsNm	결제 상품명	100
goodsAmt	결제 결과 금액	15
ordNm	결제자 이름	30
mbsReserved	상점에서 보낸 데이터 그대로 리턴	500
trxCd	‘0’ 고정	1
trDt	거래일(yyyyMMdd)	8
trTm	거래시간(HHmmss)	6

신용카드 결제 추가 데이터

파라미터	설명	최대 크기
fnNm	카드사명	20
cardNo	마스킹된 카드번호	20
appNo	승인 번호	20
appCardCd	카드 발급사 코드	2
acqCardCd	카드 매입사 코드	2
quotaMon	카드 할부개월(예: 00, 02, 03, …, 12, 두자리)	2
noIntUseFlg	가맹점 무이자 적용 여부 0: 미적용 1: 적용	1
pointFlg	포인트 사용 여부 0: 미사용 1: 사용	1
cardTypeCd	카드 타입 코드 01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	체크카드 여부 0: 신용 1: 체크 데이터 없으면 공백 리턴	1

계좌이체 추가 데이터

파라미터	설명	최대 크기
bankNm	은행명	20
bankCd	은행 코드	4
crctReqType	현금영수증 요청타입 0: 미발행 1: 소득공제 2: 지출증빙	1

가상계좌 입금통보 추가 데이터

파라미터	설명	최대 크기
fnNm	은행명	20
bankCd	은행 코드	4
vacntNo	가상계좌 번호	20
crctReqType	현금영수증 요청타입 0: 미발행 1: 소득공제 2: 지출증빙	1

네이버페이 추가 데이터

파라미터	설명	최대 크기
payNm	CARD: 카드 BANK: 은행 MONEY: 포인트머니	20
cardNm	카드사명	20
cardNo	마스킹된 카드번호	50
appNo	승인 번호	30
cardCd	카드 코드 (카드사 코드표 참조)	2
quotaMon	할부 기간(예: 00, 02, 03, …, 12, 두자리)	2
bankNm	은행명	20
bankCd	은행 코드 (은행코드표 참조)	4
bankNo	마스킹 된 계좌 번호	50
payAmt	거래금액 중 주 결제수단으로 결제 된 금액	15
npointPayAmt	거래금액 중 포인트/머니로 결제 된 금액	15

카카오페이 추가 데이터

파라미터	설명	최대 크기
fnNm	카드사명 (카카오머니인 결제인 경우 카카오머니 표시)	20
cardNo	마스킹된 카드 번호(카드 결제 시)	20
appNo	승인 번호	20
appCardCd	카드 발급사 코드	2
acqCardCd	카드 매입사 코드	2
quotaMon	카드 할부개월(예: 00, 02, 03, …, 12, 두자리)	2
cardTypeCd	카드 타입 코드 01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	체크카드 여부 0: 신용 1: 체크 데이터 없으면 공백 리턴	1
pointFlg	카카오페이 포인트 사용 여부 0: 미사용 1: 사용	1
crctReqType	현금영수증 요청타입 0: 미발행 1: 소득공제 2: 지출증빙	1

스마일페이 추가 데이터

파라미터	설명	최대 크기
fnNm	카드사명 (스마일 캐시인 결제인 경우 스마일 캐시 표시)	20
cardNo	마스킹된 카드 번호 (카드 결제 시)	20
appNo	승인 번호	20
appCardCd	카드 발급사 코드	2
acqCardCd	카드 매입사 코드	2
quotaMon	카드 할부개월 (예: 00, 02, 03, …, 12, 두자리)	2
cardTypeCd	카드 타입 코드 01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	체크카드 여부 0: 신용 1: 체크 데이터 없으면 공백 리턴	1
smileCash	스마일 캐시 사용 금액	15
cashAmt	현금성 금액 (스마일 캐시도 현금성과, 포인트성이 나뉘는 방식)	15
discountAmt	프로모션 할인 금액	15

토스페이 추가 데이터

파라미터	설명	최대 크기
fnNm	카드사명 (토스페이 계좌결제인경우는 토스페이로 표시)	20
cardNo	마스킹된 카드 번호 (카드 결제 시)	20
appNo	승인 번호	20
appCardCd	카드 발급사 코드	2
acqCardCd	카드 매입사 코드	2
quotaMon	카드 할부개월 (예: 00, 02, 03, …, 12, 두자리)	2
cardTypeCd	카드 타입 코드 01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	체크카드 여부 0: 신용 1: 체크 데이터 없으면 공백 리턴	1
crctReqType	현금영수증 요청타입 0: 미발행 1: 소득공제 2: 지출증빙	1
cashAmt	현금성 결제 금액 (토스 계좌 결제금액)	15
discountAmt	토스 포인트 (적립성 금액)	15

휴대폰 추가 데이터

파라미터	설명	최대 크기
telNm	통신사명	20
telCd	통신사코드	4
phoneNo	마스킹된 휴대폰 번호	11

내통장결제 추가 데이터

파라미터	설명	최대 크기
crctReqType	현금영수증 요청타입 0: 미발행 1: 소득공제 2: 지출증빙	1

PAYCO 추가 데이터

파라미터	설명	최대 크기
cardAmt	카드금액	15
couponAmt	쿠폰금액 (페이코포인트 금액 포함)	15
paycoPointAmt	페이코포인트 금액	15

결제 데이터 (오프라인)

파라미터	설명	최대 크기
resultCd	결과 코드 [0000: 정상, 기타: 실패]	4
resultMsg	결과 메시지	100
tid	거래 아이디	30
mid	상점 아이디	21
pmCd	결제 수단 코드(01: 신용카드)	2
spmCd	서브 결제 수단 코드(03: 오프라인)	2
ediDate	전문 생성 일시(yyyyMMddHHmmss)	14
ordNo	주문번호	40
goodsNm	결제 상품명	100
goodsAmt	결제 결과 금액	15
ordNm	결제자 이름	30
mbsReserved	상점에서 보낸 데이터 그대로 리턴	500
trxCd	‘0’ 고정	1
trDt	거래일(yyyyMMdd)	8
trTm	거래시간(HHmmss)	6
fnNm	카드사명	20
cardNo	마스킹된 카드번호	20
appNo	승인 번호	20
appCardCd	카드 발급사 코드	2
acqCardCd	카드 매입사 코드	2
quotaMon	카드 할부개월(예: 00, 02, 03, …, 12, 두자리)	2
noIntFlg	무이자여부 0: 일반 1: 무이자	1
pointFlg	포인트사용여부 0: 미사용 1: 사용	1
cardTypeCd	카드 타입 코드 01: 개인 02: 법인 데이터 없으면 공백 리턴	2
chkcardFlg	체크카드여부 0: 신용 1: 체크 데이터 없으면 공백 리턴	1

취소 데이터

파라미터	설명	최대 크기
resultCd	결과 코드 [0000: 정상, 기타: 실패]	4
resultMsg	결과 메시지	100
tid	거래 아이디	30
mid	상점 아이디	21
trDt	취소일(yyyyMMdd)	8
trTm	취소시간(HHmmss)	6
trxStCd	거래 상태 코드 0: 승인 1: 전취소 2: 후취소 3: 채번완료 4: 채번취소 9: 망취소	2
pmCd	결제 수단 코드 01: 신용카드 02: 계좌이체 03: 가상계좌 05: 휴대폰 20: 네이버페이 21: 카카오페이 22: 스마일페이 23: 내통장결제 24: 토스페이 25: PAYCO	2
spmCd	서브 결제 수단 코드 신용카드 01: 인증 02: 수기(구인증) 03: 오프라인 04: 빌링 05: 수기(비인증) 07: 애플페이 나머지 결제 수단 01: 고정	2
ccAmt	결제 취소 결과 금액	15
ordNo	주문 번호	40
otid	원거래 아이디	30
partCanFlg	부분 취소 여부 0: 전체취소 1: 부분취소	1
netCanFlg	망취소 여부 0: 일반취소 1: 망취소	1
mbsReserved	상점에서 보낸 데이터 그대로 리턴	500
ediDate	전문 생성 일시(yyyyMMddHHmmss)	14

결제 데이터 통보 재전송

가맹점에서 결제 데이터 통보를 받지 못하였거나, 이전 성공한 내역에 대해 다시 통보를 받고 싶을 경우 가맹점 관리자 페이지를 통해 재통보가 가능합니다.

결제 데이터 통보 재전송 방법

https://mms.lightpay.kr 가맹점 관리자 로그인 > 결제내역 > 결제내역 조회 > 결제통보 조회 > 거래 선택 > 재전송

주의사항

결제 데이터 통보 재전송은 결제(취소) 시간 기준으로 24시간 이내에 전송할 수 있습니다.

대사

개요

본 문서는 UDID의 지불결제 서비스와 가맹점간의 대사 요청 및 결과 데이터를 반환하는 방법에 대해 설명합니다.

주의사항

API 호출 시 다음과 같은 제약이 존재합니다.

IP + mid 및 대사 종류 별로 1일 호출 제한이 존재 (1일 5회)
IP + mid 및 대사 종류 별로 API 호출 성공 후 다음 호출은 10분 경과 후 허용
호출 시간 제한 (07:00 ~ 20:00)
정산은 영업일에만 이루어지기 때문에 대사 요청일이 공휴일인 경우에는 정산대사 응답 데이터가 반환되지 않습니다.
거래대사의 경우 대사 요청일에 오늘 일자를 지정할 수 없습니다.

위 제한은 운영 정책에 따라 변경될 수 있습니다.

거래 대사

거래 대사 URL

운영	https://mms.lightpay.kr/api/v1/reconcile/trx
개발	https://testmms.lightpay.kr/api/v1/reconcile/trx

요청 정보

Protocol	HTTPS
Method	POST
Encoding	UTF-8
Content-type	application/json

요청 파라미터

파라미터	한글명칭	설명	필수 여부	최대 크기
mid	가맹점 아이디	가맹점 아이디	Y	21
gid	그룹 아이디	gid 기준 조회 시 전달		21
ediDate	전문 요청 일시	yyyyMMddHHmmss 형식 현재 시간과 5분 이상 차이가 나면 요청 시 검증 오류	Y	14
hashStr	검증 해시	SHA256 해시 (mid + ediDate + 가맹점 키)	Y	256
reconcileReqDt	대사 요청일	yyyyMMdd 형식 현재 일자와 30일이상 차이가 나면 요청 시 검증 오류	Y	8

응답 파라미터

파라미터	한글명칭	설명	Depth	최대 크기
resultCd	결과 코드	결과 코드 항목 참조	1	4
resultMsg	결과 메시지	결과 메시지	1	256
mid	가맹점 아이디	gid 기준 조회 시에는 빈 값	1	21
gid	그룹 아이디	mid 기준 조회 시에는 빈 값	1	21
reconcileDt	대사일	yyyyMMdd 형식	1	8
coNo	사업자 번호	gid 기준 조회 시에는 빈 값	1	10
reconcileCnt	대사 건 수	조회 건 없을 시에는 0	1	10
reconcileTotAmt	대사 합계	조회 건 없을 시에는 0	1	10
reconcileData	거래 대사 데이터	Array	1
mid	가맹점 아이디		2	21
appDnt	승인 일자	yyyyMMddHHmmss	2	14
ccDnt	취소 일자	yyyyMMddHHmmss	2	14
pmCd	지불 수단 코드	01: 카드 02: 계좌이체 03: 가상계좌 05: 휴대폰 20: 네이버페이 21: 카카오페이 22: 스마일페이 23: 내통장결제 25: 페이코	2	2
trxStCd	거래 상태 코드	0: 승인 1: 전취소 2: 후취소	2	2
goodsNm	상품명		2	100
goodsAmt	상품 금액		2	15
remainAmt	잔액		2	15
quotaMon	할부 개월	pmCd가 02, 03인 경우는 ‘00’ 고정	2	2
appNo	승인 번호	pmCd가 02, 03인 경우는 공백	2	32
cpCd	제휴사 코드	제휴사, 카드사, 은행, 휴대폰 원천사 코드 등	2	4
acqCardCd	매입사 코드	pmCd가 02, 03인 경우는 ‘00’ 고정	2	2
mbsReserved	가맹점 예약 필드		2	500
tid	거래 ID		2	45
otid	원거래 ID		2	45
ordNo	주문 번호		2	40
ordNm	주문자명		2	30
ordTel	주문자 전화번호		2	20
ordEmail	주문자 이메일		2	60

코드샘플

                                    
public void reconcileTrx() throws IOException, InterruptedException {
    String mid = "";  //상점 아이디
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청 일시(yyyyMMddHHmmss 형식)
    String merchantKey = "";  //가맹점KEY
    String hashStr = encoding(mid + ediDate + merchantKey);  //SHA256 암호화
    String reconcileReqDt = "";  //대사 요청일(yyyyMMdd 형식)

    Map<String, String> data = Map.of(
            "mid", mid,
            "ediDate", ediDate,
            "hashStr", hashStr,
            "reconcileReqDt", reconcileReqDt
    );
    String requestData = new ObjectMapper().writeValueAsString(data);

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testmms.lightpay.kr/api/v1/reconcile/trx"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$mid = "";  //상점 아이디
$merchantKey = "";  //가맹점KEY
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$reconcileReqDt = "";  //대사 요청일(yyyyMMdd 형식)
$hashStr = hash("sha256", $mid.$ediDate.$merchantKey);  //SHA256 암호화
$url = "https://testmms.lightpay.kr/api/v1/reconcile/trx";
$data = [
    "mid" => $mid,
    "ediDate" => $ediDate,
    "hashStr" => $hashString,
    "reconcileReqDt" => $reconcileReqDt
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testmms.lightpay.kr/api/v1/reconcile/trx' \
     --header 'Content-Type: application/json' \
     --data '{"mid":"testmidm","reconcileReqDt":"20250320","ediDate":"20250325103323","hashStr":"47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"}'


                                

정산 대사

정산 대사 URL

운영	https://mms.lightpay.kr/api/v1/reconcile/settlement
개발	https://testmms.lightpay.kr/api/v1/reconcile/settlement

요청 정보

Protocol	HTTPS
Method	POST
Encoding	UTF-8
Content-type	application/json

요청 파라미터

파라미터	한글명칭	설명	필수 여부	최대 크기
mid	가맹점 아이디	가맹점 아이디	Y	21
gid	그룹 아이디	gid 기준 조회 시 전달		21
ediDate	전문 요청 일시	yyyyMMddHHmmss 형식 현재 시간과 5분 이상 차이가 나면 요청 시 검증 오류	Y	14
hashStr	검증 해시	SHA256 해시 (mid + ediDate + 가맹점 키)	Y	256
reconcileReqDt	대사 요청일	yyyyMMdd 형식 현재 일자와 30일이상 차이가 나면 요청 시 검증 오류	Y	8

응답 파라미터

파라미터	한글명칭	설명	Depth	최대 크기
resultCd	결과 코드	결과 코드 항목 참조	1	4
resultMsg	결과 메시지	결과 메시지	1	256
mid	가맹점 아이디	gid 기준 조회 시에는 빈 값	1	21
gid	그룹 아이디	mid 기준 조회 시에는 빈 값	1	21
reconcileDt	대사일	yyyyMMdd 형식	1	8
coNo	사업자 번호	gid 기준 조회 시에는 빈 값	1	10
reconcileCnt	대사 건 수	조회 건 없을 시에는 0	1	10
reconcileTotAmt	대사 합계	조회 건 없을 시에는 0	1	10
reconcileData	거래 대사 데이터	Array	1
mid	가맹점 아이디		2	21
stmtDt	정산일자	yyyyMMdd	2	8
trDt	거래일자	yyyyMMdd	2	8
pmCd	지불 수단 코드	01: 카드 02: 계좌이체 03: 가상계좌 05: 휴대폰 20: 네이버페이 21: 카카오페이 22: 스마일페이 23: 내통장결제 25: 페이코	2	2
trAmt	거래금액		2	10
fee	수수료		2	10
vat	부가세		2	10
refundFee	환불 수수료		2	10
refundFeeVat	환불 수수료 부가세		2	10
dpstAmt	정산 금액		2	10
tid	거래ID		2	45
otid	원거래ID		2	45
trxStCd	거래상태코드	0: 승인 1: 전취소 2: 후취소	2	2

코드샘플

                                    
public void reconcileTrx() throws IOException, InterruptedException {
    String mid = "";  //상점 아이디
    String ediDate = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));  //요청 일시(yyyyMMddHHmmss 형식)
    String merchantKey = "";  //가맹점KEY
    String hashStr = encoding(mid + ediDate + merchantKey);  //SHA256 암호화
    String reconcileReqDt = "";  //대사 요청일(yyyyMMdd 형식)

    Map<String, String> data = Map.of(
            "mid", mid,
            "ediDate", ediDate,
            "hashStr", hashStr,
            "reconcileReqDt", reconcileReqDt
    );
    String requestData = new ObjectMapper().writeValueAsString(data);

    HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://testmms.lightpay.kr/api/v1/reconcile/settlement"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(requestData))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
}
public String encoding(String input) throws NoSuchAlgorithmException {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
    return new String(Hex.encodeHex(hash));
}


                                

                                    
<?php
$mid = "";  //상점 아이디
$merchantKey = "";  //가맹점KEY
$ediDate = date("YmdHis");  //요청일시 (yyyyMMddHHmmss 형식)
$reconcileReqDt = "";  //대사 요청일(yyyyMMdd 형식)
$hashStr = hash("sha256", $mid.$ediDate.$merchantKey);  //SHA256 암호화
$url = "https://testmms.lightpay.kr/api/v1/reconcile/settlement";
$data = [
    "mid" => $mid,
    "ediDate" => $ediDate,
    "hashStr" => $hashString,
    "reconcileReqDt" => $reconcileReqDt
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>


                                

                                    
curl -X POST 'https://testmms.lightpay.kr/api/v1/reconcile/settlement' \
     --header 'Content-Type: application/json' \
     --data '{"mid":"testmidm","reconcileReqDt":"20250320","ediDate":"20250325103323","hashStr":"47d2583561eb0879846ksd3ns92eae57b01642f30fec8bca50c7e14f673c"}'


                                

웹뷰

iOS

지원환경

iOS 13 이상
Xcode 10.2 이상
Swift 5 이상

연동과정

1. 가맹점 어플리케이션 URL Scheme설정

info.plist 파일에 URL Scheme을 등록합니다.
(3rd 어플리케이션 → 가맹점 어플리케이션 호출)
(미설정 시 특정 3rd 어플리케이션에서 인증 or 결제 완료 후 가맹점 어플리케이션으로 자동 전환이 불가합니다.)

2. 3rd 어플리케이션 URL Scheme 등록

info.plist 파일에 3rd URL Scheme을 등록합니다.
(가맹점 어플리케이션 → 3rd 어플리케이션 호출)
(미설정 시 3rd 어플리케이션 연동 불가)

신한	shinhan-sr-ansimclick://	신한 앱카드 결제
신한	smshinhanansimclick://	신한카드 일반결제
현대	hdcardappcardansimclick://	현대 앱카드 결제
현대	smhyundaiansimclick://	현대카드 일반결제
삼성	mpocket.online.ansimclick://	삼성 앱카드 결제
	ansimclickscard://
	tswansimclick://
	ansimclickipcollect://
	vguardstart://
	samsungpay://
	scardcertiapp://
하나	cloudpay://	하나 앱카드 결제
	hanaskcardmobileportal://	하나카드 일반결제
	hanawalletmembers://	하나맴버스 월렛
농협	nhappcardansimclick://	농협 앱카드 결제
	nonghyupcardansimclick://	농협카드 일반결제
	nhallonepayansimclick://	농협카드 올원페이 결제
국민	kb-acp://	KB 앱카드 결제(KB Pay)
	liivbank://	KB-리브페이
	newliiv://	KB 리브 NEXT
	kbbank://	KB스타뱅킹
롯데	lotteappcard://	롯데 앱카드 결제
롯데	lottesmartpay://	롯데카드 스마트결제
씨티	citispay://	시티 앱카드 결제
	citimobileapp://	시티 앱카드 모바일 결제
	citicardappkr://
우리	com.wooricard.wcard://	우리 앱카드 결제(리뉴얼)
	wooripay://	우리 앱카드 결제
	newsmartpib;//	우리 앱카드-우리WON뱅킹
ISP	ispmobile://	ISP 인증결제
간편결제	shinsegaeeasypayment://	SSG-PAY 결제
	payco://	페이코
	lpayapp://	롯데카드 LPAY
	kakaotalk://	카카오페이
	tswansimclick://	시럽페이
	supertoss://	토스
본인인증	tauthlink://	SKT 본인인증(PASS) APP
	ktauthexternalcall://	KT 본인인증(PASS) APP
	upluscorporation://	LG U+ 본인인증(PASS) APP
네이버 로그인	naversearchthirdlogin://	네이버페이 앱 로그인
뱅크페이	kftc-bankpay://	뱅크페이(금융결제원)

3. 초기 화면 호출(AppDelegate.swift)

AppDelegate.swift 파일이 앱의 실행과 동시에 시작됩니다.
이 파일은 didFinishLaunchingWithOptions 메서드를 호출하고, 이 메서드에서 윈도우를 만들어 RootViewController를 설정하고 보여줍니다.

AppDelegate.swift

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  var window: UIWindow?

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.

    window = UIWindow(frame: UIScreen.main.bounds);
    let vc = RootViewController();
    let nav = UINavigationController(rootViewController:vc);
    window?.rootViewController = nav;
    window?.makeKeyAndVisible();

    return true
  }
}

4. 초기 화면 생성(RootViewController.swift)

RootViewController.swift 파일에서는 앱 버전 정보를 가져와 UILabel에 표시하고, 구매하기 버튼을 누르면 PaymentWebViewController로 이동하도록 구현되어 있습니다.

RootViewController.swift

class RootViewController: UIViewController {
    // UILabel과 연결할 IBOutlet 변수를 생성합니다.
    @IBOutlet weak var verNo: UILabel?

    override func viewDidLoad() {
        super.viewDidLoad()

        // 초기화면 제목 설정
        title = "초기화면"

        // 앱 버전 가져오기
        var version: String? {
            // 앱의 infoDictionary에서 버전 정보를 가져옵니다.
            guard let dic = Bundle.main.infoDictionary,
              let v = dic["CFBundleVersion"] as? String
              else {
                return nil
            }

            return v
        }

        // 레이블에 버전 텍스트 설정
        verNo?.text = version ?? ""
    }

    // 버튼을 누르면 requestPayment가 실행됩니다.
    @IBAction func requestPayment(sender: Any) {
      // PaymentWebViewController 인스턴스 생성
      let vc = PaymentWebViewController()
      // 네비게이션 컨트롤러를 사용해 PaymentWebViewController로 이동
      self.navigationController?.pushViewController(vc, animated: true)
    }

}

5. 웹뷰 호출(PaymentWebViewController.swift)

PaymentWebViewController.swift 파일에서는 웹뷰를 생성하여 결제 페이지를 불러오고, 자바스크립트 Alert와 컨펌 패널을 처리하며, ISP 앱과 BANKPAY 앱이 설치되어 있지 않은 경우 앱스토어로 연결하는 기능이 구현되어 있습니다.
(결제 페이지 URL을 변경하면 연동이 가능합니다.)

AppDelegate.swift

    // 결제 페이지 URL
    let PAY_URL: String = "결제 페이지 URL"
    // WKWebView 인스턴스 선언
    var webView: WKWebView? = nil

    // 뷰 로드가 완료되면 호출되는 함수
    override func viewDidLoad() {
        super.viewDidLoad()

        // 화면에 표시될 제목 설정
        title = "구매하기"

        // WKWebView 인스턴스 초기화 및 델리게이트 설정
        webView = WKWebView(frame: self.view.frame)
        webView?.navigationDelegate = self
        webView?.uiDelegate = self
        // 화면에 WKWebView 추가
        self.view.addSubview(webView!)

        // URL을 사용하여 URLRequest 생성
        let url = URL(string: PAY_URL)
        let request = URLRequest(url: url!)
        // URLRequest를 로드하여 웹뷰에 표시
        webView?.load(request)
    }

더 자세한 내용은 샘플 코드(WiezonAppSample.zip)를 참고해주세요.

Android

지원환경

Android sdk 22(Nougat) 이상
Android Studio Giraffe
Java 17

연동과정

1. 가맹점 어플리케이션 AndroidManifest.xml 설정

파일에 카드앱·은행앱 패키지를 등록합니다. 패키지를 등록하지 않으면 앱이 설치되어 있어도 스토어로 이동하고, Google 정책을 위반하게 됩니다.

AndroidManifest.xml

  <queries>
    <package android:name="com.kakao.talk" /> <!-- 카카오톡 -->
    <package android:name="com.shcard.smartpay" /> <!-- 신한페이판 -->
    <package android:name="com.shinhancard.smartshinhan" /> <!-- 신한페이판-공동인증서 -->
    <package android:name="com.hyundaicard.appcard" /> <!-- 현대카드 -->
    <package android:name="com.lumensoft.touchenappfree" /> <!-- 현대카드-공동인증서 -->
    <package android:name="kr.co.samsungcard.mpocket" /> <!-- 삼성카드 -->
    <package android:name="nh.smart.nhallonepay" /> <!-- 올원페이 -->
    <package android:name="com.kbcard.cxh.appcard" /> <!-- KB Pay -->
    <package android:name="com.kbstar.liivbank" /> <!-- Liiv(KB국민은행) -->
    <package android:name="com.kbstar.reboot" /> <!-- Liiv Reboot(KB국민은행) -->
    <package android:name="kvp.jjy.MispAndroid320" /> <!-- ISP/페이북 -->
    <package android:name="com.lcacApp" /> <!-- 롯데카드 -->
    <package android:name="com.hanaskcard.paycla" /> <!-- 하나카드 -->
    <package android:name="kr.co.hanamembers.hmscustomer" /> <!-- 하나멤버스 -->
    <package android:name="kr.co.citibank.citimobile" /> <!-- 씨티모바일 -->
    <package android:name="com.wooricard.wpay" /> <!-- 우리페이 -->
    <package android:name="com.wooricard.smartapp" /> <!-- 우리카드 -->
    <package android:name="com.wooribank.smart.npib" /> <!-- 우리WON뱅킹 -->
    <package android:name="viva.republica.toss" /> <!-- 토스뱅크 -->
    <package android:name="com.nhnent.payapp" /> <!-- PAYCO -->
    <package android:name="com.ssg.serviceapp.android.egiftcertificate" /> <!-- SSGPAY -->
    <package android:name="com.kakao.talk" /> <!-- 카카오페이 -->
    <package android:name="com.nhn.android.search" /> <!-- 네이버페이 -->
    <package android:name="com.lottemembers.android" /> <!-- L.POINT -->
    <package android:name="com.samsung.android.spay" /> <!-- 삼성페이 -->
    <package android:name="com.samsung.android.spaylite" /> <!-- 삼성페이 -->
    <package android:name="com.lge.lgpay" /> <!-- 엘지페이 -->
    <package android:name="com.lguplus.paynow" /> <!-- 페이나우 -->
    <package android:name="com.kftc.bankpay.android" /> <!-- 뱅크페이 -->
    <package android:name="com.TouchEn.mVaccine.webs" /> <!-- TouchEn mVaccine (신한) -->
    <package android:name="kr.co.shiftworks.vguardweb" /> <!-- V-Guard (삼성) -->
    <package android:name="com.ahnlab.v3mobileplus" /> <!-- V3 (NH, 현대) -->
  </queries>

2. WebView 설정

shouldOverrideUrlLoading를 오버라이드하여 아래와 같이 구현합니다.

WebViewActivity.java

  webView.setWebViewClient(new WebViewClient(){
    @Override
    public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
      Log.d("AAA", request.getUrl().toString());
      if (!request.getUrl().toString().startsWith("http://")
        && !request.getUrl().toString().startsWith("https://")
        && !request.getUrl().toString().startsWith("javascript:")) {
          Intent intent = null;

          try {
            intent = Intent.parseUri(request.getUrl().toString(), Intent.URI_INTENT_SCHEME); //IntentURI처리
            Uri uri = Uri.parse(intent.getDataString());

            startActivity(new Intent(Intent.ACTION_VIEW, uri));
            return true;
          } catch (URISyntaxException ex) {
              return false;
            } catch (ActivityNotFoundException e) {
              if (intent == null) return false;

              String packageName = intent.getPackage();
              if (packageName != null) {
                startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=" + packageName)));
                return true;
            }
            return false;
          }
      }
      return super.shouldOverrideUrlLoading(view, request);
    }
  });

더 자세한 내용은 샘플 코드(WebviewSample.zip)를 참고해주세요.

결과 코드

제공되는 결과 코드에 기재되어 있지 않은 결과 코드는 파트너 업체의 코드를 그대로 전달하고 있습니다.

해당 사항에 포함되는 건은 개인 정보 확인이 필요할 수 있으며, 사용자(결제자)가 파트너 업체(카드사, 통신사, 은행)를 통해 직접 확인이 필요할 수 있습니다.

필요 시, payapp@udid.co.kr로 tid, ordNo, mid, ediDate를 전달 바랍니다.

코드	메시지	코드	메시지
0000	정상처리	0001	허용되지 않는 IP 에서 호출 (담당자에게 문의)
0002	가맹점 키가 존재하지 않음	0003	요청 전문 검증 오류
0004	API 호출 허용 시간이 아님	0005	대사 API 호출 횟수 초과 (대사 종류와 IP 별로 1 일 5 회)
0006	대사 API 호출 시간 간격 오류 (대사 종류와 IP 별로 이전 호출 성공 후 10 분 뒤 호출해야 함)	0007	일부 파라미터가 빈 값인 경우
0008	거래대사 API 호출 시 대사 요청일이 오늘 날짜인 경우	0009	대사 API 호출 시 대사 요청일이 1개월 이전 날짜인 경우
1101	통신 연결 실패	1110	요청 전문 전송 실패
1111	요청 전문 수신 실패	1214	DB 조회 실패
1215	DB 수정 실패	1402	요청 전문 파싱 실패
1403	요청 전문 검증 실패	1501	미등록 가맹점
1511	가맹점 필수 전달 정보 오류	1518	가맹점 서비스 불가
1519	해당 카드사의 카드는 거래가 불가능합니다.	1520	카드사코드 미입력오류
1523	VAN장애	1524	해당 카드사의 카드는 거래가 불가능합니다.
1525	해당 카드사의 카드는 거래가 불가능합니다.	1526	VAN코드 설정오류
1542	결제 서비스 사용불가 가맹점	1551	신용카드 결제사 설정 오류
1554	해당 카드사의 카드는 거래가 불가능합니다.	1601	지불수단오류
1603	지불수단미입력	1604	필수입력값 미입력
1614	거래금액 합계오류 (공급가, 부가세, 봉사료 등)	1650	승인 TID 미입력
1651	중복 결제 요청입니다. 거래 내역을 확인해 주십시오.	1652	승인 TID 길이 오류
1653	승인 TID 날짜 오류	1654	승인 TID 가맹점ID 불일치
1655	승인 TID 지불수단 오류	1656	승인 TID 결제매체 오류
1681	주문번호(MOID)중복 또는 이미 처리된 주문	1701	MID 미입력
1711	상점 키 없음	2001	취소 성공
2002	취소 진행중	2003	취소 실패
2004	이미 취소된 거래	2010	취소 요청금액 0원 이하
2011	취소 금액 불일치	2012	취소 해당거래 없음
2013	취소 완료 거래	2014	취소 불가능 거래
2015	기 취소 요청	2016	취소 기한 초과
2017	취소 불가 가맹점	2018	신용카드 매입후 취소 불가능 가맹점
2019	타 가맹점 거래 취소 불가	2020	망상취소 허용시간 초과
2021	매입전취소	2022	매입후취소
2023	취소 한도 초과	2024	취소패스워드 불일치
2025	취소패스워드 미 입력	2026	입금액보다 취소금액이 큽니다.
2028	부분취소 불가능 가맹점	2029	부분취소 불가능 결제수단
2030	해당결제수단 부분취소 불가	2031	전체금액취소 불가
2032	취소금액이 취소가능금액보다 큼	2033	부분취소 불가능금액, 전체취소 이용바람
2034	해당거래 부분취소 불가능. 매입완료 후 가능	2035	채권방지 설정으로 취소불가. PG사로 문의바람
2036	카드정보 불일치	2037	취소요청금액과 장바구니 취소금액 불일치
2038	장바구니 거래로 취소요청 바람(일반취소 불가)	2039	일반거래로 취소요청 바람(장바구니 취소 불가)
2040	장바구니 취소 정보가 없음	2041	익월 취소 불가능한 거래입니다.
2111	가맹점의 1회 결제 금액을 초과되었습니다.	2112	가맹점의 1회 할부한도가 초과되었습니다.
2113	가맹점의 당일 한도가 초과되었습니다.	2114	가맹점의 당일 한도횟수가 초과되었습니다.
2115	가맹점의 당일 할부한도금액 초과	2116	가맹점의 당월 한도가 초과되었습니다.
2117	가맹점의 당월 한도횟수가 초과되었습니다.	2126	가맹점의 당연 한도가 초과되었습니다.
2127	가맹점의 당월 할부한도가 초과되었습니다.	3001	카드 결제 성공
3002	카드 결제 실패	3011	카드번호 오류
3012	카드가맹점 정보 미확인	3013	카드가맹점 개시 안됨
3014	카드가맹점 정보 오류	3015	사용 중지된 가맹점입니다.
3021	유효기간 오류	3022	할부개월 오류
3023	할부개월 한도 초과	3024	50000원 미만은 할부가 불가능 합니다.
3025	카드비밀번호 미입력	3026	본인인증 필수값 누락
3027	카드인징 필수값 누락	3031	무이자 할부 카드 아님
3032	무이자 할부 불가 개월 수	3033	무이자 할부 가맹점 아님
3034	무이자 할부 구분 미설정	3041	금액 오류(1000원 미만 신용카드 승인 불가)
3051	해외카드 미등록 가맹점	3052	통화코드 오류
3053	확인 불가 해외카드	3054	환율전환오류
3055	인증시 달러승인 불가	3056	국내카드 달러승인불가
3057	인증 불가카드	3061	국민카드 인터넷 안전 결제 적용 가맹점
3062	신용카드 승인번호 오류	3071	매입요청 가맹점 아님
3072	매입요청 TID 정보 불일치	3073	기매입 거래
3081	카드 잔액 값 오류	3091	제휴카드 사용불가 가맹점
3095	카드사 실패 응답	3096	외화승인불가VAN
3097	외화승인설정오류	3098	해외카드결제불가
3099	해외카드는 할부 결제가 불가합니다.	3100	세이브결제 부분취소 불가
3101	타상점 거래취소 불가	3102	거래금액이 입금완료 상태가 아님
3103	부분취소 불가능 카드번호	3104	부분취소 불가능 카드사 가맹점 번호
3174	해쉬값 검증에 실패하였습니다.	3194	가맹점번호 기준정보 미설정 오류.
3329	정산주기없음	4005	거래번호(TID) 불일치
6014	상점 지원 결제수단이 없습니다.	6201	상품명을 입력하세요.
6202	상품금액을 입력하세요.	7001	현금영수증 처리 성공
7002	현금영수증 종류오류	7003	현금영수증 중복발급
7004	현금영수증 취소오류	7005	현금영수증 부가가치세 오류
7006	현금영수증 최대개수 초과	7007	현금영수증 요청개수 입력 오류
7011	현금영수증 미발행 요청입니다.	7012	현금영수증 수동 발행 가맹점입니다.
7013	현금영수증 개시상태가 아닙니다. PG사로 문의하세요.	1615	현금영수증 금액 합계오류(공급가, 부가세, 봉사료 등)
1616	현금영수증 금액과 거래금액 상이	6110	현금영수증이 요청되었습니다.
9998	파라미터 검증 오류	9999	서버 내부 오류
I999	실패(기타)	W002	TID가 유효하지 않습니다.
W004	결제수단이 유효하지 않습니다.	W006	다시 시도하여 주십시오.(W006-상점 정보가 없습니다.)
N001	유효하지 않은 가맹점입니다.	N002	결제 승인 가능 시간 초과입니다. (10분 초과시)
N003	해당 결제번호로 결제가 이미 진행 중입니다.	N004	해당 결제번호로 이미 결제가 완료되었습니다.
N005	본인 카드 인증 오류입니다.	N006	충전 계좌 점검 중입니다.
N007	충전 계좌 잔고 부족입니다.	N008	서비스 점검중입니다.
N009	원천사 시스템 점검으로 해당 결제수단을 이용할 수 없습니다.	N010	유효하지 않은 네이버페이 결제번호입니다.
N011	이미 전체 취소된 결제입니다.	N012	취소 요청 금액이 잔여 결제 금액을 초과입니다.
N013	이전에 요청한 취소가 완료되지 않은 상태입니다.	N014	취소 기한이 만료되어 취소가 불가합니다. 가맹점의 자체 환불이 필요합니다.
N015	취소 가능한 과면세 금액보다 큰 금액 요청입니다.	N016	과면세 및 컵 보증금 금액의 합이 취소 요청 금액과 다른 상태입니다.
N017	가맹점의 예상 잔여금액과 네이버페이의 잔여금액이 일치하지 않습니다.	N018	취소처리가 완료되지 않았지만, 빠른 시일 내에 자동 취소 재처리 예정입니다.
N019	즉시 할인 정책에 따라 취소가 불가합니다.	N020	입력값이 조건을 만족하지 않습니다.
N021	검색 기간 오류입니다. (31일 이내)	N022	파라미터 오류입니다.
N023	시스템 오류입니다.	N024	외부 시스템 오류입니다.
N025	유효하지 않은 간격으로 호출된 요청입니다.	N026	필수 입력값 누락.
N101	네이버페이 결제 CPID 없음. 관리자에게 문의하세요.	N102	주문 요청 중복 또는 이미 처리된 주문.
N103	결제를 취소하였습니다.	MMS_ER0001	암호화 시 에러 발생
MMS_ER0002	가맹점 결제 요청 해시 검증 실패	MMS_ER0003	MID에 해당하는 상점키가 존재하지 않음
MMS_ER0004	해당하는 SMS 메시지 탬플릿 없음	R101	현금영수증 발행번호 길이 오류[전화번호]
R102	현금영수증 발행번호 길이 오류[주민등록번호]	R103	현금영수증 발행번호 길이 오류[카드번호]
R104	현금영수증 발행번호 길이 오류[사업자등록번호]	R105	카드 결제는 현금영수증 발행 대상이 아님
R106	현금영수증 미발행 요청입니다.	R107	소득공제 현금영수증은 사업자 번호로 발행할 수 없습니다.
R108	지출증빙 현금영수증은 사업자 번호로만 발행할 수 있습니다.	R109	취소타입이 없음
Y001	내통장 결제 CPID 없음. 관리자에게 문의하세요.	Y002	사용자가 거래를 취소하였습니다.
Y003	유효하지 않는 요청전문	Y004	IP 권한 없음
Y005	내부 시스템 오류	Y006	Signature 오류
Y007	존재하지 않는 계좌	Y008	유효하지 않는 계좌
Y009	이중출금 발생	Y010	VAN 요청중 시스템 에러
Y011	VAN 응답정보 없음	Y012	거래번호 정보가 없음
Y013	통신장애	Y014	이미 등록된 계좌
Y015	유효하지 않는 요청전문	Y016	내부 시스템 에러
Y017	은행점검 시간	Y018	출금계좌잔액부족
Y019	ARS 인증 결과가 없음	Y020	ARS 인증 요청 값이 상이함
Y021	자동이체해지계좌	Y022	출금계좌거래제한
Y023	주민번호 사업자번호 오류	Y024	계좌오류 (간편계좌등록불가)
Y025	기타거래불가	Y026	계좌오류
Y027	수취인 계좌 없음	Y028	법적 제한 계좌
Y029	비실명 계좌	Y030	예금주 불일치
Y031	이미 취소된 거래	Y032	취소금액 오류
Y033	ARS인증 실패	Y034	ARS수신불가
Y035	계좌 등록 진행중	Y036	환불 진행중
Y037	이중송금 발생	Y038	납부자 성명조회 실패
Y039	1회 한도초과	Y040	1일 한도초과
Y041	사고계좌 입니다.	Y042	일정시간이 지나 연결이 끊어졌습니다.
Y043	간편결제 취소	Y044	요청 진행 중
Y045	환불중복 요청	Y046	처리 중 요청이 있음
Y047	서비스 용량초과	Y048	시스템 BUSY
Y049	이미 등록된 계좌입니다.	Y050	거래 불가 은행
Y051	중복전문요청	Y052	이미 등록된 현금영수증 사용자
Y053	미등록 현금영수증 사용자	Y054	이미 해지된 계좌
Y055	거래실패	Y056	1회한도 금액초과
Y057	일한도 금액초과	Y058	월한도 금액초과
Y059	일한도 건수초과	Y060	월한도 건수초과
Y061	비밀번호 등록 실패	Y062	비밀번호 불일치
Y063	서비스 이용정지	Y064	정책상 해당 결제서비스를 이용할 수 없습니다. 다른 결제수단으로 이용 부탁드립니다.
Y065	정책상 선택하신 결제서비스를 이용할 수 없습니다.	Y066	간편결제 시스템 점검중
Y067	중계기관 TIMEOUT	T001	이미 처리된 결제 입니다. (토스)
T002	일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요. (토스)	T003	설정 가능한 최대 할부 개월 수를 초과했습니다. (토스)
T004	잘못된 요청입니다. (토스)	T005	포인트 사용이 불가한 카드로 카드 포인트 결제에 실패했습니다. (토스)
T006	잘못된 시크릿키 연동 정보 입니다. (토스)	T007	카드 사용이 거절되었습니다. 카드사 문의가 필요합니다. (토스)
T008	신용카드는 결제금액이 100원 이상, 계좌는 200원이상부터 결제가 가능합니다. (토스)	T009	카드 정보를 다시 확인해주세요. (유효기간) (토스)
T010	정지된 카드 입니다. (토스)	T011	하루 결제 가능 횟수를 초과했습니다. (토스)
T012	할부가 지원되지 않는 카드 또는 가맹점 입니다. (토스)	T013	할부 개월 정보가 잘못되었습니다. (토스)
T014	할부가 지원되지 않는 카드입니다. (토스)	T015	하루 결제 가능 금액을 초과했습니다. (토스)
T016	단말기번호(Terminal Id)가 없습니다. 토스페이먼츠로 문의 바랍니다. (토스)	T017	유효하지 않은 인증 방식입니다. (토스)
T018	분실 혹은 도난 카드입니다. (토스)	T019	계좌는 등록 후 12시간 뒤부터 결제할 수 있습니다. 관련 정책은 해당 은행으로 문의해주세요. (토스)
T020	카드번호를 다시 확인해주세요. (토스)	T021	등록되지 않은 서브몰입니다. 서브몰이 없는 가맹점이라면 안심클릭이나 ISP 결제가 필요합니다. (토스)
T022	등록되지 않은 사업자 번호입니다. (토스)	T023	1일 출금 한도를 초과했습니다. (토스)
T024	1회 출금 한도를 초과했습니다. (토스)	T025	카드사에서 오류가 발생했습니다. (토스)
T026	거래금액 한도를 초과했습니다. (토스)	T027	유효하지 않은 계좌입니다. 계좌 재등록 후 시도해주세요. (토스)
T028	결제가 불가능한 시간대입니다 (토스)	T029	아직 승인되지 않은 주문번호입니다. (토스)
T030	당월 결제 가능금액인 1,000,000원을 초과 하셨습니다. (토스)	T031	인증되지 않은 시크릿 키 혹은 클라이언트 키 입니다. (토스)
T032	잔액부족으로 결제에 실패했습니다. (토스)	T033	한도초과 혹은 잔액부족으로 결제에 실패했습니다. (토스)
T034	결제 승인이 거절되었습니다. (토스)	T035	허용되지 않은 요청입니다. (토스)
T036	선택하신 출금 계좌가 출금이체 등록이 되어 있지 않아요. 계좌를 다시 등록해주세요. (토스)	T037	최대 인증 횟수를 초과했습니다. 카드사로 문의해주세요. (토스)
T038	일일 한도를 초과했습니다. (토스)	T039	은행 서비스 시간이 아닙니다. (토스)
T040	결제 비밀번호가 일치하지 않습니다. (토스)	T041	잘못된 요청입니다. ':' 를 포함해 인코딩해주세요. (토스)
T042	[토스페이먼츠] 위험거래가 감지되어 결제가 제한됩니다. 발송된 문자에 포함된 링크를 통해 본인인증 후 결제가 가능합니다. (고객센터: 1644-8051) (토스)	T043	존재하지 않는 결제 정보 입니다. (토스)
T044	결제 시간이 만료되어 결제 진행 데이터가 존재하지 않습니다. (토스)	T045	결제가 완료되지 않았어요. 다시 시도해주세요. (토스)
T046	내부 시스템 처리 작업이 실패했습니다. 잠시 후 다시 시도해주세요. (토스)	T047	결제에 실패했어요. 같은 문제가 반복된다면 은행이나 카드사로 문의해주세요. (토스)
T048	이미 취소된 결제 입니다. (토스)	T049	환불 계좌번호와 예금주명이 일치하지 않습니다. (토스)
T050	즉시할인금액보다 적은 금액은 부분취소가 불가능합니다. (토스)	T051	잘못된 요청입니다. (토스)
T052	잘못된 환불 계좌번호입니다. (토스)	T053	유효하지 않은 은행입니다. (토스)
T054	잔액 결과가 일치하지 않습니다. (토스)	T055	일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요. (토스)
T056	환불이 거절됐습니다. 결제사에 문의 부탁드립니다. (토스)	T057	이미 환불된 결제입니다. (토스)
T058	고객 계좌가 입금이 되지 않는 상태입니다. (토스)	T059	인증되지 않은 시크릿 키 혹은 클라이언트 키 입니다. (토스)
T060	취소 할 수 없는 금액 입니다. (토스)	T061	반복적인 요청은 허용되지 않습니다. 잠시 후 다시 시도해주세요. (토스)
T062	허용되지 않은 요청입니다. (토스)	T063	취소 할 수 없는 결제 입니다. (토스)
T064	환불 가능한 기간이 지났습니다. (토스)	T065	입금 대기중인 결제는 부분 환불이 불가합니다. (토스)
T066	에스크로 주문, 현금 카드 결제일 때는 부분 환불이 불가합니다. 이외 다른 결제 수단에서 부분 취소가 되지 않을 때는 토스페이먼츠에 문의해 주세요. (토스)	T067	은행 서비스 시간이 아닙니다. (토스)
T068	잘못된 요청입니다. ':' 를 포함해 인코딩해주세요. (토스)	T069	휴면 처리된 회원의 결제는 취소할 수 없습니다. (토스)
T070	존재하지 않는 결제 정보 입니다. (토스)	T071	내부 시스템 처리 작업이 실패했습니다. 잠시 후 다시 시도해주세요. (토스)
T072	은행 응답시간 지연이나 일시적인 오류로 환불요청에 실패했습니다. (토스)	T073	취소 중 결제 시 사용한 결제 수단 처리과정에서 일시적인 오류가 발생했습니다. (토스)
T074	은행 점검, 해약 계좌 등의 사유로 부분 환불이 실패했습니다. (토스)	T075	일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요. (토스)
T076	결제가 완료되지 않았어요. 다시 시도해주세요. (토스)	T077	카드 정보를 다시 확인해주세요. (유효기간) (토스)
T078	카드번호를 다시 확인해주세요. (토스)	T079	카드 정보를 다시 확인해주세요. (비밀번호) (토스)
T080	입력하신 주민번호/사업자번호가 카드 소유주 정보와 일치하지 않습니다. (토스)	T081	정지된 카드 입니다. (토스)
T082	카드 사용이 거절되었습니다. 카드사 문의가 필요합니다. (토스)	T083	생년월일 정보는 6자리의 `yyMMdd` 형식이어야 합니다. 사업자등록번호는 10자리의 숫자여야 합니다. (토스)
T084	지원되지 않는 카드 종류입니다. (토스)	T085	카드를 사용 등록 후 이용해주세요. (토스)
T086	잘못된 요청입니다. (토스)	T087	할부가 지원되지 않는 카드입니다. (토스)
T088	할부 개월 정보가 잘못되었습니다. (토스)	T089	할부가 지원되지 않는 카드 또는 가맹점 입니다. (토스)
T090	유효하지 않은 이메일 주소 형식입니다. (토스)	T091	신용카드는 결제금액이 100원 이상, 계좌는 200원이상부터 결제가 가능합니다. (토스)
T092	이미 승인 및 취소가 진행된 중복된 주문번호 입니다. 다른 주문번호로 진행해주세요. (토스)	T093	`orderId`는 영문 대소문자, 숫자, 특수문자(-, _) 만 허용합니다. 6자 이상 64자 이하여야 합니다. (토스)
T094	포인트 사용이 불가한 카드로 카드 포인트 결제에 실패했습니다. (토스)	T095	필수 파라미터가 누락되었습니다. (토스)
T096	5만원 이하의 결제는 할부가 불가능해서 결제에 실패했습니다. (토스)	T097	인증되지 않은 시크릿 키 혹은 클라이언트 키 입니다. (토스)
T098	한도초과 혹은 잔액부족으로 결제에 실패했습니다. (토스)	T099	최대 인증 횟수를 초과했습니다. 카드사로 문의해주세요. (토스)
T100	잔액부족으로 결제에 실패했습니다. (토스)	T101	결제 승인이 거절되었습니다. (토스)
T102	잘못된 요청입니다. ':' 를 포함해 인코딩해주세요. (토스)	T103	내부 시스템 처리 작업이 실패했습니다. 잠시 후 다시 시도해주세요. (토스)
T104	잘못된 요청 값으로 처리 중 DB 에러가 발생했습니다. (토스)	T105	결제가 완료되지 않았어요. 다시 시도해주세요. (토스)
T104	잘못된 요청 값으로 처리 중 DB 에러가 발생했습니다. (토스)	T105	결제가 완료되지 않았어요. 다시 시도해주세요. (토스)
T106	카드사에서 에러가 발생했습니다. 잠시 후 다시 시도해 주세요. (토스)

영중소 코드

코드	메시지
00	일반 (차액정산 대상이 아니므로 결과코드가 함께 전시됩니다)
A1	영세
B1	중소 1
B2	중소 2
B3	중소 3

원천제휴사 코드

카드사 코드

코드	카드사	코드	카드사
01	비씨	28	해외AMAX
02	국민	29	해외JCB
03	하나	30	해외
04	삼성	32	우체국
06	신한	33	MG새마을체크
07	현대	34	중국은행체크
08	롯데	38	은련
11	시티	41	신협
12	NH농협	42	저축은행
13	수협	43	KDB산업
15	우리	44	카카오뱅크
21	광주	45	케이뱅크
22	전북	46	카카오머니
23	제주	47	강원
25	해외비자	49	토스뱅크
26	해외마스터	56	스마일캐시
27	해외다이너스	57	토스페이 (계좌)

은행(증권사) 코드

코드	은행명	코드	은행명
001	한국은행	101	한국신용정보원
002	산업은행	102	대신저축은행
003	기업은행	103	에스비아이저축은행
004	KB 국민은행	104	에이치케이저축은행
007	수협은행	105	웰컴저축은행
008	수출입은행	106	신한저축은행
011	NH 농협은행	209	유안타증권
012	지역농축협	218	KB 증권
020	우리은행	221	상상인증권
023	SC 제일은행	222	한양증권
027	한국씨티은행	223	리딩투자증권
031	대구은행	224	BNK 투자증권
032	부산은행	225	IBK 투자증권
034	광주은행	227	KTB 투자증권
035	제주은행	238	미래에셋대우
037	전북은행	240	삼성증권
039	경남은행	243	한국투자증권
045	새마을금고	247	NH 투자증권
048	신협	261	교보증권
050	저축은행	262	하이투자증권
052	모건스탠리은행	263	현대차증권
054	HSBC 은행	264	키움증권
055	도이치은행	265	이베스트투자증권
057	제이피모간체이스은행	266	SK 증권
058	미즈호은행	267	대신증권
059	엠유에프지은행	269	한화투자증권
060	BOA 은행	270	하나금융투자
061	비엔피파리바은행	271	토스준비법인
062	중국공상은행	272	NH 선물
063	중국은행	278	신한금융투자
064	산림조합중앙회	279	DB 금융투자
065	대화은행	280	유진투자증권
066	교통은행	287	메리츠증권
067	중국건설은행	288	카카오페이증권
071	우체국	290	부국증권
076	신용보증기금	291	신영증권
077	기술보증기금	292	케이프투자증권
081	하나은행	293	한국증권금융
088	신한은행	294	한국포스증권
089	케이뱅크	295	우리종합금융
090	카카오뱅크	299	우리금융캐피탈
092	토스

통신사 코드

코드	카드사	코드	카드사
KTF	KT	LGT	LGT+
SKT	SKT	SKL	SK 7Mobile+
CJH	CJ헬로모바일	KCT	한국케이블텔레콤

간편 결제사 코드

코드	카드사	코드	카드사
02	카카오페이	15	토스페이
14	스마일페이

결제연동

결제 요청 페이지 작성

특징

결제 요청 데이터

가맹점 Key 발급방법

Input에 결제 요청 데이터 생성

결제/취소 테스트

방화벽

라이트페이에 대한 통신이 가능하도록 방화벽 설정이 필요합니다.

암호화

암호화 구성

가맹점연동가이드

개요

과정

서비스 구조와 결제 처리 (신용카드)

설치

요구사항

샘플코드

결제 요청

결제 요청 URL

결제 요청 정보

결제 기본 요청데이터 필드

인증 결과 데이터 필드

승인 요청

승인 요청 URL

승인 요청 데이터 필드

결제 결과 데이터 필드

신용카드 결제 추가 응답데이터 필드

가상계좌 결제(채번) 추가 응답데이터 필드

네이버페이 결제 추가 응답데이터 필드

카카오페이 결제 추가 응답데이터 필드

스마일페이 결제 추가 응답데이터 필드

계좌이체 결제 추가 응답데이터 필드

휴대폰 결제 추가 응답데이터 필드

내통장 결제 추가 응답데이터 필드

PAYCO 결제 추가 응답데이터 필드

토스페이 결제 추가 응답데이터 필드

빌링

개요

과정

빌키 발급 정보 입력

빌키 발급 요청, 응답

빌키 승인 요청, 응답

빌키 삭제 요청, 응답

주의사항

예외처리

빌키 발급 요청 시 주의 및 오류 사항

사용자 카드로 인한 빌키 발급 에러 발생

빌키 승인 요청시 주의 및 오류

빌키 승인 응답 중 오류 발생

빌키 삭제 요청 시 주의 및 오류

빌키 발급

요청 URL

요청 정보

요청 파라미터

응답 파라미터

빌키 결제(승인)

요청 URL

요청 정보

요청 파라미터

응답 파라미터

빌키 삭제

요청 URL

요청 정보

요청 파라미터

응답 파라미터

키인

개요

결제 요청

요청 URL

요청 정보

결제 기본 요청데이터 필드

결제 결과 데이터 필드

결제 취소

결제 취소 요청 페이지 작성

요청 URL

결제 취소 요청 정보

기본 취소요청데이터 필드

결제취소 기본 응답데이터 필드

네이버페이 결제취소 추가 응답데이터 필드