결제 승인

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

정보

• 본 API는 PG 결제를 위해 제공되는 서비스 입니다.

주의사항

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

요청

일반결제

일반결제 요청 URL

POST https://{API 도메인}/easypay/payment/settle.do
Content-type: application/json; charset=euc-kr

에스크로결제

에스크로결제 요청 URL

POST https://{API 도메인}/easypay/payment/escrow/settle.do
Content-type: application/json; charset=euc-kr

참고

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

주의

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

파라미터

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

escrowInfo(에스크로 정보)

필드명	타입	길이	필수여부	설명
escrowTypeCode	String	1Byte	✅	에스크로 타입 "K" 고정
deliveryCode	String	4Byte	✅	배송구분 “DE01” : 자가배송 “DE02” : 택배배송
goodsInfoList	Array		✅	장바구니 목록(Max 20개) 아래 goodsInfoList 참조
recvInfo	Object		✅	구매자 상세정보 (아래 recvInfo 참조)

goodsInfoList(장바구니 목록)

필드명	타입	길이	필수여부	설명
productNo	String	40Byte	✅	개별 상품관리 번호
productName	String	50Byte	✅	개별 상품명
productAmount	Number		✅	개별 상품금액

주의

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

recvInfo(구매자 상세정보)

필드명	타입	길이	필수여부	설명
recvId	String	50Byte		구매자 ID
recvName	String	50Byte	✅	구매자 이름
recvMobileNo	String	11Byte	✅	구매자 연락처(숫자만 허용)
recvMail	String	100Byte	✅	구매자 이메일 주소
recvZipCode	String	6Byte		구매자 우편번호(숫자만 허용)
recvAddr1	String	100Byte		구매자 주소1
recvAddr2	String	100Byte		구매자 주소2

일반결제

요청 예시

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

에스크로결제

요청 예시

{  
   "mallId": "T5102001", 
   "shopOrderNo": "{제휴사 주문번호}", 
   "shopTransactionId": "{API 멱등성 키}",    
   "authorizationId": "{인증 거래번호}",
   "approvalReqDate": "{결제 승인요청 일자}",    
   "escrowInfo": {
     "escrowTypeCode": "K",
     "deliveryCode": "DE01",
     "goodsInfoList": [
        {
          "productNo": "{개별 상품 고유번호}",
          "productName": "{개별 상품명}",
          "productAmount": 1000
        }
     ],
     "recvInfo": {
       "recvName": "수취인명",
       "recvMobileNo": "수취인 연락처",
       "recvMail": "수취인 Email",
       "recvAddr": "수취인 주소",
       "recvZipCode": "수취인 우편번호",
       "recvAddr1": "수취인 주소1",
       "recvAddr2": "수취인 주소2"
     }
   }
}

응답

파라미터

필드명	타입	길이	설명
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	응답값의 무결성을 검증 (메시지 인증값 바로가기)
paymentInfo	Array		결제수단별 승인결과 정보 (아래 paymentInfo 참조)

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

필드명	타입	길이	설명
payMethodTypeCode	String	2Byte	결제수단 코드 (결제수단 코드 참고)
amount	Number		결제금액
approvalNo	String	100Byte	결제수단 승인번호
approvalDate	String	14Byte	결제수단의 승인일시 (yyyyMMddHHmmss)
maskingNo	String	20Byte	마스킹(*)된 결제수단 번호
payMethodDetailCode	String	3Byte	결제수단 세부코드 발급사 코드(카드사 코드 참고) 또는 은행 코드 (은행 코드 참고)
payMethodDetailCodeName	String	50Byte	결제수단 세부 명
cardInfo	Object		카드 승인정보 (아래 cardInfo 참조)
cashReceiptInfo	Object		현금영수증 발행 정보 (아래 cashReceiptInfo 참조)

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

필드명	타입	길이	설명
acquirerCode	String	3Byte	매입사 코드 (카드사 코드 참고)
acquirerName	String	50Byte	매입사 명
installmentMonth	Number		할부개월
isFreeInstallment	Boolean		무이자 여부
cardGubun	String	1Byte	신용카드 종류 (신용: “N”, 체크: “Y”, 기프트: “G”)

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

필드명	타입	길이	설명
resCd	String	4Byte	결과코드
resMsg	String	1000Byte	결과 메시지
approvalNo	String	50Byte	승인번호
approvalDate	String	14Byte	승인일시(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(거래일시)