거래 등록

결제 화면 호출을 하기 위해 주문정보를 등록하면 결제창 호출 URL을 응답으로 받을 수 있습니다.

요청

요청 URL

POST https://{API 도메인}/api/ep9/trades/webpay
Content-type: application/json; charset=utf-8

파라미터

필드명	타입	길이	필수여부	설명
mallId	String	8Byte	✅	KICC에서 부여한 상점ID
shopOrderNo	String	40Byte	✅	상점 주문번호 반드시 Unique 값으로 생성
amount	Number		✅	결제요청 금액
payMethodTypeCode	String	2Byte	✅	결제수단 (결제수단 코드 참고) 선택을 하지 않을 시 “00”으로 요청
currency	String	2Byte	✅	통화코드(원화 : “00”)
returnUrl	String	256Byte	✅	인증 완료 후 이동할 URL
deviceTypeCode	String	20Byte	✅	결제고객 단말구분 PC버전: “pc”, 모바일버전: “mobile”
clientTypeCode	String	2Byte	✅	결제창 구분코드로 통합형일 경우 "00" 고정
langFlag	String	3Byte		KOR: 한국어, ENG:영어, JPN:일본어, CHN:중국어
appScheme	String	256Byte		상점 앱스키마(앱으로 결제연동 시) iOS에서 대외기관 앱 호출 후 돌아올 때 사용 웹뷰 연동하기 참고
orderInfo	Object		✅	결제 주문정보 아래 orderInfo 참조
payMethodInfo	Object			결제수단 관리정보 아래 payMethodInfo 참조
taxInfo	Object			복합과세 정보(복합과세 사용 시 필수) 아래 taxInfo 참조
shopValueInfo	Object			상점 필드 승인 및 노티 응답으로 전송됨 아래 shopValueInfo 참조
depositInfoList	Array			자원순환 보증금 목록 아래 depositInfoList 참조
escrowInfo	Object			에스크로 정보(에스크로 사용 시 필수) 아래 escrowInfo 참조
basketInfoList	Array			장바구니 목록(다중정산 사용 시 필수) 아래 basketInfoList 참조

orderInfo(주문 정보)

필드명	타입	길이	필수여부	설명
goodsName	String	50Byte	✅	상품명
customerInfo	Object			주문 고객정보 (아래 customerInfo 참조)

orderInfo > customerInfo(주문 고객정보)

필드명	타입	길이	필수여부	설명
customerId	String	20Byte		고객 ID
customerName	String	20Byte		고객명
customerMail	String	50Byte		고객 Email
customerContactNo	String	11Byte		고객 연락처(숫자만 허용)
customerAddr	String	200Byte		고객 주소

payMethodInfo(결제수단 관리정보)

필드명	타입	길이	필수여부	설명
cardMethodInfo	Object			신용카드 설정 정보 (결제창 노출 시 카드 또는 간편결제를 별도 설정이 필요한 상점만 설정필요) 아래 cardMethodInfo 참조
virtualAccountMethodInfo	Object			가상계좌 설정 정보 (결제창 노출 시 입금은행를 별도 설정이 필요한 상점만 설정필요) 아래 virtualAccountMethodInfo 참조

payMethodInfo > cardMethodInfo(신용카드 설정 정보)

필드명	타입	길이	필수여부	설명
paymentType	String	1Byte		신용카드 결제구분 빈값: 일반 신용카드 결제 "0": 키인(key-in) 인증 "1": 키인(key-in) 비인증
installmentMonthList	Array			결제창에 노출할 할부개월 리스트 일시불만 노출 경우: [0] 6개월까지 노출: [0, 2, 3, 4, 5, 6]
setFreeInstallment	String	1Byte		무이자 사용 여부: Y/N, 빈값으로 설정하면 원장 설정으로 처리
setCardPoint	String	1Byte		카드사 포인트 사용 여부: Y/N, 빈값으로 설정하면 원장 설정으로 처리
joinCd	String	4Byte		제휴서비스 코드 (해당 코드를 사용하기 위해 영업담당자와 협의바람)
displayArea	Array			결제수단 노출영역 지정목록 (빈값으로 설정하면 원장 설정으로 처리) "CARD": 신용카드만 노출 "SPAY": 간편결제만 노출
usedSpayCode	Array			결제창에 노출할 제휴 간편결제사 리스트 (제휴 서비스사 코드 참고) 카카오페이만 노출: ["KKO"]
cardInfoList	Array			결제창에 노출할 신용 카드사 리스트 아래 cardInfoList 참조

payMethodInfo > cardMethodInfo > cardInfoList(신용 카드사 목록)

필드명	타입	길이	필수여부	설명
cardCd	String	3Byte	✅	결제창에 노출할 카드사 코드 (카드사 코드 참고)
cardPoint	String	2Byte		카드사 포인트 적용값 setCardPoint가 “Y” 시 사용 “60”
freeInstallmentMonthList	Array			무이자 할부개월 리스트 setFreeInstallment가 ‘Y’인 경우 적용 2 ~ 6개월 무이자일 경우: [2,3,4,5,6]

payMethodInfo > virtualAccountMethodInfo(가상계좌 설정 정보)

필드명	타입	길이	필수여부	설명
bankList	Array			결제창에 노출할 은행 리스트 (은행 코드 참고)
expiryDate	String	8Byte		입금만료 일자(yyyyMMdd)
expiryTime	String	6Byte		입금만료 시간(hhmmss)

taxInfo(복합과세 정보)

필드명	타입	길이	필수여부	설명
taxAmount	Number		✅	과세 금액
freeAmount	Number		✅	비과세 금액
vatAmount	Number		✅	부가세 금액

shopValueInfo(상점 필드)

필드명	타입	길이	필수여부	설명
value1	String	1000Byte		필드1
value2	String	64Byte		필드2
value3	String	32Byte		필드3
value4	String	32Byte		필드4
value5	String	64Byte		필드5
value6	String	64Byte		필드6
value7	String	64Byte		필드7

depositInfoList(자원순환 보증금목록)

필드명	타입	길이	필수여부	설명
dpsType	String	1Byte	✅	보증금 종류 컵 보증금 : “C”
dpsAmount	Number		✅	보증금 금액(자원순환 보증금종류별 총금액)

요청 예시

{  
    "mallId": "{상점ID}", 
    "shopOrderNo": "{상점 주문번호}", 
    "amount": 1000, 
    "payMethodTypeCode": "00", 
    "currency": "00",
    "clientTypeCode": "00", 
    "returnUrl": "{상점 리턴 URL}", 
    "deviceTypeCode": "mobile",     
    "orderInfo": { 
        "goodsName": "예시 상품명" 
    }
}

escrowInfo(에스크로 정보)

에스크로 서비스를 하기위해 아래 정보를 추가하여 요청하시기 바랍니다.

필드명	타입	길이	필수여부	설명
escrowTypeCode	String	1Byte	✅	에스크로 타입 "K" 고정
deliveryCode	String	4Byte		배송구분 “DE01” : 자가배송 “DE02” : 택배배송
goodsInfoList	Array		✅	상품정보 목록(Max 20개) 아래 goodsInfoList 참조
recvInfo	Object		✅	구매자 상세정보 (아래 recvInfo 참조)

escrowInfo > goodsInfoList(상품정보 목록)

필드명	타입	길이	필수여부	설명
productNo	String	40Byte	✅	개별 상품관리 번호
productName	String	50Byte	✅	개별 상품명
productAmount	Number		✅	개별 상품금액

주의

상품정보 목록의 개별 상품금액 합계가 거래등록 시 요청한 결제요청 금액과 일치해야 합니다.

escrowInfo > recvInfo(구매자 상세정보)

필드명	타입	길이	필수여부	설명
recvId	String	50Byte		구매자 ID
recvName	String	50Byte	✅	구매자 이름
recvMobileNo	String	11Byte	✅	구매자 연락처(숫자만 허용)
recvMail	String	100Byte	✅	구매자 이메일 주소
recvZipCode	String	6Byte		구매자 우편번호(숫자만 허용)
recvAddr1	String	100Byte		구매자 주소1
recvAddr2	String	100Byte		구매자 주소2

요청 예시

{
    "mallId": "{상점ID}",
    "shopOrderNo": "{상점 주문번호}",
    "amount": 1000,
    "payMethodTypeCode": "00",
    "currency": "00",
    "clientTypeCode": "00",
    "returnUrl": "{상점 리턴 URL}",
    "deviceTypeCode": "mobile",
    "orderInfo": {
        "goodsName": "예시 상품명"
    },
    "escrowInfo": {
        "escrowType": "K",
        "deliveryCode": "DE01",
        "goodsInfoList": [
            {
                "productNo": "{개별 상품 고유번호}",
                "productName": "{개별 상품명}",
                "productAmount": 1000
            }
        ],
        "recvInfo": {
            "recvName": "수취인명",
            "recvMobileNo": "수취인 연락처",
            "recvMail": "수취인 Email",
            "recvAddr": "수취인 주소",
            "recvZipCode": "수취인 우편번호",
            "recvAddr1": "수취인 주소1",
            "recvAddr2": "수취인 주소2"
        }
    }
}

basketInfoList(장바구니 목록)

다중정산 서비스를 하기위해 아래 정보를 추가하여 요청하시기 바랍니다.

주의사항

• 다중정산 서비스를 이용하기 위해서 다중정산 전용 상점ID를 발급 받아야 합니다.
• 에스크로, 복합과세 서비스와 혼합하여 사용할 수 없습니다.

필드명	타입	길이	필수여부	설명
productNo	String	40Byte	✅	개별 상품 고유번호 장바구니 내 Unique 보장
productName	String	50Byte	✅	개별 상품명
productAmount	Number		✅	개별 상품 금액
sellerId	String	50Byte	✅	셀러ID
feeUsed	Boolean		✅	셀러 수수료 사용여부
feeTypeCode	String	1Byte		셀러 수수료 코드(셀러 수수료 사용여부가 true 일 경우 필수) 정액: "A" 정율: "P"
feeCharge	Number			셀러 수수료 금액(셀러 수수료 사용여부가 true 일 경우 필수) 정율일 경우 수수료 * 1000 예) 2.12%일 경우 2120

요청 예시

{
    "mallId": "{상점ID}",
    "shopOrderNo": "{상점 주문번호}",
    "amount": 1000,
    "payMethodTypeCode": "00",
    "currency": "00",
    "clientTypeCode": "00",
    "returnUrl": "{상점 리턴 URL}",
    "deviceTypeCode": "mobile",
    "orderInfo": {
        "goodsName": "예시 상품명"
    },
    "basketInfoList": [
        {
            "productNo": "{개별 상품 고유번호}",
            "productName": "{개별 상품명}",
            "productAmount": 1000,
            "sellerId": "{셀러ID}",
            "feeUsed": true,
            "feeTypeCode": "P",
            "feeCharge": 2120
        }
    ]
}

응답

파라미터

필드명	타입	길이	설명
resCd	String	4Byte	결과코드(정상 : “0000”)
resMsg	String	1000Byte	결과 메시지
authPageUrl	String	256Byte	결제창 호출 URL

응답 예시

{
   "resCd": "0000",
   "resMsg": "정상처리",
   "authPageUrl": "{결제창 호출 URL}"
}