거래 등록

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

요청

요청 URL

POST https://{API 도메인}/api/v2/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	✅	결제창 구분코드로 단독형일 경우 "10" 고정
appScheme	String	256Byte		상점 앱스키마(앱으로 결제연동 시) iOS에서 대외기관 앱 호출 후 돌아올 때 사용 웹뷰 연동하기 참고
orderInfo	Object		✅	결제 주문정보 아래 orderInfo 참조
payMethodInfo	Object			결제수단 관리정보 아래 payMethodInfo 참조
taxInfo	Object			복합과세 정보(복합과세 사용 시 필수) 아래 cutaxInfostomerInfo 참조
shopValueInfo	Object			상점 필드 승인 및 노티 응답으로 전송됨 아래 shopValueInfo 참조
cashInfo	Object			현금영수증 발급 정보 아래 cashInfo 참조
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 참조)
mobileMethodInfo	Object			휴대폰 설정 정보 (아래 mobileMethodInfo 참조)

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

필드명	타입	길이	필수여부	설명
installmentMonthList	Array			카드사(간편결제사) 결제창에 노출할 할부개월(신용카드일 경우 선택한 할부개월만 설정) 빈값일 경우 신용카드는 일시불 처리/간편결제는 DB조회 일시불만 노출 경우: [0] 6개월까지 노출: [0, 2, 3, 4, 5, 6]
setFreeInstallment	String	1Byte		무이자 사용 시 "Y", 미사용 시 "N" (무이자할부 조회)
setCardPoint	String	1Byte		카드사 포인트 사용 시 "Y", 미사용 시 "N"
setCouponInfo	String	1Byte		즉시할인 쿠폰 사용 시 사용 "Y" (즉시할인 쿠폰 조회)
chainCode	String	1Byte		신용카드사 결제창 제어코드 "3": 앱카드만 결제가능
onlyCreditCard	String	1Byte		KB국민카드 전용 파라미터 "1": KB페이 앱에서 KB국민카드만 결제가능
appCode	String	20Byte		우리카드 결제수단 제어코드 빈값일 경우 모두노출 "WONCARD": 우리카드만 노출 "WONBANK": 우리은행만 노출
joinCd	String	4Byte		제휴서비스 코드
usedSpayCode	Array			제휴 간편결제사 리스트 (제휴 서비스사 코드 참고)는 1개의 결제사만 설정가능 결제수단이 신용카드일 경우 ["CRD"] 필수
cardInfoList	Array			결제창에 노출할 신용 카드사 리스트 아래 cardInfoList 참조
couponInfo	Array			즉시할인 쿠폰사용 정보 아래 couponInfo 참조

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

필드명	타입	길이	필수여부	설명
cardCd	String	3Byte	✅	결제창에 노출할 카드사 코드 (카드사 코드 참고)는 1개의 카드사만 설정가능
cardPoint	String	2Byte		카드사 포인트 적용값 setCardPoint가 “Y” 시 사용 “60”으로 고정
cardNo	String	20Byte		해외카드 결제(Visa, Master, JCB, Amex) 시 사용(3D-Secure)할 카드번호
expireDate	String	4Byte		해외카드 결제(Visa, Master, JCB, Amex) 시 사용(3D-Secure)할 유효기간(YYMM) 예) 2026년 11월일 경우 “2611”

payMethodInfo > cardMethodInfo > couponInfo(즉시할인 쿠폰 사용 정보)

필드명	타입	길이	필수여부	설명
cponId	String	10Byte	✅	즉시할인 쿠폰 그룹ID (즉시할인 쿠폰조회에서 coupon_id값을 이용하세요.)
cponAmount	Number		✅	즉시할인 쿠폰 금액 (정률일 경우 계산된 할인금액의 소수점 첫자리를 반올림한 금액)
cponNo	String	44Byte	✅	즉시할인 쿠폰 번호 "123456789"로 고정

payMethodInfo > mobileMethodInfo(휴대폰 설정 정보)

필드명	타입	길이	필수여부	설명
mobileCd	String	3Byte	✅	통신사 코드 (통신사 코드 참고)

taxInfo(복합과세 정보)

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

shopValueInfo(상점 필드)

필드명	타입	길이	필수여부	설명
value1	String	64Byte		필드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

cashInfo(현금영수증 발급 정보)

필드명	타입	길이	필수여부	설명
issueType	String	2Byte	✅	현금영수증 발행용도 "01": 소득공제 "02": 지출증빙 "03": 자진발급
authType	String	1Byte	✅	인증 구분 "1": 카드번호 "3": 휴대폰번호 "4": 사업자번호
authValue	String	20Byte	✅	현금영수증 인증 값(숫자만 허용) 자진발급 시 "0100001234" 고정

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

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

요청 예시

{  
    "mallId": "{상점ID}", 
    "shopOrderNo": "{상점 주문번호}", 
    "amount": 1000, 
    "payMethodTypeCode": "11", // 신용카드
    "currency": "00",
    "clientTypeCode": "00", 
    "returnUrl": "{상점 리턴 URL}", 
    "deviceTypeCode": "mobile",     
    "orderInfo": { 
        "goodsName": "예시 상품명" 
    },
    "payMethodInfo": {
        "cardMethodInfo": {
            "usedSpayCode": ["CRD"], // 신용카드
            "installmentMonthList": [0],
            "cardInfoList": [
                {
                    "cardCd": "026",  // 카드사 코드
                    "cardPoint": "60"
                }
            ],
        }
    }
}

에스크로

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

escrowInfo(에스크로 정보)

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

goodsInfoList(장바구니 목록)

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

주의

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

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"
        }
    }
}

다중정산

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

주의사항

• 다중정산 서비스를 이용하기 위해서 다중정산 전용 상점ID를 발급 받아야 합니다.

basketInfoList(장바구니 목록)

필드명	타입	길이	필수여부	설명
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}"
}