API 인증

이지페이 간편결제 겾제전용 API는 데이터 무결성을 보장하기 위해 HMAC-SHA256 알고리즘을 사용합니다. 모든 API 요청 시, 발급받은 ChannelId와 SecretKey를 사용하여 생성한 Base64 인코딩 서명을 HTTP 헤더에 포함해야 합니다.

---

요청 헤더 (Request Headers)

API를 호출할 때 아래 4가지 헤더를 반드시 포함해야 합니다.

헤더 이름 (Header Name)	필수	설명	예시
X-KICC-ChannelId	Y	제휴사 발급 채널 ID	CH_A1B2C3D4
X-KICC-Timestamp	Y	요청 시점의 타임스탬프 (Millisecond)	1701234567890
X-KICC-Nonce	Y	요청 고유 식별값 (UUID v4 권장)	550e8400-e29b...
X-KICC-Authorization	Y	HMAC 서명 데이터 (Base64 Encoded)	dGhpcyBpcyBhIHN...

---

서명(Signature) 생성 방법

X-KICC-Authorization 헤더 값은 요청의 주요 정보를 조합하여 생성합니다.

1. 서명 대상 문자열 (Message Construction)

아래 5가지 항목을 순서대로 이어 붙여(Concatenate) 문자열을 만듭니다. 구분자(공백 등)는 없습니다.

ChannelId + RequestURI + Timestamp + Nonce + RequestBody

• RequestURI: 도메인을 제외한 경로 (예: /v1/payment/approve)
• RequestBody: 전송할 JSON 데이터 원본 문자열 (공백 주의)

2. 암호화 및 인코딩 (Encryption)

위 문자열을 발급받은 SecretKey 를 키(Key)로 사용하여 HMAC-SHA256 알고리즘으로 해싱한 후, Base64 문자열로 인코딩합니다.

참고

제휴사에 제공되는 SecretKey는 영업 담당자를 통해 별도 제공됩니다.

언어별 구현 예제

Node.js

const crypto = require('crypto');
const { v4: uuidv4 } = require('uuid');

// 1. 발급받은 정보
const channelId = 'CH_YOUR_ID';
const secretKey = 'YOUR_SECRET_KEY';

// 2. 요청 정보 설정
const requestUri = '/smpy/kiccpay/reqAprv'; // 도메인 제외 경로
const requestBody = JSON.stringify({
  mallId: '05500001',
  amount: 1004
}); // 실제 전송할 JSON 문자열

// 3. 헤더 값 생성
const timestamp = Date.now().toString();
const nonce = uuidv4();

// 4. 서명 생성 (ChannelId + URI + Timestamp + Nonce + Body)
const message = channelId + requestUri + timestamp + nonce + requestBody;
const signature = crypto.createHmac('sha256', secretKey)
                        .update(message)
                        .digest('base64'); // Base64 인코딩

// 5. 헤더 구성
const headers = {
  'Content-Type': 'application/json',
  'X-KICC-ChannelId': channelId,
  'X-KICC-Timestamp': timestamp,
  'X-KICC-Nonce': nonce,
  'X-KICC-Authorization': signature
};

console.log('Signature:', signature);

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.UUID;

public class AuthGenerator {
    public static void main(String[] args) throws Exception {
        String channelId = "CH_YOUR_ID";
        String secretKey = "YOUR_SECRET_KEY";

        // 1. 요청 정보
        String requestUri = "/smpy/kiccpay/reqAprv";  // 도메인 제외 경로
        String requestBody = "{\"mallId\":\"05500001\",\"amount\":1004}"; // JSON String
        String timestamp = String.valueOf(System.currentTimeMillis());
        String nonce = UUID.randomUUID().toString();

        // 2. 서명 대상 문자열 조합
        String message = channelId + requestUri + timestamp + nonce + requestBody;
        
        // 3. HMAC-SHA256 해싱
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        sha256_HMAC.init(secret_key);

        byte[] rawHmac = sha256_HMAC.doFinal(message.getBytes(StandardCharsets.UTF_8));
        
        // 4. Base64 인코딩
        String signature = Base64.getEncoder().encodeToString(rawHmac);

        System.out.println("X-KICC-Authorization: " + signature);
    }
}

---

보안 요구사항 (TLS/SSL)

보안을 위해 API 서버와의 통신은 암호화된 채널을 사용해야 합니다.

• 프로토콜: TLS 1.2 이상 필수 지원
• 지원 중단: SSL v2, v3 및 TLS 1.0, 1.1은 보안 취약점으로 인해 지원하지 않습니다.