API 키

캔디페이 API 키로 상점의 SDK와 API 요청을 인증해요. 정산 웹훅의 서명은 보안 키로 검증할 수 있어요.

API 키 확인하기

관리자에 로그인하고 상점을 선택한 뒤 개발자 → API Keys에서 키를 확인하고 복사하세요. 클라이언트 키, 시크릿 키, 보안 키는 테스트·라이브 환경별로 발급돼요.

// 관리자에서 발급받은 테스트 키를 사용하세요.
const clientKey = "test_ck_8gmPHt6FgfAkzbRrysrZaJfb460J";
const secretKey = "test_sk_us9gfWyGFkOU2EK6I2OmM3U5b2pE";

API 키 이해하기

테스트 키와 라이브 키

테스트 키는 test_로 시작해요. 테스트 키로 요청한 결제도 실제로 승인되고 청구돼요. 소액으로 테스트하고 당일 안에 취소해주세요. 자세한 내용은 테스트 환경을 확인하세요.

라이브 키는 live_로 시작하며 운영 서비스에서 사용해요.

클라이언트 키와 시크릿 키

같은 상점·환경에서 발급한 클라이언트 키와 시크릿 키를 함께 사용하세요.

클라이언트 키는 브라우저에서 캔디페이 SDK를 초기화할 때 사용해요. test_ck_ 또는 live_ck_로 시작해요.

시크릿 키는 상점 서버에서 캔디페이 API를 호출할 때 사용해요. test_sk_ 또는 live_sk_로 시작해요. Basic 인증 헤더에 넣어 요청을 인증하세요.

보안 키

보안 키는 정산 웹훅의 서명을 검증할 때 사용해요. 32바이트 난수를 64자리 소문자 hex 문자열로 표현한 값이에요.

테스트·라이브 보안 키는 각각 독립적으로 발급돼요. 인증된 자격 증명 조회·발급·재발급 API 응답에서는 testSecurityKey, liveSecurityKey로 확인할 수 있어요. 정산 웹훅 검증에는 liveSecurityKey를 hex 디코딩해서 사용하세요.

시크릿 키와 보안 키는 상점 서버에 보관하세요. 브라우저 코드나 공개 저장소에 포함하지 마세요.

API 키 재발급하기

관리자 /developers/api-keys에서 재발급을 누르면 테스트/라이브 환경의 클라이언트 키, 시크릿 키, 보안 키가 즉시 교체돼요. API를 호출하는 서버와 웹훅을 검증하는 서버의 키를 함께 변경해주세요.

재발급 전에 서명한 웹훅은 교체 후에도 이전 키의 서명으로 도착할 수 있어요. 검증에 실패한 건은 정산 조회 API로 확인하세요.

API로 재발급할 때 동일한 Idempotency-Key를 보내면 기존 응답을 다시 받아요. 새로 재발급하려면 새 멱등성 키를 사용하세요.

시크릿 키 사용하기

관리자 개발자 → API Keys에서 사용할 환경의 시크릿 키를 복사하세요.
```
test_sk_us9gfWyGFkOU2EK6I2OmM3U5b2pE
```
시크릿 키 뒤에 :을 붙인 문자열을 Base64로 인코딩하세요.
터미널 창
```
echo -n 'test_sk_us9gfWyGFkOU2EK6I2OmM3U5b2pE:' | base64
```
인코딩한 값을 Authorization 헤더에 넣어 API를 호출하세요.
```
Authorization: Basic {ENCODED_SECRET_KEY}
```

Basic 인증

Authorization: Basic base64({USERNAME}:{PASSWORD})

HTTP Basic 인증은 사용자 ID와 비밀번호를 :으로 연결한 뒤 Base64로 인코딩하는 방식이에요. 캔디페이에서는 시크릿 키를 사용자 ID에 넣고 비밀번호를 비워둬요. 시크릿 키 뒤의 :은 빈 비밀번호를 구분하는 문자예요.

인증 정보를 암호화해서 전송할 수 있도록 API는 HTTPS로 호출하세요.