본문으로 건너뛰기

인증

OOZOO PAY API 사용을 위한 HMAC-SHA256 서명 인증 가이드입니다.

API Key​

API 요청 인증에는 Client Key와 Secret Key가 필요합니다. 가맹점 대시보드에서 프로젝트별로 발급받을 수 있습니다.

Key형식용도
Client Keypk_xxx요청 헤더에 포함하여 프로젝트를 식별합니다
Secret Keysk_xxxHMAC 서명 생성에 사용합니다 (서버 사이드 전용)
Secret Key 보안

Secret Key는 절대 클라이언트(브라우저, 앱)에 노출되어서는 안 됩니다. 반드시 서버 사이드에서만 사용하시기 바랍니다.

필수 헤더​

모든 API 요청에 아래 헤더를 포함해야 합니다.

Header타입필수설명
X-Client-Keystring✓Client Key
X-Timestampstring✓Unix timestamp (초 단위)
X-Signaturestring✓HMAC-SHA256 서명값
Content-Typestring✓application/json

서명 생성 가이드​

Step 1. HMAC Key 생성​

Secret Key의 SHA-256 해시값을 HMAC Key로 사용합니다.

import * as crypto from 'crypto';

const hmacKey = crypto.createHash('sha256').update(secretKey).digest('hex');

Step 2. 서명 메시지 구성​

서명 대상 메시지는 아래 형식으로 구성합니다. 각 요소를 마침표(.)로 연결합니다.

{timestamp}.{method}.{path}.{body}

요소설명예시
timestampX-Timestamp 헤더와 동일한 값1706500000
methodHTTP 메서드 (대문자)POST
pathAPI 경로 (query string 포함)/api/invoices
body요청 본문의 JSON 문자열{"price":100,...}
body가 없는 경우

GET 요청 등 body가 없는 경우 빈 문자열("")을 사용합니다.

Step 3. HMAC-SHA256 서명 생성​

구성된 메시지에 대해 HMAC-SHA256 서명을 생성합니다.

const message = `${timestamp}.${method}.${path}.${body}`;
const signature = crypto.createHmac('sha256', hmacKey).update(message).digest('hex');

코드 예시​

POST 요청 (인보이스 생성)​

import * as crypto from 'crypto';

const clientKey = 'pk_xxxxxxxxxxxxxxxx';
const secretKey = 'sk_xxxxxxxxxxxxxxxx';

// 1. HMAC Key
const hmacKey = crypto.createHash('sha256').update(secretKey).digest('hex');

// 2. 요청 정보
const timestamp = Math.floor(Date.now() / 1000).toString();
const method = 'POST';
const path = '/api/invoices';
const body = JSON.stringify({
  price: 100,
  unit: 'usd',
  chainId: '11155111',
  tokenAddress: '0xaA8E...',
  sender: '0x1234...',
});

// 3. 서명 생성
const message = `${timestamp}.${method}.${path}.${body}`;
const signature = crypto.createHmac('sha256', hmacKey).update(message).digest('hex');

// 4. API 요청
const response = await fetch('https://api.oozoo.com/api/invoices', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-Key': clientKey,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body,
});

GET 요청 (인보이스 조회)​

const timestamp = Math.floor(Date.now() / 1000).toString();
const method = 'GET';
const path = '/api/invoices?page=1&limit=10';
const body = ''; // GET 요청은 빈 문자열

const message = `${timestamp}.${method}.${path}.${body}`;
const signature = crypto.createHmac('sha256', hmacKey).update(message).digest('hex');

const response = await fetch(`https://api.oozoo.com${path}`, {
  headers: {
    'X-Client-Key': clientKey,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
});

주의사항​

항목설명
Timestamp 유효성서버 시간 기준 ±5분 이내여야 합니다. 서버 시간이 동기화되어 있는지 확인하시기 바랍니다.
Body 직렬화JSON.stringify()로 직렬화한 문자열을 서명 메시지와 요청 본문에 동일하게 사용해야 합니다.
Path 형식Query string이 포함된 경우 query string까지 포함하여 서명합니다. (예: /api/invoices?page=1)
Method 대소문자HTTP 메서드는 반드시 대문자로 사용합니다. (GET, POST)