회원 토큰 | Bootpay 결제 매뉴얼

브랜드페이 및 지갑결제를 사용하기 위한 회원 토큰(UserToken)을 발급해요.

서버에서 부트페이 API를 호출하여 회원토큰을 발급받아요. 회원토큰은 브랜드페이(간편결제 자체 구축) 및 지갑결제 기능을 사용할 때 필요해요. 가맹점의 회원 정보를 부트페이에 연동하여, 해당 회원이 등록한 결제 수단(카드, 계좌 등)을 저장·재사용할 수 있게 해요.

일반 결제(PG 결제창 호출)만 사용하는 경우에는 회원토큰이 필요하지 않아요.

API 엔드포인트

POSThttps://api.bootpay.co.kr/v2/request/user/tokenBasic Auth

회원토큰은 발급 후 1시간 동안 유효해요. 브랜드페이·지갑결제 화면을 띄우기 직전에 발급해 클라이언트로 전달하고, 만료되면 다시 발급해요. 회원 식별은 user_id 기준이라, 재발급하더라도 같은 회원은 이전에 등록한 결제수단을 그대로 재사용해요.

요청 파라미터

파라미터	타입	필수	설명
`user_id`	String	필수	회원 고유 ID (회원 로그인 ID 권장)
`email`	String	선택	회원 이메일 주소
`username`	String	선택	회원 이름
`phone`	String	선택	회원 전화번호
`gender`	Number	선택	회원 성별 (1: 남자, 0: 여자)
`birth`	String	선택	회원 생년월일

email을 넣지 않아도 user_id가 이메일 형식이면 서버가 그 값을 email로 대신 채워요.
phone은 하이픈(-)을 서버에서 제거한 뒤 저장하고, 남은 자릿수가 8~12자를 벗어나면 USER_PHONE_INVALID로 거절해요.
gender를 넣지 않으면 -1(미상)로 저장돼요.

코드 예제

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

Bootpay.setConfiguration({
    client_key: '[ Client Key ]',
    secret_key: '[ Secret Key ]'
})

try {
    const response = await Bootpay.requestUserToken({
        user_id: 'user_12345',
        email: 'user@example.com',
        username: '홍길동',
        phone: '01012345678',
        gender: 1
    })
    // user_token을 프론트엔드에 전달
    console.log(response)
} catch (e) {
    console.log(e)
}javascript

from bootpay_backend import BootpayBackend

bootpay = BootpayBackend(client_key='CLIENT_KEY', secret_key='SECRET_KEY')

response = bootpay.request_user_token(
    user_id='user_12345',
    email='user@example.com',
    username='홍길동',
    phone='01012345678',
    gender=1
)
print(response)python

use Bootpay\ServerPhp\BootpayApi;

BootpayApi::setClientKeyConfiguration('CLIENT_KEY', 'SECRET_KEY');
$response = BootpayApi::requestUserToken([
    'user_id' => 'user_12345',
    'email' => 'user@example.com',
    'username' => '홍길동',
    'phone' => '01012345678',
    'gender' => 1,
]);
print_r($response);php

import kr.co.bootpay.pg.Bootpay;
import kr.co.bootpay.pg.model.request.UserToken;

Bootpay bootpay = Bootpay.withClientKey("CLIENT_KEY", "SECRET_KEY");
UserToken userToken = new UserToken();
userToken.userId = "user_12345";
userToken.email = "user@example.com";
userToken.username = "홍길동";
userToken.phone = "01012345678";
userToken.gender = 1;

var response = bootpay.getUserToken(userToken);
System.out.println(response);java

bootpay = Bootpay::Api.new(client_key: 'CLIENT_KEY', secret_key: 'SECRET_KEY')
response = bootpay.get_user_token(
  user_id: 'user_12345',
  email: 'user@example.com',
  name: '홍길동',
  phone: '01012345678',
  gender: 1
)
puts response.dataruby

import "github.com/bootpay/backend-go/v2"

api := bootpay.NewAPIWithClientKey("CLIENT_KEY", "SECRET_KEY", nil, "")
response, err := api.RequestUserToken(bootpay.UserTokenRequest{
    UserId:   "user_12345",
    Email:    "user@example.com",
    Username: "홍길동",
    Phone:    "01012345678",
    Gender:   1,
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(response)go

using Bootpay;
using Bootpay.models;

var bootpay = BootpayApi.WithClientKey("CLIENT_KEY", "SECRET_KEY");
var response = await bootpay.GetUserToken(new UserToken
{
    userId = "user_12345",
    email = "user@example.com",
    username = "홍길동",
    phone = "01012345678",
    gender = 1
});
Console.WriteLine(response);csharp

응답

성공 응답

{
  "user_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expired_at": "2025-01-15T15:32:00+09:00"
}json

응답 파라미터

파라미터	타입	설명
user_token	String	1시간 유지되는 Token 값 (SDK에 전달하여 사용)
expired_at	Date	Token 만료 시간

에러 코드

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

코드	메시지	대처 방법
`USER_ID_BLANK` (1500)	user_id를 입력해주세요	`user_id`를 반드시 전달해요
`USER_EMAIL_INVALID` (1501)	사용자 이메일 정보가 이메일 포맷에 맞지 않습니다. 다시 확인해주세요.	`email` 형식을 확인해요. `user_id`가 이메일 형식이면 자동으로 대입되므로 그 값도 함께 확인해요
`USER_PHONE_INVALID` (1502)	사용자 전화번호 정보가 전화번호 자리수에 맞지 않습니다. 다시 확인해주세요.	하이픈을 제거한 `phone`이 8~12자인지 확인해요

회원정보(email, username, phone, gender, birth)는 프로젝트별로 생성된 암호화 키로 암호화해 저장하고, 결제 진행 등 필요한 시점에 같은 키로 복호화해 사용해요. 결제·통계 목적으로만 쓰이며 제3자에게 제공하지 않아요.