서버에서 Bootpay API를 호출할 때 Basic Auth로 인증해요. 별도의 토큰 발급 없이 매 요청마다
Authorization헤더를 포함하면 돼요.
모든 서버 API 요청에 Authorization: Basic {credentials} 헤더를 추가해요. {credentials}는 client_key:secret_key를 Base64로 인코딩한 값이에요.
인증 방식
Authorization: Basic base64(client_key:secret_key)예를 들어 client_key가 my_client_key이고 secret_key가 my_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// SDK 없이 직접 호출할 때
const BASIC_AUTH = 'Basic ' + btoa(`${process.env.BOOTPAY_CLIENT_KEY}:${process.env.BOOTPAY_SECRET_KEY}`)
const res = await fetch('https://api.bootpay.co.kr/v2/receipt/receipt_id', {
method: 'GET',
headers: {
'Content-Type': 'application/json',
'Authorization': BASIC_AUTH
}
})javascriptfrom bootpay_backend import BootpayBackend
# SDK 사용 시 — SDK가 Basic Auth를 자동 처리한다
bootpay = BootpayBackend(client_key='CLIENT_KEY', secret_key='SECRET_KEY')
receipt = bootpay.receipt_payment('receipt_id')pythonuse Bootpay\ServerPhp\BootpayApi;
// SDK 사용 시 — SDK가 Basic Auth를 자동 처리한다
BootpayApi::setClientKeyConfiguration('CLIENT_KEY', 'SECRET_KEY');
$receipt = BootpayApi::receiptPayment('receipt_id');phpimport kr.co.bootpay.pg.Bootpay;
// SDK 사용 시 — SDK가 Basic Auth를 자동 처리한다
Bootpay bootpay = Bootpay.withClientKey("CLIENT_KEY", "SECRET_KEY");
var receipt = bootpay.getReceipt("receipt_id");javabootpay = Bootpay::Api.new(client_key: 'CLIENT_KEY', secret_key: 'SECRET_KEY')
receipt = bootpay.verify('receipt_id').datarubyimport "github.com/bootpay/backend-go/v2"
api := bootpay.NewAPIWithClientKey("CLIENT_KEY", "SECRET_KEY", nil, "")
receipt, err := api.GetReceipt("receipt_id")gousing Bootpay;
var bootpay = BootpayApi.WithClientKey("CLIENT_KEY", "SECRET_KEY");
var receipt = await bootpay.GetReceipt("receipt_id");csharp에러 코드
공통 에러
인증·권한 관련 에러는 에러 코드표를 참고해요.
| 코드 | 메시지 | 대처 방법 |
|---|---|---|
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)는 백엔드에서만 써요. 프론트엔드에 노출하지 않아요.
