본문으로 건너뛰기

거래 등록

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

요청​

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

파라미터​

필드명타입길이필수여부설명
mallIdString8Byte✅KICC에서 부여한 상점ID
shopOrderNoString40Byte✅상점 주문번호 반드시 Unique 값으로 생성
amountNumber✅결제요청 금액
payMethodTypeCodeString2Byte✅단독형 API 결제수단 호출 코드
currencyString2Byte✅통화코드(원화 : “00”)
returnUrlString256Byte✅인증 완료 후 이동할 URL
deviceTypeCodeString20Byte✅결제고객 단말구분
PC버전: “pc”, 모바일버전: “mobile”
clientTypeCodeString2Byte✅고정값 "10" 고정
appSchemeString256Byte상점 앱스키마(앱으로 결제연동 시) iOS에서 대외기관 앱 호출 후 돌아올 때 사용
웹뷰 연동하기 참고
orderInfoObject✅결제 주문정보
아래 orderInfo 참조
payMethodInfoObject결제수단 관리정보
아래 payMethodInfo 참조
taxInfoObject복합과세 정보(복합과세 사용 시 필수)
아래 cutaxInfostomerInfo 참조
shopValueInfoObject상점 필드 승인 및 노티 응답으로 전송됨
아래 shopValueInfo 참조
cashInfoObject현금영수증 발급 정보
아래 cashInfo 참조
depositInfoListArray보증금 목록
아래 depositInfoList 참조
escrowInfoObject에스크로 정보(에스크로 사용 시 필수)
아래 escrowInfo 참조
basketInfoListArray장바구니 목록(다중정산 사용 시 필수)
아래 basketInfoList 참조

orderInfo(주문 정보)​

필드명타입길이필수여부설명
goodsNameString50Byte✅상품명
customerInfoObject주문 고객정보 (아래 customerInfo 참조)

orderInfo > customerInfo(주문 고객정보)​

필드명타입길이필수여부설명
customerIdString20Byte고객 ID
customerNameString20Byte고객명
customerMailString50Byte고객 Email
(해외카드 결제 Visa, Master, JCB, Amex 시 필수)
customerContactNoString11Byte고객 연락처(숫자만 허용)
customerAddrString200Byte고객 주소

payMethodInfo(결제수단 관리정보)​

필드명타입길이필수여부설명
cardMethodInfoObject신용카드 설정 정보 (아래 cardMethodInfo 참조)
mobileMethodInfoObject휴대폰 설정 정보 (아래 mobileMethodInfo 참조)

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

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

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

필드명타입길이필수여부설명
cardCdString3Byte✅결제창에 노출할 카드사 코드 (카드사 코드 참고)는 1개의 카드사만 설정가능
cardPointString2Byte카드사 포인트 적용값 setCardPoint가 “Y” 시 사용 “60”으로 고정
cardNoString20Byte해외카드 결제(Visa, Master, JCB, Amex) 시 사용(3D-Secure)할 카드번호
expireDateString4Byte해외카드 결제(Visa, Master, JCB, Amex) 시 사용(3D-Secure)할 유효기간(YYMM)
예) 2026년 11월일 경우 “2611”
cardHolderNameString45Byte해외카드 결제(Visa, Master, JCB, Amex) 시 사용(3D-Secure)할 카드 소유자 영문 이름

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

필드명타입길이필수여부설명
cponIdString10Byte✅즉시할인 쿠폰 그룹ID (즉시할인 쿠폰조회에서 couponGid값을 이용하세요.)
cponAmountNumber✅즉시할인 쿠폰 금액 (정률일 경우 계산된 할인금액을 discountRoundingUnit에 따라 반올림한 금액)
cponRateNumber즉시할인 쿠폰 할인율(정률 쿠폰에만 포함)

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

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

taxInfo(복합과세 정보)​

필드명타입길이필수여부설명
taxAmountNumber✅과세 금액
freeAmountNumber✅비과세 금액
vatAmountNumber✅부가세 금액

shopValueInfo(상점 필드)​

필드명타입길이필수여부설명
value1String1000Byte필드1
value2String64Byte필드2
value3String32Byte필드3
value4String32Byte필드4
value5String64Byte필드5
value6String64Byte필드6
value7String64Byte필드7

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

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

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

필드명타입길이필수여부설명
dpsTypeString1Byte✅보증금 종류 컵 보증금 : “C”
dpsAmountNumber✅보증금 금액(자원순환 보증금종류별 총금액)
요청 예시
{  
"mallId": "{상점ID}",
"shopOrderNo": "{상점 주문번호}",
"amount": 1000,
"payMethodTypeCode": "11", // 신용카드
"currency": "00",
"clientTypeCode": "10",
"returnUrl": "{상점 리턴 URL}",
"deviceTypeCode": "mobile",
"orderInfo": {
"goodsName": "예시 상품명"
},
"payMethodInfo": {
"cardMethodInfo": {
"usedSpayCode": ["CRD"], // 신용카드
"installmentMonthList": [0],
"cardInfoList": [
{
"cardCd": "026", // 카드사 코드
"cardPoint": "60"
}
]
}
}
}

escrowInfo(에스크로 정보)​

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

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

escrowInfo > goodsInfoList(상품정보 목록)​

필드명타입길이필수여부설명
productNoString40Byte✅개별 상품관리 번호
productNameString50Byte✅개별 상품명
productAmountNumber✅개별 상품금액
주의

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

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

필드명타입길이필수여부설명
recvIdString50Byte구매자 ID
recvNameString50Byte✅구매자 이름
recvMobileNoString11Byte✅구매자 연락처(숫자만 허용)
recvMailString100Byte✅구매자 이메일 주소
recvZipCodeString6Byte구매자 우편번호(숫자만 허용)
recvAddr1String100Byte구매자 주소1
recvAddr2String100Byte구매자 주소2
요청 예시
{
"mallId": "{상점ID}",
"shopOrderNo": "{상점 주문번호}",
"amount": 1000,
"payMethodTypeCode": "21",
"currency": "00",
"clientTypeCode": "10",
"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를 발급 받아야 합니다.
  • 에스크로, 복합과세 서비스와 혼합하여 사용할 수 없습니다.
필드명타입길이필수여부설명
productNoString40Byte✅개별 상품 고유번호 장바구니 내 Unique 보장
productNameString50Byte✅개별 상품명
productAmountNumber✅개별 상품 금액
sellerIdString50Byte✅셀러ID
feeUsedBoolean✅셀러 수수료 사용여부
feeTypeCodeString1Byte셀러 수수료 코드(셀러 수수료 사용여부가 true 일 경우 필수)
정액: "A" 정율: "P"
feeChargeNumber셀러 수수료 금액(셀러 수수료 사용여부가 true 일 경우 필수)
정율일 경우 수수료 * 1000 예) 2.12%일 경우 2120
요청 예시
{
"mallId": "{상점ID}",
"shopOrderNo": "{상점 주문번호}",
"amount": 1000,
"payMethodTypeCode": "11",
"currency": "00",
"clientTypeCode": "10",
"returnUrl": "{상점 리턴 URL}",
"deviceTypeCode": "mobile",
"orderInfo": {
"goodsName": "예시 상품명"
},
"payMethodInfo": {
"cardMethodInfo": {
"usedSpayCode": ["CRD"],
"installmentMonthList": [0],
"cardInfoList": [
{
"cardCd": "026"
}
]
}
},
"basketInfoList": [
{
"productNo": "{개별 상품 고유번호}",
"productName": "{개별 상품명}",
"productAmount": 1000,
"sellerId": "{셀러ID}",
"feeUsed": true,
"feeTypeCode": "P",
"feeCharge": 2120
}
]
}

응답​

파라미터​

필드명타입길이설명
resCdString4Byte결과코드(정상 : “0000”)
resMsgString1000Byte결과 메시지
authPageUrlString256Byte결제창 호출 URL
응답 예시
{
"resCd": "0000",
"resMsg": "정상처리",
"authPageUrl": "{결제창 호출 URL}"
}