연동키 발급 | Bootpay 결제 매뉴얼

새로 연동한다면 먼저 Client Key + Secret Key 한 쌍을 발급해요. 예전에 쓰던 Application ID · Private Key 는 레거시 방식이에요.

Bootpay를 예전부터 써본 사람은 Application ID, REST API Application ID, Private Key 이름이 더 익숙할 수 있어요. 하지만 신규 결제 연동은 권한·만료를 설정할 수 있는 Client Key + Secret Key 방식부터 보면 돼요.

먼저 어떤 키를 만들면 되나

처음 연동이라면 아래처럼 나눠서 생각해요.

상황	필요한 키	어디에 넣나
결제창·결제위젯을 띄운다	Client Key	프론트엔드 SDK
결제 조회·승인·취소를 서버에서 호출한다	Client Key + Secret Key	서버 환경변수
예전 코드가 `Application ID`를 쓰고 있다	레거시 키	유지 가능. 신규 개발은 Client Key로 전환 권장

관리자에서 새 연동키를 발급해야 Client Key와 Secret Key가 한 쌍으로 나와요.

키 두 종류

키	어디서 쓰나	노출
Client Key	결제창·결제위젯 호출, 서버 인증 헤더의 사용자 식별자	프론트엔드 코드에 들어갈 수 있음
Secret Key	서버 인증 헤더의 비밀값	서버 전용 — 프론트·Git·로그에 절대 포함 X

발급 방법

관리자 콘솔 → 개발자 설정 > 결제 연동키에서 새 키를 발급해요.

연동키 발급

발급 화면에서는 아래 값을 함께 정해요.

권한 범위 (Scope) — 이 키 한 쌍이 호출할 수 있는 API 묶음을 제한해요. 예: 결제 조회·취소만 허용, 빌링키 발급은 제외.
만료일 — 키 만료 시점을 지정해요. 만료된 키로 호출하면 인증 에러가 떨어져요.
이름 / 메모 — 어떤 용도의 키 쌍인지 식별용 라벨.

같은 프로젝트 안에서 여러 쌍을 발급할 수 있어요. 환경별·용도별로 나누면 한 키가 노출돼도 영향 범위를 줄이고, 폐기·재발급도 따로 처리할 수 있어요.

외부 협력사에 잠깐 넘기는 키 → 만료일 짧게, 조회 권한만 부여
운영 자동화 스크립트 → 만료일 길게, 필요한 API만 화이트리스트
신규 연동 검증 단계 → 만료일 짧게 끊어 임시 키로 테스트

Secret Key는 서버 코드와 환경변수에서만 다뤄야 해요. 프론트엔드 번들·Git 저장소·로그·스크린샷에 포함되는 순간 즉시 관리자 콘솔에서 해당 키 쌍을 폐기하고 새로 발급해야 해요.

키가 안 먹힐 때

API 호출에서 인증·권한 에러가 떨어지면 인증 관련 에러를 먼저 봐요. 자주 마주치는 코드:

에러 코드	무엇이 잘못됐나
`APP_KEY_NOT_FOUND`	Client Key 자체가 잘못됐거나 다른 프로젝트의 키
`APP_SK_NOT_MATCHED`	Secret Key가 Client Key와 짝이 맞지 않음
`APP_API_SCOPE_NOT_MATCHED`	키에 부여된 권한 범위(Scope) 에 호출 API가 없음 — 발급 화면에서 권한 추가
`APP_AT_AUTHORIZE_HEADER_BLANK`	`Authorization: Basic` 헤더 누락 또는 형식 오류
`AUTHENTICITY_TOKEN_EXPIRE`	인증 정보 무효 — 키 만료·폐기 여부 확인

예전 Application ID 방식과 헷갈린다면

기존 Application ID + Private Key 방식으로 연동된 코드는 계속 지원돼요. 다만 새로운 프로젝트를 시작하는 단계라면 신규 연동 방식인 Client Key + Secret Key 로 연동하길 권장해요.

이미 운영 중인 코드를 한 번에 바꿀 필요는 없어요. 레거시 키는 그대로 두고, 같은 관리자 화면에서 새 키 한 쌍을 추가로 발급해 신규 연동부터 적용해요.

레거시	신규
`Application ID` (클라이언트)	→ `Client Key`
`REST API Application ID` + `Private Key` (서버)	→ `Client Key` + `Secret Key` 한 쌍