결제 승인

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

주의사항

• 응답 대기시간 초과 및 네트워크 오류로 응답을 받지 못한 경우 반드시 거래상태 조회를 통해 PG 거래고유번호를 조회 후 취소처리 바랍니다.
• 승인결과의 결제금액과 상점의 결제금액이 상이할 시 반드시 취소처리 바랍니다.
• 승인결과에 대한 상점 DB 처리 실패 시 반드시 취소처리 바랍니다
• 은련결제의 경우, 상점 returnUrl로 인증완료가 전달된 이후 30분 이내에 승인요청을 하지 않으면 결제사에서 강제로 취소처리 합니다.
• 카카오페이, 토스페이 테스트거래는 실 승인이 발생할 수 있으므로 테스트 후 반드시 취소하셔야합니다.

요청

요청 URL

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

참고

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

주의

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

파라미터

필드명	타입	길이	필수여부	설명
mallId	String	8Byte	✅	KICC에서 부여한 상점ID
shopTransactionId	String	60Byte	✅	상점 거래고유번호 (API 멱등성 키)
authorizationId	String	60Byte	✅	인증 거래번호 결제창 호출 후 받은 값 그대로 사용
shopOrderNo	String	40Byte	✅	상점 주문번호(거래등록 시 요청한 값 그대로 응답)
approvalReqDate	String	8Byte	✅	승인요청일자(yyyyMMdd)

요청 예시

{  
    "mallId": "T5102001", 
    "shopOrderNo": "{상점 주문번호}", 
    "shopTransactionId": "{API 멱등성 키}",    
    "authorizationId": "{인증 거래번호}",
    "approvalReqDate": "{결제 승인요청 일자}"
}

응답

파라미터

필드명	타입	길이	설명
resCd	String	4Byte	결과코드(정상 : “0000”)
resMsg	String	1000Byte	결과 메시지
shopTransactionId	String	60Byte	상점 거래고유번호
mallId	String	8Byte	KICC에서 부여한 상점ID
shopOrderNo	String	40Byte	상점 주문번호(거래등록 시 요청한 값 그대로 응답)
pgCno	String	20Byte	PG 거래고유번호(취소 또는 환불요청 시 필수)
amount	Number		총 결제금액(결제 요청금액과 응답금액을 필수로 비교하여 주세요.)
transactionDate	String	14Byte	거래일시(yyyyMMddHHmmss)
statusCode	String	4Byte	거래상태 코드 (거래상태 코드 참고)
statusMessage	String	50Byte	거래상태 메시지
msgAuthValue	String	200Byte	응답값의 무결성을 검증 (메시지 인증값 바로가기)
escrowUsed	String	1Byte	에스크로 사용유무(Y/N)
paymentInfo	Object		결제수단별 승인결과 정보 아래 paymentInfo 참조
basketInfoList	Array		장바구니 목록(다중정산 시 응답) 아래 basketInfoList 참조

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

필드명	타입	길이	설명
payMethodTypeCode	String	2Byte	결제수단 코드 (결제수단 코드 참고)
approvalNo	String	100Byte	결제수단 승인번호
approvalDate	String	14Byte	결제수단의 승인일시 (yyyyMMddHHmmss)
cpCode	String	4Byte	간편결제/포인트 서비스 제공 기관코드 (제휴 서비스사 코드 참고)
multiCardAmount	Number		페이코/카카오페이/네이버페이 카드금액
multiPntAmount	Number		페이코/카카오페이/네이버페이 포인트금액
multiCponAmount	Number		페이코/카카오페이/네이버페이 쿠폰금액
cardInfo	Object		신용카드 결제결과 정보 아래 cardInfo 참조
bankInfo	Object		계좌이체 결제결과 정보 아래 bankInfo 참조
virtualAccountInfo	Object		가상계좌 채번결과 정보 아래 virtualAccountInfo 참조
mobInfo	Object		휴대폰 결제결과 정보 아래 mobInfo 참조
cashReceiptInfo	Object		현금영수증 발행 정보 아래 cashReceiptInfo 참조

paymentInfo > cardInfo(신용카드 결제결과)

필드명	타입	길이	설명
cardNo	String	20Byte	카드번호(마스킹 *)
issuerCode	String	3Byte	발급사 코드 (카드사 코드 참고)
issuerName	String	50Byte	발급사 명
acquirerCode	String	3Byte	매입사 코드 (카드사 코드 참고)
acquirerName	String	50Byte	매입사 명
installmentMonth	Number		할부개월
freeInstallmentTypeCode	String	2Byte	할부구분 (일반: "00", 상점분담 무잊자: "02", 카드사 무이자: "03")
cardGubun	String	1Byte	카드종류 (신용: “N”, 체크: “Y”, 기프트: “G”)
cardBizGubun	String	1Byte	카드주체 (개인: “P”, 법인: “C”, 기타: “N”)
partCancelUsed	String	1Byte	부분취소 가능여부(Y/N)
subCardCd	String	3Byte	BC제휴사 카드코드 빌키발급 시 응답
couponAmount	Number		즉시할인 금액
vanSno	String	12Byte	VAN거래일련번호

paymentInfo > bankInfo(계좌이체 결제결과)

필드명	타입	길이	설명
bankCode	String	3Byte	은행코드 (은행 코드 참고)
bankName	String	20Byte	은행명

paymentInfo > virtualAccountInfo(가상계좌 채번결과)

필드명	타입	길이	설명
bankCode	String	3Byte	은행코드 (은행 코드 참고)
bankName	String	20Byte	은행명
accountNo	String	20Byte	채번계좌번호
depositName	String	20Byte	예금주 성명
expiryDate	String	14Byte	계좌사용만료일

paymentInfo > mobInfo(휴대폰 결제결과)

필드명	타입	길이	설명
authId	String	20Byte	인증ID
billId	String	20Byte	인증번호
mobileNo	String	11Byte	휴대폰번호
mobileCd	String	3Byte	이통사 코드

paymentInfo > cashReceiptInfo(현금영수증 발행결과)

필드명	타입	길이	설명
resCd	String	4Byte	결과코드
resMsg	String	1000Byte	결과 메시지
approvalNo	String	50Byte	승인번호
approvalDate	String	14Byte	승인일시(yyyyMMddHHmmss)

basketInfoList(장바구니 목록)

필드명	타입	길이	설명
productNo	String	20Byte	개별 상품 고유번호 거래등록 시 요청한 값 그대로 사용
sellerId	String	50Byte	셀러ID
productPgCno	String	20Byte	개별 상품 PG 거래고유번호 개별 상품 취소(환불) 시 필수

응답 예시

{
   // 신용카드 결제 승인응답
   "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",
      "approvalNo": "00017177",
      "approvalDate": "20210326090200",
      "cardInfo": {
         "cardNo": "45184211******81",
         "issuerCode": "029",
         "issuerName": "신한카드",
         "acquirerCode": "029",
         "acquirerName": "신한카드",
         "installmentMonth": 0,
         "freeInstallmentTypeCode": "00",
         "cardGubun": "N",
         "cardBizGubun": "P",
         "partCancelUsed": "Y",
         "couponAmount": 0
     }
   }
}

메시지 인증값

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

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