브랜드페이 | Bootpay 결제 매뉴얼

이 문서는 결제위젯에 user_token을 얹어 브랜드페이를 빠르게 붙이는 매뉴얼이에요. 브랜드페이 설정, 저장 결제수단 동작, 운영 흐름은 브랜드페이 상세 문서에서 이어서 확인해요.

브랜드페이는 가맹점에서 관리하는 로그인 회원에게 저장된 결제수단을 연결해주는 기능이에요. 이때 회원을 식별하는 방식이 user_token이에요. 프론트엔드는 기존 결제위젯 렌더링 payload에 서버에서 발급한 user_token만 추가로 전달하면 돼요.

데모 영상

사전 준비

결제위젯 연동이 먼저 완료되어 있어야 해요. 브랜드페이는 결제위젯 위에서 동작해요.
가맹점에서 관리하는 회원 식별값이 있어야 해요. 이 값을 user_id로 넣어 user_token을 발급해요.
관리자 → 결제위젯 → 사용할 위젯 선택 → 브랜드페이 탭에서 브랜드페이를 활성화해요. 브랜드페이는 위젯 단위로 설정해요.

연동 흐름

서버가 발급한 user_token을 결제위젯 렌더링 payload에 넣으면, 로그인 회원에게 저장된 결제수단이 표시돼요. 결제 완료 후에는 receipt_id를 백엔드로 보내 결제 정보를 검증하고 주문을 확정해야 해요.

구현 순서

user_token 발급 (백엔드)

결제 페이지 진입 시, 로그인된 회원의 user_token을 서버에서 발급해요. user_id에는 가맹점 DB의 회원 PK, user idx, UUID 등 회원을 구분할 수 있는 고유값을 넣어요. 토큰 유효시간은 1시간이에요.

app.get('/api/checkout', auth, async (req, res) => {
    const tokenResponse = await Bootpay.requestUserToken({
        user_id: req.user.id,
        email: req.user.email,
        username: req.user.name,
        phone: req.user.phone,
    })

    res.json({ user_token: tokenResponse.user_token })
})javascript

# Flask·Django 핸들러 안에서
token = bootpay.request_user_token(
    user_id=user.id,
    email=user.email,
    username=user.name,
    phone=user.phone,
)
# token.data['user_token']을 프론트로 응답python

// Laravel·Slim 컨트롤러 안에서
$token = BootpayApi::requestUserToken([
    'user_id' => $user->id,
    'email' => $user->email,
    'username' => $user->name,
    'phone' => $user->phone,
]);
// $token.data['user_token']을 프론트로 응답php

// Spring 컨트롤러 안에서
UserToken payload = new UserToken();
payload.userId = user.getId();
payload.email = user.getEmail();
payload.username = user.getName();
payload.phone = user.getPhone();

var token = bootpay.getUserToken(payload);
// token.get("user_token")을 프론트로 응답java

# Rails 컨트롤러 안에서
token = bootpay.get_user_token(
  user_id: user.id,
  email: user.email,
  name: user.name,
  phone: user.phone,
)
# token.data['user_token']을 프론트로 응답ruby

// net/http·Gin 핸들러 안에서
token, err := api.RequestUserToken(bootpay.UserTokenRequest{
    UserId: user.ID, Email: user.Email, Username: user.Name, Phone: user.Phone,
})
if err != nil { return }
// token["user_token"]을 프론트로 응답go

// ASP.NET Core 컨트롤러 안에서
var token = await bootpay.GetUserToken(new UserToken {
    userId = user.Id, email = user.Email, username = user.Name, phone = user.Phone,
});
// user_token을 프론트로 응답csharp

상세 문서: 회원 토큰 API

결제위젯에 user_token 전달 (프론트엔드)

기존 결제위젯 렌더링 코드에 user_token 한 줄만 추가해요. 나머지는 결제위젯과 동일해요.

const { user_token } = await fetch('/api/checkout').then(r => r.json())

BootpayWidget.render('#bootpay-widget', {
    client_key: 'YOUR_CLIENT_KEY',
    price: 39000,
    widget_key: 'default-widget',
    use_terms: true,
    user_token: user_token,   // 이 한 줄로 브랜드페이 활성화
})javascript

let userToken = try await fetchUserToken()  // /api/checkout
payload.clientKey = "YOUR_CLIENT_KEY"
payload.price = 39000
payload.widgetKey = "default-widget"
payload.widgetUseTerms = true
payload.userToken = userTokenswift

String userToken = fetchUserToken();  // /api/checkout

payload.setClientKey("YOUR_CLIENT_KEY")
       .setPrice(39000d)
       .setWidgetKey("default-widget")
       .setWidgetUseTerms(true)
       .setUserToken(userToken);java

// Payload의 userToken 한 줄만 추가하면 BootpayWidget이 브랜드페이로 동작한다.
final userToken = await fetchUserToken();  // /api/checkout

final payload = Payload()
    ..webApplicationId = BootpayEnvConfig.webApplicationId
    ..price = 39000
    ..widgetUseTerms = true
    ..widgetKey = 'default-widget'
    ..userToken = userToken;  // 이 한 줄

return BootpayWidget(payload: payload, controller: controller);dart

const userToken = await fetchUserToken()  // /api/checkout

const payload = {
    widget_key: 'default-widget',
    widget_use_terms: true,
    order_name: '테스트 상품',
    order_id: `order_${Date.now()}`,
    price: 39000,
    user_token: userToken,
}

<BootpayWidget
    ref={bootpayWidget}
    client_key={CLIENT_KEY}
    onWidgetReady={() => bootpayWidget.current?.renderWidget(payload)}
/>javascript

비로그인 사용자는 user_token 없이 렌더링해요. 이 경우 브랜드페이가 아니라 일반 결제위젯으로 결제를 진행해요.

결제 요청·검증 (백엔드)

BootpayWidget.requestPayment() 호출 후 받은 receipt_id는 백엔드로 전달해요. 서버에서는 결제위젯과 동일하게 결제 조회 API로 상태·금액·주문 정보를 확인한 뒤 주문을 확정해야 해요. 브랜드페이 여부와 무관하게 검증 기준은 receipt_id예요.

상세 문서: 결제 조회

다음 단계

브랜드페이 설정과 저장 결제수단 동작을 자세히 보려면 → 브랜드페이 상세 문서
일반 결제위젯 흐름을 다시 확인하려면 → 결제위젯

동작 방식

user_token 없음 → 일반 결제위젯
user_token + 저장된 수단 없음 → 일반 결제위젯 (첫 결제 완료 시 수단 자동 저장)
user_token + 저장된 수단 있음 → 원클릭 결제 UI

FAQ

비로그인 사용자도 쓸 수 있나?

구조적으로 맞지 않아요. 브랜드페이는 가맹점의 회원 계정에 저장된 결제수단을 다시 보여주는 기능이므로, 로그인 회원을 식별할 수 있을 때만 user_token을 발급해요.

다만 결제 자체를 막을 필요는 없어요. 비로그인 주문은 user_token 없이 결제위젯을 렌더링하면 일반 결제위젯으로 진행돼요.

토큰이 만료되면?

위젯 렌더링 시점에 만료되어 있으면 저장된 결제수단을 불러올 수 없어요. 결제 페이지에 진입할 때마다 서버에서 새 user_token을 발급해 내려주는 방식이 가장 단순해요.