결제창으로부터 받은 인증값으로 승인 요청하는 API 입니다. HTTP POST 방식으로 호출하시기 바랍니다.
주의사항
응답 대기시간 초과 및 네트워크 오류로 응답을 받지 못한 경우 반드시 거래상태 조회를 통해 PG거래번호를 조회 후 취소처리바랍니다.
승인결과의 결제금액과 가맹점의 결제금액이 상이할 시 반드시 취소처리 바랍니다.
승인결과에 대한 상점 DB 처리 실패 시 반드시 취소처리 바랍니다.
요청
URL 정보
| 테스트 | https://testpgapi.easypay.co.kr/api/ep9/trades/approval |
| 운영 | https://pgapi.easypay.co.kr/api/ep9/trades/approval |
파라미터
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| mallId | String | 8 Byte | 필수 | KICC에서 부여한 상점ID |
| shopTransactionId | String | 60 Byte | 필수 | 가맹점 트랜젝션ID 중복요청을 방지를 위해 일별로 Unique 보장 |
| authorizationId | String | 60 Byte | 필수 | 인증 거래번호 결제창 호출 후 받은 값 그대로 사용 |
| shopOrderNo | String | 40 Byte | 필수 | 상점 주문번호 결제등록 시 요청한 값 그대로 사용 |
| approvalReqDate | String | 8 Byte | 필수 | 승인요청일자(yyyyMMdd) |
요청 예
{
"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 승인요청 시 전송한 값 노티(웹훅) 전송 시 미전송 대상 |
| 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는 영업담당자에게 문의 |
|
| escrowUsed | String | 1 Byte | 에스크로 사용유무(Y/N) | |
| 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 |
| cpCode | String | 3 Byte | 서비스 제공 기관코드 간편결제, 포인트 결제 시 응답 |
|
| multiCardAmount | Number | 페이코 카드금액 | ||
| multiPntAmount | Number | 페이코 포인트금액 | ||
| multiCponAmount | Number | 페이코 쿠폰금액 | ||
| cardInfo | Object | 신용카드 결제결과 정보 {cardInfo} 참조 |
||
| bankInfo | Object | 계좌이체 결제결과 정보 {bankInfo} 참조 |
||
| virtualAccountInfo | Object | 가상계좌 채번결과 정보 {virtualAccountInfo}참조 |
||
| mobInfo | Object | 휴대폰 결제결과 정보. {MobInfo} 참조 | ||
| cashReceiptInfo | Object | 현금영수증 발행 정보 {cashReceiptInfo}참조 |
||
| spayInfo | Object | 간편결제 결제결과 정보 네이버, 카카오, 페이코, 토스페이일 경우 응답 {spayInfo} 참조 |
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) | |
| subCardCd | String | 3 Byte | BC제휴사 카드코드 빌키발급 시 응답 |
|
| couponAmount | Number | 즉시할인 금액 | ||
| vanSno | String | 12 Byte | VAN거래일련번호 |
bankInfo(계좌이체 결제결과)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| bankCode | String | 3 Byte | 필수 | 은행코드표 참조 |
| bankName | String | 20 Byte | 필수 | 은행명 |
virtualAccountInfo(가상계좌 결제결과)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| bankCode | String | 3 Byte | 필수 | 은행코드표 참조 |
| bankName | String | 20 Byte | 필수 | 은행명 |
| accountNo | String | 20 Byte | 필수 | 채번계좌번호 |
| depositName | String | 20 Byte | 필수 | 예금주 성명 |
| expiryDate | String | 14 Byte | 필수 | 계좌사용만료일 |
spayInfo(간편결제 결제결과)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| cardAmount | Number | 필수 | 신용카드 결제금액 | |
| pntAmount | Number | 필수 | 포인트 결제금액 | |
| cponAmount | Number | 필수 | 쿠폰(할인) 결제금액 |
mobInfo(휴대폰 결제결과)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| authId | String | 3 Byte | 필수 | 인증ID |
| billId | String | 20 Byte | 필수 | 인증번호 |
| mobileNo | String | 11 Byte | 필수 | 휴대폰번호 |
| mobileCd | String | 10 Byte | 필수 | 이통사 코드 |
cashReceiptInfo(현금영수증발행결과)
| 필드명 | 타입 | 최대크기 | 필수여부 | 설명 |
|---|---|---|---|---|
| resCd | String | 4 Byte | 필수 | 결과코드 |
| resMsg | String | 100 Byte | 필수 | 결과 메시지 |
| approvalNo | String | 50 Byte | 필수 | 승인번호 |
| approvalDate | String | 14 Byte | 필수 | 승인일시(yyyyMMddHHmmss) |
응답 예
// 신용카드 응답 예시
{
resCd: "0000",
"resMsg": "MPI결제 정상",
"mallId": "T5102001",
"pgCno": "21032609005610816914",
"shopTransactionId": "20210326090126",
"shopOrderNo": "20210326090046",
"amount": "51004",
"transactionDate": "20210326090200",
"statusCode": "TS03",
"statusMessage": "매입요청",
"msgAuthValue": "e06540df5ac28ac877fb4f063d06d5f9c3ee2a3a8820a888bfc8db1577a7fe",
"escrowUsed": "N",
"paymentInfo": {
"payMethodTypeCode": "11",
"approvalNo": "00017177",
"approvalDate": "20210326090200",
"cardInfo": {
"cardNo": "4518421100007681",
"issuerCode": "029",
"issuerName": "OK:00017177",
"acquirerCode": "029",
"acquirerName": "Payzone TestCard",
"installmentMonth": 0,
"freeInstallmentTypeCode": "00",
"cardGubun": "N",
"cardBizGubun": "P",
"partCancelUsed": "Y",
"couponAmount": 0
}
}
}