페이북 QR·비밀번호 결제는 되는데 ISP 인증서 결제에서 설치 안내만 반복된다면 이 문서예요.
이 증상인지 먼저 확인해요
아래가 모두 맞으면 이 문서의 상황이에요.
- 페이북 앱 결제(QR)·비밀번호 결제는 정상 진행돼요
- 인증서 등록/결제(ISP)를 고를 때만 설치 안내가 반복되거나 멈춰요
- KB국민 · BC · 카카오뱅크 카드(ISP·페이북)에서 발생해요
- 크롬과 같은 Chromium 기반인 Edge 에서도 발생할 수 있어요
- 인증창 대신 ISP·보안 프로그램을 설치하라는 안내가 나오고, 설치해도 같은 안내가 다시 나와요
"설치가 안 된다" 로 보여서 구매자 PC나 회사망 문제로 판단하기 쉽지만, 대개는 이 문서의 상황이에요. 프로그램은 설치됐는데 결제창이 그 프로그램을 부르지 못해서 다시 설치하라고 안내하는 거예요. 같은 결제를 집 PC나 휴대폰 핫스팟에서 해 봐도 똑같이 막힌다면 사내망 문제가 아니에요.
브라우저 개발자도구(F12) → Console 에 아래와 비슷한 줄이 있어요.
Access to XMLHttpRequest at 'https://127.0.0.1:<포트>/' from origin 'https://<PG도메인>'
has been blocked by CORS policy: Permission was denied for this request to access
the `loopback` address space.개발자도구 Console 좌측 상단의 프레임 선택을 결제창 프레임으로 바꾸고 아래를 실행해요.
document.featurePolicy.allowsFeature('loopback-network')javascriptfalse 가 나오면 이 문서의 상황이에요.
왜 생기나요
BC카드를 고르면 페이북 창에 「페이북 앱 결제(QR)」「비밀번호 결제」「인증서 등록/결제(ISP)」가 나와요. 라이트페이→나이스페이의 BC카드 결제에서 60만원·120만원 모두 같은 화면이었어요.
「인증서 등록/결제(ISP)」를 누르면 기존 ISP 등록 카드도 금액과 무관하게 결제창 프레임이 https://127.0.0.1:55501 로 구매자 PC의 ISP 프로그램을 불러요. KB국민 · 카카오뱅크도 ISP 계열이라 같은 원리로 설명해요. 페이북 앱 결제(QR)·비밀번호 결제는 ISP 프로그램 없이 진행할 수 있어요.
크롬 142(2025년 10월)부터 로컬 네트워크 액세스(Local Network Access) 정책이 적용되면서, 웹사이트가 이 주소로 접근하려면 구매자의 권한 허용이 필요해졌어요. Edge 도 Chromium 기반이라 버전에 따라 같은 일이 생겨요.
부트페이나 PG 가 바뀐 게 아니라 브라우저 규칙이 바뀐 거예요. 그래서 같은 코드로 몇 년 잘 되던 쇼핑몰도 이 시점부터 ISP 인증서 결제가 막혀요.
문제는 결제창을 iFrame 으로 열었을 때예요. 이 권한은 다른 도메인의 iFrame 에 자동으로 내려가지 않아요(기본값이 self). iFrame 태그에 allow 속성이 있어야 내려가는데, 부트페이 SDK 5.5.1 까지는 결제 iFrame 에 이 속성이 없었어요. 결제 프레임 전부의 권한 상태가 denied라 권한을 묻는 팝업조차 뜨지 않고 조용히 거부돼요. 프로그램이 설치돼 있어도 「일반결제ISP 프로그램을 설치해주시기 바랍니다」가 반복되고, 15만원 실제 구매자 사례도 이 상황이었어요.
보안 헤더로는 해결되지 않아요
"우리 웹서버(Vercel·Next.js·nginx) 헤더가 조여서 그렇다" 고 판단하기 쉽지만 아니에요. 헤더를 고치는 방향으로는 해결되지 않아요.
크롬 · Windows UA · 라이트페이→나이스페이 · BC카드로 실제 측정한 결과예요 (60만원·120만원 카드결제).
| 상황 | 로컬 네트워크 접근 |
|---|---|
| 가맹점 페이지 자체 (최상위) | 허용 (헤더와 무관) |
open_type: 'popup' — 팝업 창과 그 안의 PG 결제 화면 |
prompt (허용 가능) |
open_type: 'iframe' · SDK 5.5.1 이하 — 결제창과 그 안의 PG 프레임 전부 |
denied (거부) |
open_type: 'iframe' · SDK 5.5.2 이상 — 결제창과 그 안의 PG 프레임 전부 |
prompt (허용 가능) |
open_type: 'redirect' — PC |
거부 (PC 는 페이지 이동 없이 iFrame 으로 떠요) |
iFrame + 서버에 Permissions-Policy: loopback-network=* 추가 |
거부 |
| 보안 헤더가 아예 없는 사이트의 iFrame | 거부 |
Vercel · Cloudflare Pages 등 호스팅과 무관하게 결과가 같았어요.
정리하면 이래요.
Permissions-Policy를 추가해도 iFrame 안은 그대로 거부돼요. 상위 페이지의 권한이 다른 도메인 iFrame 으로 내려가려면 iFrame 태그 쪽 설정이 함께 필요한데, 그건 결제 SDK 영역이에요. SDK 5.5.2 부터 부트페이가 결제 iFrame 에 이 설정을 달아요.- CSP 와는 무관해요. CSP 는 다른 도메인 iFrame 안으로 상속되지 않아요. 결제창 안에서 일어나는 통신은 PG 사이트의 정책을 따라요.
- 보안 헤더를 한 번도 설정한 적 없는 사이트에서도 똑같이 거부돼요. 브라우저 기본 동작이라서 그래요.
- 오히려
loopback-network=(self)처럼 잘못 적으면 없던 제약이 새로 생겨요.
해결 — SDK 를 5.5.2 이상으로 올려요
부트페이 SDK 5.5.2 부터 결제 iFrame 에 로컬 네트워크 권한을 넘겨주는 allow 속성이 붙어요. SDK 만 올리면 PC 는 지금처럼 iFrame 으로 열어도 ISP 인증서 결제가 막히지 않아요. 결과 처리 코드도 바꿀 필요가 없어요.
{
"dependencies": {
"@bootpay/client-js": "5.5.2"
}
}json<script src="https://js.bootpay.co.kr/bootpay-5.5.2.min.js"></script>htmlnpm 을 쓴다면 package.json 의 버전을 바꾼 뒤 npm install 로 package-lock.json 까지 함께 갱신해서 배포해요.
창 모드는 PC iframe, 모바일 redirect 를 권장해요.
import { Bootpay } from '@bootpay/client-js'
const isMobile = /Mobile|Android|iP(hone|od|ad)/i.test(navigator.userAgent)
await Bootpay.requestPayment({
client_key: '[ Client Key ]',
price,
order_name: '주문명',
order_id: orderId,
extra: {
// PC 는 iFrame, 모바일은 리다이렉트
open_type: isMobile ? 'redirect' : 'iframe',
// redirect일 때 필수예요
redirect_url: 'https://내도메인/order/result'
}
})javascriptSDK 5.5.1 이하에서는 PC 결제창을 popup 으로 열면 결제창이 최상위 창으로 떠서 권한이 정상 적용돼요(open_type: isMobile ? 'redirect' : 'popup'). PC 에서 redirect 를 고르면 페이지가 이동하지 않고 결제창이 iFrame 으로 떠서 해결되지 않아요.
모바일에는 팝업 개념이 없고 카카오톡·인스타그램 같은 인앱 브라우저에서 팝업이 막혀요. 모바일은 redirect 가 가장 안정적이에요. 모바일 ISP 는 앱으로 인증해서 이 문서의 증상과는 관계없어요. 자세한 비교는 창 모드 문서를 참고하세요.
바꾸면 무엇이 달라지나요
여기가 핵심이에요. 창 모드를 바꾸면 결제 결과를 받는 위치가 달라져요. 코드를 그대로 두고 옵션만 바꾸면 결제는 되는데 주문이 확정되지 않는 상태가 돼요.
| iFrame (기존) | Popup | Redirect | |
|---|---|---|---|
| 결과 받는 곳 | 프론트엔드 콜백 | 프론트엔드 콜백 | redirect_url 서버 라우트 |
| 결제 중 원래 페이지 | 유지 | 유지 | 떠나요 |
| 화면 상태(장바구니·폼) | 유지 | 유지 | 사라져요 |
| 추가 구현 | - | 거의 없음 | 서버 라우트 필요 |
Popup 으로 바꿀 때 (PC · SDK 5.5.1 이하)
결과 처리 코드는 그대로 두면 돼요. confirm · done · cancel · error 이벤트 흐름이 iFrame 과 같아요. 다만 두 가지를 확인해요.
- 구매자 클릭이 한 번 더 들어가요. 팝업 차단 정책 때문에 "결제 계속하기" 확인 단계가 자동으로 붙어요. 결제 완료율에 영향이 없는지 한 번 보세요.
- 결제 요청은 반드시 클릭 핸들러 안에서 호출해요. 버튼 클릭과
requestPayment()사이에await(서버로 주문 생성 요청 등)를 두면 브라우저가 팝업을 차단해요.
// ❌ 팝업이 차단돼요 — await 뒤에 호출하면 클릭과의 연결이 끊겨요
async function onClick() {
const order = await createOrder()
await Bootpay.requestPayment({ /* ... */ })
}
// ✅ 주문 생성을 먼저 끝내두고, 클릭 시점에는 바로 호출해요
async function onClick() {
await Bootpay.requestPayment({ order_id: preparedOrderId, /* ... */ })
}javascriptRedirect 로 바꿀 때 (모바일)
페이지가 결제창으로 완전히 이동했다가 돌아와요. 그래서 아래를 반드시 준비해야 해요.
redirect 는 프론트엔드 콜백이 호출되지 않아요. 서버 라우트를 만들지 않으면 결제 승인과 주문 확정이 아무 데서도 일어나지 않아요.
① 주문을 결제 요청 전에 서버에 저장해요
페이지를 떠나면 화면 메모리에 있던 값(장바구니, 배송지 폼, 쿠폰 선택)이 전부 사라져요. order_id 와 결제 금액, 주문 내용을 결제창을 띄우기 전에 서버 DB에 저장해 두세요. 돌아왔을 때 order_id 로 다시 찾을 수 있어야 해요.
② redirect_url 은 서버가 처리하는 주소여야 해요
Next.js 라면 Route Handler 나 API Route 여야 하고, 클라이언트 컴포넌트로는 안 돼요. 승인 API 호출에 시크릿 키가 필요해서 브라우저에서 처리할 수 없어요.
③ 쿼리로 넘어오는 값은 요약본이에요
event · receipt_id · order_id · status · message 가 쿼리 파라미터로 들어와요. 상세 결제 정보가 아니에요. 쿼리 값을 믿지 말고 서버 API 응답으로 금액과 상태를 확인해요 — confirm 이면 승인 API 의 응답, done 이면 결제 조회 API 의 응답이에요.
④ 승인은 서버에서 해요
event=confirm 은 "구매자 인증이 끝났고 승인 직전" 이라는 뜻이에요. 아직 결제가 완료된 게 아니에요. 서버에서 DB 주문 상태(재고 등)를 확인한 뒤 승인 API를 호출하고, 승인 API 가 돌려준 status · price 를 DB 주문과 대조해요. 승인 전에 조회 API를 따로 부를 필요는 없어요. 자세한 내용은 분리 승인 문서를 참고하세요.
import { NextRequest, NextResponse } from 'next/server'
export async function GET(req: NextRequest) {
const q = req.nextUrl.searchParams
const event = q.get('event')
const receiptId = q.get('receipt_id')
const orderId = q.get('order_id')
// 취소·실패는 주문을 미결제로 두고 안내 페이지로 보내요
if (event !== 'confirm' && event !== 'done') {
return NextResponse.redirect(new URL(`/orders/${orderId}/failed`, req.url))
}
// 이미 처리한 결제면 다시 승인하지 않아요 (뒤로가기·새로고침 대비)
const order = await findOrder(orderId)
if (order.status === 'paid') {
return NextResponse.redirect(new URL(`/orders/${orderId}/complete`, req.url))
}
// confirm: 서버에서 승인하고, 승인 응답으로 금액·상태를 확인해요
// done(분리 승인을 안 쓰는 경우): 이미 승인됐으니 조회 API 응답으로 확인해요
const payment = event === 'confirm'
? await bootpay.confirmPayment(receiptId)
: await bootpay.receiptPayment(receiptId)
if (payment.status !== 1 || payment.price !== order.price) {
await bootpay.cancelPayment({ receipt_id: receiptId, cancel_username: 'system' })
return NextResponse.redirect(new URL(`/orders/${orderId}/failed`, req.url))
}
await markOrderPaid(orderId, receiptId)
return NextResponse.redirect(new URL(`/orders/${orderId}/complete`, req.url))
}typescript⑤ 프론트엔드 try/catch 는 이동 전 상황만 잡아요
requestPayment() 의 catch 로는 결제창으로 이동하기 전에 발생한 취소·오류만 들어와요. 결제 결과는 여기로 오지 않아요.
⑥ 세션 쿠키가 SameSite=Strict 면 로그인이 풀려 보여요
결제창에서 돌아오는 것은 다른 사이트에서 넘어오는 이동이라, Strict 로 설정한 쿠키는 전송되지 않아요. 결과 페이지에서 비로그인 상태로 보이면 이걸 의심하세요. 세션 쿠키는 SameSite=Lax 로 두세요.
⑦ 새로고침·뒤로가기에 대비해요
구매자가 결과 페이지에서 새로고침하면 같은 receipt_id 로 라우트가 다시 실행돼요. 위 예시의 order.status === 'paid' 검사처럼 같은 주문을 두 번 승인하지 않도록 막아 두세요.
⑧ redirect_url 을 빠뜨리면 결제창이 아예 안 떠요
open_type: 'redirect' 인데 redirect_url 이 없으면 RC_REDIRECT_URL_INVALID 오류가 발생해요.
PC와 모바일을 다르게 쓴다면
양쪽 결과 처리를 모두 구현해야 해요. PC는 iFrame(또는 팝업) 콜백, 모바일은 서버 라우트예요. 한쪽만 만들면 그 경로로 들어온 구매자는 결제가 되고도 주문이 확정되지 않아요.
어느 경로에서든 결제 결과를 놓치지 않으려면 웹훅을 함께 사용하세요. 구매자가 결과 페이지 도착 전에 창을 닫아도 서버가 결과를 받을 수 있어요.
구매자에게 안내할 문구
SDK 를 올리거나 창 모드를 바꾸면 권한 허용 팝업이 정상적으로 뜨므로, 구매자는 허용을 누르면 돼요. 이미 거부한 구매자에게는 아래처럼 안내해요.
- 주소창 왼쪽 자물쇠 아이콘 클릭
- 사이트 설정 선택
- 크롬 145 이상은 기기의 앱, 크롬 142~144는 로컬 네트워크 액세스 항목을 허용 으로 변경
- 결제 페이지 새로고침 후 다시 시도
급하게 결제를 마쳐야 하는 구매자에게는 페이북 앱 결제(QR)·비밀번호 결제를 안내해요. ISP 프로그램 없이 진행할 수 있어요. Edge 로 바꿔서 되는 구매자도 있지만, Edge 도 Chromium 기반이라 버전에 따라 똑같이 막혀요.
점검 순서
- ISP(인증서 결제)를 고를 때만 막히고 페이북 QR·비밀번호 결제는 되는지 확인해요
- 결제창 프레임에서
document.featurePolicy.allowsFeature('loopback-network')가false인지 확인해요 - 보안 헤더는 건드리지 않아요 — 이 증상은 헤더로 해결되지 않아요
- 부트페이 SDK 를 5.5.2 이상으로 올려요. 창 모드는 PC
iframe· 모바일redirect— 바로 올릴 수 없으면 PC 는popup으로 열어요(PC 를redirect로 바꾸면 안 고쳐져요) redirect를 쓴다면redirect_url서버 라우트를 먼저 만들어요- 테스트 결제로 양쪽 경로 모두 주문이 확정되는지 확인해요



