1. 인증 방식

모든 요청에 아래 3개 헤더가 필요합니다.

X-API-Key: kpch_xxxxxxxxxxxxxxxx
X-Timestamp: 1737000000        (현재 UNIX 타임스탬프, 5분 이내만 허용)
X-Signature: HMAC-SHA256(secret, "{timestamp}.{body}")

body는 POST 요청은 raw JSON 문자열, GET 요청은 쿼리스트링(예: code=xxxx)입니다. 서명은 반드시 hash_hmac('sha256', "{timestamp}.{body}", secret)와 동일한 방식으로 생성해야 합니다.

2. 결제요청 생성

POST https://kpchub.ginienm.com/api/payments_create.php

요청 본문(JSON):

{
  "merchant_order_id": "order-1234",   // 가맹점 측 주문번호(고유값, 1~100자)
  "amount": 1000,                       // 포인트 금액(정수, 1~10,000,000)
  "item_name": "투표권 10장"            // 선택
}

응답:

{
  "success": true,
  "data": {
    "payment_code": "a1b2c3...",
    "pay_url": "https://kpchub.ginienm.com/pay.php?code=a1b2c3...",
    "qr_text": "https://kpchub.ginienm.com/pay.php?code=a1b2c3...",
    "status": "pending",
    "expires_at": "2026-09-15 12:10:00",
    "idempotent_replay": false
  }
}

같은 merchant_order_id로 다시 요청하면 새로 만들지 않고 기존 결제를 그대로 반환합니다(멱등성 보장). pay_url을 QR코드로 만들어 보여주면 사용자가 KPC 허브 앱에서 스캔해 결제합니다. 결제 유효시간은 10분입니다.

3. 결제상태 조회

GET https://kpchub.ginienm.com/api/payments_status.php?code=xxxx

서명 대상 문자열은 "code=xxxx"입니다. 웹훅을 못 받았을 때 재확인용으로 사용하세요.

{
  "success": true,
  "data": {
    "payment_code": "a1b2c3...",
    "merchant_order_id": "order-1234",
    "amount": 1000,
    "item_name": "투표권 10장",
    "status": "paid",       // pending | paid | expired | canceled
    "paid_at": "2026-09-15 12:05:00",
    "expires_at": "2026-09-15 12:10:00"
  }
}

4. 웹훅(결제 완료 통보)

결제 상태가 바뀌면 등록하신 콜백 URL로 KPC 허브가 아래 형식으로 POST합니다.

POST {callback_url}
Content-Type: application/json
X-Signature: HMAC-SHA256(secret, "{timestamp}.{body}")
X-Timestamp: 1737000000

{
  "event": "payment.paid",
  "payment_code": "a1b2c3...",
  "merchant_order_id": "order-1234",
  "amount": 1000,
  "item_name": "투표권 10장",
  "status": "paid",
  "paid_at": "2026-09-15 12:05:00"
}

수신 측은 동일한 방식으로 서명을 재계산해 X-Signature와 비교(반드시 hash_equals 등 타이밍 공격에 안전한 방식 사용) 검증해야 합니다. 2xx 응답을 주지 않으면 실패로 기록되고 자동으로 최대 5회까지 재시도합니다. 200~299 외 응답이거나 타임아웃이면 실패 처리됩니다.

5. 서명 생성 예시 (PHP)

$timestamp = (string) time();
$body = json_encode(['merchant_order_id' => 'order-1234', 'amount' => 1000]);
$signature = hash_hmac('sha256', $timestamp . '.' . $body, $apiSecret);

$ch = curl_init('https://kpchub.ginienm.com/api/payments_create.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey,
        'X-Timestamp: ' . $timestamp,
        'X-Signature: ' . $signature,
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);