발급받은 빌키로 승인 요청하는 API 입니다.
HTTP POST 방식으로 호출하시기 바랍니다.
주의사항
✔ 응답 대기시간 초과 및 네트워크 오류로 응답을 받지 못한 경우 반드시 거래상태 조회를 통해 PG거래번호를 조회 후 취소처리 바랍니다.
✔ 승인결과의 결제금액과 가맹점의 결제금액이 상이할 시 반드시 취소처리 바랍니다.
✔ 승인결과에 대한 상점 DB 처리 실패 시 반드시 취소처리 바랍니다.
요청
URL 정보
| 테스트 | https://testpgapi.easypay.co.kr/api/trades/approval/batch |
| 운영 | https://pgapi.easypay.co.kr/api/trades/approval/batch |
파라미터
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| mallId | String | 8 Byte | 필수 | KICC에서 부여한 상점ID |
| shopTransactionId | String | 60 Byte | 필수 | 가맹점 트랜젝션ID 중복요청을 방지를 위해 일별로 Unique 보장 |
| shopOrderNo | String | 40 Byte | 필수 | 상점 주문번호 |
| approvalReqDate | String | 8 Byte | 필수 | 승인요청일자(yyyyMMdd) |
| currency | String | 2 Byte | 필수 | 통화코드(원화: "00") |
| amount | Number | 필수 | 결제요청금액 | |
| orderInfo | Object | 필수 | 결제 주문정보 {orderInfo} 참조 |
|
| payMethodInfo | Object | 필수 | 결제수단 관리정보 {payMethodInfo} 참조 |
|
| taxInfo | Object | 복합과세 정보(복합과세 사용시 필수) {taxInfo} 참조 |
orderInfo(주문정보)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| goodsName | String | 50 Byte | 필수 | 상품명 |
| customerInfo | Object | 주문 고객정보 {customerInfo} 참조 |
customerInfo(주문정보)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| customerId | String | 20 Byte | 고객 ID | |
| customerName | String | 20 Byte | 고객 명 | |
| customerMail | String | 50 Byte | 고객 Email | |
| customerContactNo | String | 11 Byte | 고객 연락처(숫자만 허용) |
payMethodInfo(결제수단 관리정보)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| billKeyMethodInfo | Object | 필수 | 빌키 설정 정보 {billKeyMethodInfo} 참조 |
|
| cardMethodInfo | Object | 필수 | 신용카드 설정 정보 {cardMethodInfo} 참조 |
billKeyMethodInfo(빌키 설정정보)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| batchKey | String | 60 Byte | 필수 | 빌키 빌키 발급 응답의 cardNo 값 |
cardMethodInfo(신용카드 설정정보)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| installmentMonth | Number | 필수 | 할부개월 | |
| freeInstallmentUsed | Boolean | 무이자여부 true : 무이자 false : 유이자 |
||
| joinCd | String | 4 Byte | 제휴서비스 코드 해당 서비스를 사용하기 위해 영업담당자와 협의바람 |
taxInfo(복합과세 정보)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| taxAmount | Number | 필수 | 과세 금액 | |
| freeAmount | Number | 필수 | 비과세 금액 | |
| vatAmount | Number | 필수 | 부가세 금액 |
요청 예
{
"mallId": "T0001997",
"shopTransactionId": "20210326090126",
"authorizationId" : "21032609005210816913",
"shopOrderNo": "20210326090046",
"approvalReqDate" : "20210326"
}
응답
Body
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| resCd | String | 4 Byte | 필수 | 결과코드 |
| resMsg | String | 100 Byte | 필수 | 결과 메시지 |
| mallId | String | 8 Byte | 필수 | KICC에서 부여한 상점ID |
| shopTransactionId | String | 60 Byte | 필수 | 가맹점 트랜젝션ID 중복요청을 방지를 위해 일별로 Unique 보장 |
| shopOrderNo | String | 40 Byte | 상점 주문번호 결제등록 시 요청한 값 그대로 사용 |
|
| pgCno | String | 20 Byte | PG 승인거래번호 | |
| amount | Number | 총 결제금액 | ||
| transactionDate | String | 14 Byte | 거래일시(yyyyMMddHHmmss) | |
| statusCode | String | 4 Byte | 거래상태 코드(거래상태 코드표 참조) | |
| statusMessage | String | 50 Byte | 거래상태 메시지(거래상태 코드표 참조) | |
| msgAuthValue | String | 200 Byte | 각주 1) 메시지 인증값 응답값의 무결성을 검증할 때 사용 Secret Key는 영업담당자에게 문의 |
|
| paymentInfo | Object | 결제수단별 승인결과 {paymentInfo} 참조 |
각주 1)
메시지 인증값 구성은 PG승인거래번호, 결제금액, 거래일시로 아래와 같이 조합하고 해당값을 HmacSHA256으로 해시한다.(HmacSHA256 해시함수 참조)
pgCno(PG승인거래번호) + “|” + amount(결제금액) + “|” + transactioDate(거래일시)
paymentInfo(결제수단별 승인결과)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| payMethodTypeCode | String | 2 Byte | 필수 | 결제수단 코드 |
| approvalNo | String | 50 Byte | 필수 | 결제수단 승인번호 |
| approvalDate | String | 14 Byte | 필수 | 결제수단의 승인일시 yyyyMMddHHmmss |
| cardInfo | Object | 신용카드 결제결과 정보 {cardInfo} 참조 |
cardInfo(신용카드 결제결과)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| cardNo | String | 20 Byte | 필수 | 카드번호(마스킹) |
| issuerCode | String | 3 Byte | 필수 | 발급사 코드 |
| issuerName | String | 50 Byte | 필수 | 발급사 명 |
| acquirerCode | String | 3 Byte | 필수 | 매입사 코드 |
| acquirerName | String | 50 Byte | 필수 | 매입사 명 |
| installmentMonth | String | 2 Byte | 할부개월 | |
| freeInstallmentTypeCode | String | 2 Byte | 무이자 타입 일반할부 : "00" 가맹점 분담 무이자 : "02" 카드사 무이자 : "03" |
|
| cardGubun | String | 1 Byte | 필수 | 카드종류 신용("N"), 체크("Y"), 기프트("G") |
| cardBizGubun | String | 1 Byte | 필수 | 카드 주체 개인("P"), 법인("C"), 기타("N") |
| partCancelUsed | String | 1 Byte | 부분취소 가능여부(Y/N) |
응답 예
// 신용카드 응답 예시
{
"resCd": "0000",
"resMsg": "MPI결제 정상",
"mallId": "T0001997",
"pgCno": "21032609005610816914",
"shopTransactionId": "20210326090126",
"shopOrderNo": "20210326090046",
"amount": "51004",
"statusCode": "TS03",
"statusMessage": "매입요청",
"transactionDate": "20210326090200",
"msgAuthValue": "e06540df5ac28ac877fb4f063d06d5f9c3ee2a3a8820a888bfc8db1577a7fe",
"paymentInfo": {
"payMethodTypeCode": "11",
"approvalNo": "00017177",
"approvalDate": "20210326090200",
"cardInfo": {
"cardNo": "45187373****3232",
"issuerCode": "029",
"issuerName": "OK:00017177",
"acquirerCode": "029",
"acquirerName": "Payzone TestCard",
"installmentMonth": "02",
"freeInstallmentTypeCode": "03",
"cardGubun": "N",
"cardBizGubun": "P",
"partCancelUsed": "Y"
}
}
}
신용카드 인증 타입
빌키를 발급받기 위해 고객의 카드정보(카드번호, 유효기간, 생년월일, 비밀번호)를 수집을 하게 되는데,
이때 계약방식에 따라 아래와 같이 입력받는 카드정보가 상이할 수 있습니다.
거래등록 시 certType 필드의 값에 따라 아래와 같이 입력화면이 상이합니다.
| Value | 항목 |
|---|---|
| "0" | 카드번호, 유효기간, 생년월일, 비밀번호 |
| "1" | 카드번호, 유효기간 |
| "2" | 카드번호, 유효기간, 생년월일 |
즉시할인 적용방법
빌키 승인 API에서 CardMethodInfo(신용카드 설정정보) 필드에 아래 항목을 추가해서 요청하시기 바랍니다.
| 필드명 | 타입 | 최대크기 | 필수 여부 | 설명 |
|---|---|---|---|---|
| couponUsed | String | 1 Byte | 필수 | 즉시할인 사용여부 "A" : 즉시할인 쿠폰사용 |
| couponGid | String | 10 Byte | 즉시할인 쿠폰ID | |
| couponJoinCd | String | 3 Byte | 즉시할인 쿠폰 제휴사코드 | |
| couponNo | String | 44 Byte | 즉시할인 쿠폰번호 | |
| couponAmount | Number | 즉시할인 쿠폰금액(할인금액) |