본문으로 건너뛰기

결제 승인

결제 인증창으로부터 받은 인증 거래번호(authorizationId)으로 승인 요청하는 API 입니다.

정보
  • 본 API는 PG 결제를 위해 제공되는 서비스 입니다.
주의사항
  • 응답 대기시간 초과 및 네트워크 오류로 응답을 받지 못한 경우 반드시 거래상태 조회를 통해 PG 거래고유번호를 조회 후 취소처리 바랍니다.
  • 승인결과의 결제금액과 제휴사의 결제금액이 상이할 시 반드시 취소처리 바랍니다.
  • 승인결과에 대한 제휴사 DB 처리 실패 시 반드시 취소처리 바랍니다

요청​

일반결제 요청 URL
POST https://{API 도메인}/easypay/payment/settle.do
Content-type: application/json; charset=euc-kr
참고

API 멱등성 지원 대상 (API 멱등성 참조)

주의

최종 결제 승인이 완료되기까지 시간이 걸리므로 timeout을 30초로 설정해야 합니다.

파라미터​

필드명타입길이필수여부설명
mallIdString8Byte✅KICC에서 부여한 가맹점ID
shopTransactionIdString60Byte✅제휴사 거래고유번호 (API 멱등성 키)
authorizationIdString60Byte✅인증 거래번호 결제창 호출 후 받은 값 그대로 사용
shopOrderNoString40Byte✅제휴사 주문번호 거래등록 시 요청한 값 그대로 사용
approvalReqDateString8Byte✅승인요청일자(yyyyMMdd)
escrowInfoObject에스크로 정보(에스크로결제 시 필수)
아래 escrowInfo 참조

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

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

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

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

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

필드명타입길이필수여부설명
recvIdString50Byte구매자 ID
recvNameString50Byte✅구매자 이름
recvMobileNoString11Byte✅구매자 연락처(숫자만 허용)
recvMailString100Byte✅구매자 이메일 주소
recvZipCodeString6Byte구매자 우편번호(숫자만 허용)
recvAddr1String100Byte구매자 주소1
recvAddr2String100Byte구매자 주소2
요청 예시
{  
"mallId": "T5102001",
"shopOrderNo": "{제휴사 주문번호}",
"shopTransactionId": "{API 멱등성 키}",
"authorizationId": "{인증 거래번호}",
"approvalReqDate": "{결제 승인요청 일자}"
}

응답​

파라미터​

필드명타입길이설명
resCdString4Byte결과코드(정상 : “0000”)
resMsgString1000Byte결과 메시지
shopTransactionIdString60Byte승인 요청 시 전송한 값
mallIdString8ByteKICC에서 부여한 가맹점ID
shopOrderNoString40Byte제휴사 주문번호 거래등록 시 요청한 값 그대로 사용
pgCnoString20BytePG 거래고유번호(취소요청 시 필수 필드)
amountNumber총 결제금액(결제 요청금액과 응답금액을 필수로 비교하여 주세요.)
transactionDateString14Byte거래일시(yyyyMMddHHmmss)
statusCodeString4Byte거래상태 코드 (거래상태 코드 참고)
statusMessageString50Byte거래상태 메시지
msgAuthValueString200Byte응답값의 무결성을 검증 (메시지 인증값 바로가기)
paymentInfoArray결제수단별 승인결과 정보 (아래 paymentInfo 참조)

paymentInfo(결제수단별 승인결과 정보)​

필드명타입길이설명
payMethodTypeCodeString2Byte결제수단 코드 (결제수단 코드 참고)
amountNumber결제금액
approvalNoString100Byte결제수단 승인번호
approvalDateString14Byte결제수단의 승인일시 (yyyyMMddHHmmss)
maskingNoString20Byte마스킹(*)된 결제수단 번호
payMethodDetailCodeString3Byte결제수단 세부코드 발급사 코드(카드사 코드 참고) 또는 은행 코드 (은행 코드 참고)
payMethodDetailCodeNameString50Byte결제수단 세부 명
cardInfoObject카드 승인정보 (아래 cardInfo 참조)
cashReceiptInfoObject현금영수증 발행 정보 (아래 cashReceiptInfo 참조)

paymentInfo > cardInfo(신용카드 승인정보)​

필드명타입길이설명
acquirerCodeString3Byte매입사 코드 (카드사 코드 참고)
acquirerNameString50Byte매입사 명
installmentMonthNumber할부개월
isFreeInstallmentBoolean무이자 여부
cardGubunString1Byte신용카드 종류 (신용: “N”, 체크: “Y”, 기프트: “G”)

paymentInfo > cashReceiptInfo(현금영수증 발행정보)​

필드명타입길이설명
resCdString4Byte결과코드
resMsgString1000Byte결과 메시지
approvalNoString50Byte승인번호
approvalDateString14Byte승인일시(yyyyMMddHHmmss)
응답 예시
{
// 신용카드 결제 승인응답
"resCd": "0000",
"resMsg": "MPI결제 정상",
"mallId": "{요청한 가맹점ID}",
"pgCno": "{PG 거래고유번호}",
"shopTransactionId": "{요청한 API 멱등성 키}",
"shopOrderNo": "{제휴사 주문번호}",
"amount": "51004",
"transactionDate": "20210326090200",
"statusCode": "TS03",
"statusMessage": "매입요청",
"msgAuthValue": "e06540df5ac28ac877fb4f063d06d5f9c3ee2a3a8820a888bfc8db1577a7fe",
"escrowUsed": "N",
"paymentInfo": [
{
"payMethodTypeCode": "11",
"amount": "51004",
"approvalNo": "00017177",
"approvalDate": "20210326090200",
"maskingNo": "45184211******81",
"payMethodDetailCode": "029",
"payMethodDetailCodeName": "신한카드",
"cardInfo": {
"acquirerCode": "029",
"acquirerName": "신한카드",
"installmentMonth": 0,
"isFreeInstallment": false,
"cardGubun": "N"
}
}
]
}

메시지 인증값​

메시지 인증값 구성은 아래와 같이 조합하고 해당값을 HmacSHA256으로 해시한다. 메시지 인증 참조

pgCno(PG 거래고유번호) + “|” + amount(결제금액) + “|” + transactionDate(거래일시)