서버 연동

API 인증

Basic Auth로 서버 API 호출 준비를 끝내요.

서버에서 Bootpay API를 호출할 때 Basic Auth로 인증해요. 별도의 토큰 발급 없이 매 요청마다 Authorization 헤더를 포함하면 돼요.

모든 서버 API 요청에 Authorization: Basic {credentials} 헤더를 추가해요. {credentials}client_key:secret_key를 Base64로 인코딩한 값이에요.

인증 방식

Authorization: Basic base64(client_key:secret_key)

예를 들어 client_keymy_client_key이고 secret_keymy_secret_key이면:

base64("my_client_key:my_secret_key") → "bXlfY2xpZW50X2tleTpteV9zZWNyZXRfa2V5"
Authorization: Basic bXlfY2xpZW50X2tleTpteV9zZWNyZXRfa2V5
연동키 확인 방법

백엔드 연동키(Client Key, Secret Key)는 관리자 콘솔 > 개발자 설정결제 연동키 탭에서 확인할 수 있어요.

Basic Auth가 현행 기본 방식이지만, 레거시 연동(Application ID + Private Key)은 POST /v2/request/token으로 발급한 액세스 토큰을 Authorization: Bearer {access_token}으로 보내는 방식도 계속 호환돼요. 신규 연동은 Basic Auth를 사용해요.

코드 예제

import { Bootpay } from '@bootpay/backend-js'

// SDK 사용 시 — SDK가 Basic Auth를 자동 처리한다
Bootpay.setConfiguration({
    client_key: '[ Client Key ]',
    secret_key: '[ Secret Key ]'
})

// 이후 API 호출 시 인증이 자동 적용된다
const receipt = await Bootpay.receiptPayment('receipt_id')javascript

에러 코드

공통 에러

인증·권한 관련 에러는 에러 코드표를 참고해요.

코드 메시지 대처 방법
APP_CLIENT_KEY_NOT_FOUND (1216) Client Key 정보를 찾지 못했습니다 관리자 > 개발자 설정의 결제 연동키 탭에서 Client Key를 다시 확인해요
APP_SK_NOT_MATCHED (1204) Private Key가 올바르지 않습니다. 부트페이 관리자에서 다시 확인해주시기 바랍니다. Secret Key(Private Key)를 다시 확인해요
APP_AT_AUTHORIZE_HEADER_BLANK (1206) Access Token을 HTTP Header에 Authorization으로 보내고 있는 확인해주시기 바랍니다. Authorization 헤더를 빠뜨리지 않았는지 확인해요

자주 발생하는 인증 에러

코드 메시지 대처 방법
API_ONLY_SELLER (600) 판매점 계정만 사용할 수 있는 API입니다. 판매점 계정의 연동키로 호출해요
APP_FIREWALL_BLOCKED (1203) 접근이 허가된 IP가 아닙니다. 관리자 [결제설정]->[연동키 및 보안] 에서 IP 보안 설정을 확인해주시기 바랍니다. (요청된 IP가 함께 표시돼요) 서버 아웃바운드 IP를 허용 목록에 추가해요
APP_AT_AUTHORIZE_TYPE_INVALID (1205) Access Token 인증 타입이 올바르지 않습니다. ex) Header Authorization에 인증 타입 'Bearer'가 빠져있는지 확인해주세요. 레거시 Bearer 방식이면 Bearer , Basic Auth면 Basic 접두어를 붙여요
APP_KEY_CHAIN_EXPIRED (1224) 발급받은 Client Key가 만료되었습니다. 관리자에서 다시 확인해주세요. 관리자에서 연동키 만료일을 확인하고 재발급해요
APP_CLIENT_KEY_EXPIRED (1218) 연동키 유효기간이 지나 API Scope 검증 단계에서 거절돼요 관리자에서 연동키를 재발급해요
API_ROLE_NOT_SUPPORT (1221) API Scope is not supported. key: {scope key} 호출한 API가 지원되는 Scope인지 확인해요
API_SCOPE_INVALID (1222) API Scope Not Configured. key: {scope key}, Please contact your administrator. 관리자에서 해당 연동키에 필요한 API Scope를 부여해요

백엔드 연동키(Client Key, Secret Key)는 백엔드에서만 써요. 프론트엔드에 노출하지 않아요.