거래인증 등록
인증 화면 호출을 하기 위해 주문정보를 등록하면 인증창 호출 URL을 응답으로 받을 수 있습니다.
정보
- 본 API는 PG 결제를 위해 제공되는 서비스 입니다.
요청
요청 URL
POST https://{API 도메인}/easypay/auth/paymentAuthReg.do
Content-type: application/json; charset=euc-kr
참고
API 멱등성 지원 대상 (API 멱등성 참조)
파라미터
| 필드명 | 타입 | 길이 | 필수여부 | 설명 |
|---|---|---|---|---|
| mallId | String | 8Byte | ✅ | KICC에서 부여한 가맹점ID |
| customerKey | String | 60Byte | ✅ | 간편결제 회원 고유키 |
| easypayVirtualNo | String | 60Byte | ✅ | 고객이 선택한 결제수단 가상번호 |
| payMethodTypeCode | String | 2Byte | ✅ | 고객이 선택한 결제수단 코드 (결제수단 코드 참고) |
| payMethodDetailCode | String | 3Byte | ✅ | 고객이 선택한 결제수단 상세코드 (결제수단 코드 참고) |
| shopTransactionId | String | 60Byte | ✅ | 제휴사 거래고유번호 (API 멱등성 키) |
| shopOrderNo | String | 40Byte | ✅ | 제휴사 주문번호 |
| currency | String | 2Byte | ✅ | 통화코드 원화 : “00” |
| amount | Number | ✅ | 결제요청 금액 | |
| comTaxAmt | Number | 과세금액 | ||
| comFreeAmt | Number | 비과세금액 | ||
| comVatAmt | Number | 부가세 | ||
| goodsName | String | 100Byte | ✅ | 상품명 UTF-8 사용 제휴사는 URL Encoding |
| installmentMonth | Number | 고객이 선택한 할부개월(카드 Only) 신용카드 시 필수 | ||
| isFreeInstallment | Boolean | 무이자 여부(카드Only) 신용카드 시 필수 | ||
| isCardPointUsageCheck | Boolean | 카드사 포인트 선택 유무(카드 Only) 신용카드 시 필수 | ||
| joinCd | String | 4Byte | 제휴서비스 코드 사용 제휴사만 세팅가능 | |
| userEmail | String | 50Byte | 고객 이메일 승인/취소 시 결제내역 전송 | |
| returnUrl | String | 256Byte | ✅ | 인증 후 되돌아갈 제휴사 리턴URL 해당URL로 Redirect됨(HTTPS만 허용) |
| msgAuthValue | String | 200Byte | ✅ | 요청값의 무결성을 검증 (메시지 인증값 바로가기) |
| cashReceiptInfo | Object | 현금영수증 발행정보 (아래 cashReceiptInfo 참조) | ||
| depositList | Array | 자원순환 보증금 목록 (아래 depositList 참조) | ||
| shopParameter | String | 4000Byte | 제휴사 예비필드(개인정보에 해당하는 데이터는 제외하여 전달해야 합니다.) |
cashReceiptInfo(현금영수증 발행정보)
| 필드명 | 타입 | 길이 | 필수여부 | 설명 |
|---|---|---|---|---|
| usage | String | 2Byte | ✅ | 현금영수증 발행용도 소득공제용: "01" 지출증빙용: "02" |
| issuingMethod | String | 1Byte | ✅ | 현금영수증 발행을 위한 수단 카드: "1" 휴대폰번호: "3" 사업자번호: "4" |
| issuingValue | String | 256Byte | ✅ | 현금영수증 발행 수단의 값을 SEED 암호화 후 HexString으로 전송함 |
depositList(자원순환 보증금 목록)
| 필드명 | 타입 | 길이 | 필수여부 | 설명 |
|---|---|---|---|---|
| dpsType | String | 1Byte | ✅ | 보증금 종류 컵 보증금 : “C” |
| dpsAmount | Number | ✅ | 보증금 금액(자원순환 보증금종류별 총금액) |
요청 예시
{
"mallId": "{KICC에서 부여한 가맹점ID}",
"customerKey": "{간편결제 회원 고유키}",
"easypayVirtualNo": "{고객이 선택한 결제수단 가상번호}",
"payMethodTypeCode": "11",
"payMethodDetailCode": "026",
"shopTransactionId": "{API 멱등성 키}",
"shopOrderNo": "{제휴사 주문번호}",
"currency": "00",
"amount": 1000,
"goodsName": "예시 상품명",
"installmentMonth": 0,
"isFreeInstallment": false,
"isCardPointUsageCheck": false,
"userEail": "{결제고객 메일}",
"returnUrl": "{제휴사 리턴 URL}",
"msgAuthValue": "{메시지 인증값}"
}
응답
파라미터
| 필드명 | 타입 | 길이 | 설명 |
|---|---|---|---|
| resCd | String | 4Byte | 결과코드(정상 : “0000”) |
| resMsg | String | 1000Byte | 결과 메시지 |
| shopTransactionId | String | 60Byte | 요청 시 전송한 값 그대로 사용 |
| authPageUrl | String | 256Byte | 인증창 호출 URL(URL Encoding 됨) |
응답 예시
{
"resCd": "0000",
"resMsg": "정상처리",
"shopTransactionId": "{API 멱등성 키}",
"authPageUrl": "{인증창 호출 URL}"
}
메시지 인증값
메시지 인증값 구성은 아래와 같이 조합하고 해당값을 HmacSHA256으로 해시한다. 메시지 인증 참조
customerKey(고객 고유키) + “|” + shopTransactionId(제휴사 거래고유번호) + “|” + payMethodDetailCode(결제수단 상세코드) + “|” + easypayVirtualNo(가상번호) + “|” + amount(결제금액)