API Authentication

The EasyPay Simple Payment Only API uses the HMAC-SHA256 algorithm to ensure data integrity. For all API requests, you must include a Base64 encoded signature in the HTTP header, generated using your issued ChannelId and SecretKey.

---

Request Headers

The following four headers must be included when calling the API:

Header Name	Required	Description	Example
X-KICC-ChannelId	✅	Affiliate Channel ID	CH_A1B2C3D4
X-KICC-Timestamp	✅	Request timestamp (Milliseconds)	1701234567890
X-KICC-Nonce	✅	Unique request identifier (UUID v4 recommended)	550e8400-e29b...
X-KICC-Authorization	✅	HMAC Signature Data (Base64 Encoded)	dGhpcyBpcyBhIHN...

---

Signature Generation

The value for the X-KICC-Authorization header is constructed by combining key request details.

1. Message Construction

Concatenate the following five items in the exact order shown below (No separators/spaces):

ChannelId + RequestURI + Timestamp + Nonce + RequestBody

• RequestURI: The path excluding the domain (e.g., /v1/payment/approve).
• RequestBody: The raw JSON string of the data to be sent (Be careful with white spaces).

2. Encryption & Encoding

Hash the constructed string using the HMAC-SHA256 algorithm with your issued SecretKey as the key, then encode the result into a Base64 string.

Note

The SecretKey is provided separately by your sales representative upon affiliate registration.

Implementation Examples

Node.js

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

// 1. Issued Credentials
const channelId = 'CH_YOUR_ID';
const secretKey = 'YOUR_SECRET_KEY';

// 2. Request Information
const requestUri = '/smpy/kiccpay/reqAprv'; // Path excluding domain
const requestBody = JSON.stringify({
  mallId: '05500001',
  amount: 1004
}); // Raw JSON string to be sent

// 3. Header Values
const timestamp = Date.now().toString();
const nonce = uuidv4();

// 4. Generate Signature (ChannelId + URI + Timestamp + Nonce + Body)
const message = channelId + requestUri + timestamp + nonce + requestBody;
const signature = crypto.createHmac('sha256', secretKey)
                        .update(message)
                        .digest('base64'); // Base64 Encoding

// 5. Configure Headers
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. Request Information
        String requestUri = "/smpy/kiccpay/reqAprv";  // Path excluding domain
        String requestBody = "{\"mallId\":\"05500001\",\"amount\":1004}"; // JSON String
        String timestamp = String.valueOf(System.currentTimeMillis());
        String nonce = UUID.randomUUID().toString();

        // 2. Construct Message String
        String message = channelId + requestUri + timestamp + nonce + requestBody;
        
        // 3. HMAC-SHA256 Hashing
        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 Encoding
        String signature = Base64.getEncoder().encodeToString(rawHmac);

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

---

Security Requirements (TLS/SSL)

For security purposes, communication with the API server must use encrypted channels.

• Protocol: TLS 1.2 or higher is required.
• Deprecated: SSL v2, v3, and TLS 1.0, 1.1 are not supported due to security vulnerabilities.