결제 승인

정기 결제 승인 요청하는 API 입니다.

주의사항

• 응답 대기시간 초과 및 네트워크 오류로 응답을 받지 못한 경우 반드시 거래상태 조회를 통해 PG 거래고유번호를 조회 후 취소처리 바랍니다. 거래상태 조회 참고
• 승인결과의 결제금액과 상점의 결제금액이 상이할 시 반드시 취소처리 바랍니다.
• 승인결과에 대한 상점 DB 처리 실패 시 반드시 취소처리 바랍니다

요청

요청 URL

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

참고

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

주의사항

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

파라미터

필드명	타입	길이	필수여부	설명
mallId	String	8Byte	✅	KICC에서 부여한 상점ID
shopTransactionId	String	60Byte	✅	상점 거래고유번호 (API 멱등성 키)
shopOrderNo	String	40Byte	✅	상점 주문번호 반드시 Unique 값으로 생성
approvalReqDate	String	8Byte	✅	결제 승인요청일자(yyyyMMdd)
amount	Number		✅	결제요청 금액
currency	String	2Byte	✅	통화코드(원화 : “00”)
orderInfo	Object		✅	결제 주문정보 (아래 orderInfo 참조)
payMethodInfo	Object		✅	결제수단 정보 (아래 payMethodInfo 참조)
taxInfo	Object			복합과세 정보(복합과세 사용 시 필수) 아래 refundInfo 참조

orderInfo(주문 정보)

필드명	타입	길이	필수여부	설명
goodsName	String	50Byte	✅	상품명
customerInfo	Object			주문 고객정보 (아래 customerInfo 참조)

orderInfo > customerInfo(주문 고객정보)

필드명	타입	길이	필수여부	설명
customerId	String	20Byte		고객 ID
customerName	String	20Byte		고객명
customerMail	String	50Byte		고객 Email
customerContactNo	String	11Byte		고객 연락처(숫자만 허용)
customerAddr	String	200Byte		고객 주소

payMethodInfo(결제수단 정보)

필드명	타입	길이	필수여부	설명
billKeyMethodInfo	Object		✅	빌키 정보 (아래 billKeyMethodInfo 참조)
cardMethodInfo	Object		✅	신용카드 정보 (아래 cardMethodInfo 참조)

payMethodInfo > billKeyMethodInfo(빌키 정보)

필드명	타입	길이	필수여부	설명
batchKey	String	60Byte	✅	빌키 빌키 발급 응답의 cardNo 값

payMethodInfo > cardMethodInfo(신용카드 정보)

필드명	타입	길이	필수여부	설명
installmentMonth	Number		✅	할부개월
freeInstallmentUsed	Boolean			무이자 여부 true: 사용, false: 미사용
joinCd	String	4Byte		제휴서비스 코드

taxInfo(복합과세 정보)

필드명	타입	길이	필수여부	설명
taxAmount	Number		✅	과세 금액
freeAmount	Number		✅	비과세 금액
vatAmount	Number		✅	부가세 금액

요청 예시

{  
    "mallId": "T5102001", 
    "shopOrderNo": "{상점 주문번호}", 
    "shopTransactionId": "{API 멱등성 키}",       
    "approvalReqDate": "{요청 일자}",
    "amount": 1000,     
    "currency": "00",    
    "orderInfo": { 
        "goodsName": "예시 상품명" 
    }
    "payMethodInfo": {
        "billKeyMethodInfo": {
            "batchKey": "발급받은 빌키"
        },
        "cardMethodInfo":{
            "installmentMonth": 12
        }
    }
}

응답

파라미터

필드명	타입	길이	설명
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 참조)

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

필드명	타입	길이	설명
payMethodTypeCode	String	2Byte	결제수단 코드 (결제수단 코드 참고)
approvalNo	String	100Byte	결제수단 승인번호
approvalDate	String	14Byte	결제수단의 승인일시 (yyyyMMddHHmmss)
cpCode	String	4Byte	서비스 제공 기관코드(제휴 서비스사 코드 참고)로 간편결제, 포인트 결제 시 응답
cardInfo	Object		신용카드 결제결과 정보 (아래 cardInfo 참조)

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)
vanSno	String	12Byte	VAN 거래일련번호

응답 예시

{
   "resCd": "0000",
   "resMsg": "결제 정상",
   "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"
     }
   }
}

메시지 인증값

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

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