회원

쇼핑몰 구매자(회원)의 가입·이메일 인증·로그인·세션·내 정보·비밀번호·탈퇴·배송지와, 가맹점 서버가 회원을 옮기거나 관리하는 API 입니다.

모든 API 는 프로젝트 인증(Basic)이 필요합니다. 구매자 본인 API 는 여기에 더해 로그인으로 받은 JWT 를 Bootpay-User-JWT 헤더로 보냅니다 — 회원 JWT. 인증 절에 user_id 를 받는다고 적힌 본인 API 는 secretKey 인증일 때 JWT 대신 user_id(또는 login_id)로도 회원을 정할 수 있습니다(둘 다 오면 JWT 우선, 다른 회원이면 403 USER_NOT_MATCH). 예외로 세션 API(GET·DELETE /v1/users/session)는 JWT 전용입니다.

자주 쓰는 흐름

가입 → 로그인 → 내 정보

  1. GET /v1/users/signup-policy 로 가입 화면이 그릴 약관·필수 입력과 policy_version 을 받습니다.
  2. POST /v1/users/signup 으로 가입합니다. 가입은 JWT 를 발급하지 않습니다(requires_login: true).
    • 응답 status 가 standby 면 이메일 인증이 필요합니다. 회원이 메일 링크를 누르면 POST /v1/users/authenticate 로 인증을 완료합니다. 메일을 다시 보내려면 POST /v1/users/authenticate/:id/resend 를 씁니다.
  3. POST /v1/users/login 으로 로그인해 token 을 받습니다.
  4. 이후 본인 API(GET /v1/users/me 등)에 Bootpay-User-JWT: <token> 을 붙여 호출합니다. 로그아웃은 DELETE /v1/users/session 입니다.
    • 쇼핑몰 서버가 자기 로그인 세션으로 회원을 관리한다면 로그인 응답의 user_id 를 저장하고, user_id 를 받는 본인 API(비밀번호 변경·탈퇴·배송지·결제 토큰·지갑 등 각 API 의 인증 절 참고)에 JWT 대신 user_id 를 보내도 됩니다(secretKey 인증일 때만).

비밀번호 찾기 (로그아웃 상태, 3단계)

  1. POST /v1/users/password-recovery/requests — 아이디와 수단(email/phone)을 보내면 등록된 연락처로 인증코드가 갑니다. challenge_id 를 받습니다.
  2. POST /v1/users/password-recovery/verifications — challenge_id + 인증코드로 일회성 reset_token 을 받습니다.
  3. PUT /v1/users/password-recovery/password — reset_token 으로 새 비밀번호를 저장합니다. 이 회원의 기존 로그인은 모두 끊깁니다.

탈퇴 후 재가입 제한

탈퇴한 회원은 탈퇴 후 최소 7일 동안 같은 가입 정보로 다시 가입할 수 없습니다. 쇼핑몰 설정으로 이 기간을 더 길게 늘릴 수 있고, 7일보다 짧게 줄일 수는 없습니다. 실제 적용 기간은 GET /v1/users/me/withdrawal 의 rejoin_restriction.days 로 탈퇴 전에 안내할 수 있습니다.

제한 기간 안의 가입은 400 MEMBER_LEFT_RECENTLY 로 거절되며, payload 에 다음 값이 옵니다.

필드 설명
rejoin_available_at 재가입 가능 시각 (ISO 8601)
rejoin_block_code 문의 코드 (RJ-XXXX-XXXX). 구매자가 판매자에게 이 코드를 알려주면 판매자가 제한을 풀 수 있습니다

가입 API 두 가지

  • POST /v1/users/signup — 구매자 신규 가입. 약관 동의·가입 방식·중복·재가입 제한·이메일 인증을 모두 거칩니다. 브라우저 입력을 서버가 넘기는 용도입니다.
  • POST /v1/users/join — 가맹점이 기존 회원을 부트페이로 옮기는 동기화용. 약관·재가입 제한·이메일 인증을 거치지 않으므로 공개 가입 화면에 쓰지 마세요.

값 코드

필드 값
membership_type 1 회원, 2 비회원
corporate_type 1 개인, 2 기업, 3 부서
status 1 정상, 0 사용 중지, -1 탈퇴
gender -1 알 수 없음, 0 비공개, 1 남성, 2 여성

GET /v1/users/signup-policy

가입 화면을 그리기 전에 부릅니다. 가입 방식, 필수 입력, 회원가입 약관 목록과 정책 지문(policy_version)을 줍니다. POST /v1/users/signup 은 이 응답과 같은 목록으로 약관 동의를 검증합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_signup_policy
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

파라미터 없음.

응답

200 OK

{
  "signup_enabled": true,
  "membership_type": "id",
  "supported_member_types": ["individual"],
  "fields": {
    "name": { "required": true },
    "email": { "required": true },
    "phone": { "required": true },
    "address": { "required": false }
  },
  "terms": [
    {
      "term_id": "66f0...",
      "required": true,
      "title": "이용약관",
      "desc": "",
      "content": "<p>...</p>",
      "use_url": false,
      "url": null,
      "sort": 1,
      "updated_at": "2026-09-01T10:00:00+09:00"
    }
  ],
  "policy_version": "3f9a0c1b2d4e5f60"
}json
필드 타입 설명
signup_enabled boolean 가입 가능 여부. 쇼핑몰이 비활성이면 응답 대신 442 MALL_INACTIVE 가 오므로 응답에서는 항상 true 입니다
membership_type string 로그인 식별자. id(아이디 가입) | email(이메일 가입)
supported_member_types string[] 이 API 로 가입할 수 있는 회원 유형. 현재 individual(개인)만
fields object 입력 항목별 필수 여부 (name·email·phone·address)
terms array 회원가입 약관. sort, term_id 순
terms[].term_id string 약관 ID — 가입 시 term_ids 로 보냅니다
terms[].required boolean 필수 동의 여부
terms[].title / desc / content string 제목·요약·본문(HTML)
terms[].use_url / url boolean / string use_url 이 true 면 본문 대신 외부 URL 약관입니다 (content 가 비어 있음)
terms[].sort integer 표시 순서
terms[].updated_at string 약관 변경 시각
policy_version string 약관 목록과 필수 입력 설정의 지문(16자). 가입 요청에 그대로 보내면 그 사이 정책이 바뀌었는지 서버가 확인합니다

오류

HTTP error_code 언제
442 MALL_INACTIVE 쇼핑몰이 비활성 상태

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-21 추가

POST /v1/users/signup

구매자 신규 가입. 쇼핑몰 가입 정책(약관·가입 방식·중복·재가입 제한·이메일 인증)을 거칩니다. JWT 는 발급하지 않습니다 — 가입 후 POST /v1/users/login 으로 로그인합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_create
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body login_id string 아이디 가입 몰 O 영문·숫자 5~30자. 이메일 가입 몰에서는 쓰지 않습니다
body password string O 8자 이상, 72바이트 이하. 앞뒤 공백은 제거됩니다
body email string 이메일 가입 몰 O 100자 이하. 이메일 가입 몰에서는 로그인 식별자입니다
body name string O 50자 이하
body phone string 설정에 따라 숫자 8~15자리(하이픈 허용, 저장 시 제거). fields.phone.required 가 true 면 필수
body address object 설정에 따라 { zipcode, address, address_detail }. fields.address.required 가 true 면 zipcode·address 필수. 이 세 키 외에는 받지 않습니다
body address.zipcode string 5자리(구 우편번호 123-456 허용)
body address.address / address.address_detail string 각 100자 이하
body term_ids string[] 필수 약관이 있으면 O 동의한 약관 ID. 배열 또는 쉼표로 구분한 문자열
body policy_version string GET /v1/users/signup-policy 에서 받은 값. 보내면 정책이 바뀌었는지 확인하고, 안 보내면 확인하지 않습니다

다음 키는 보내면 거절​​합니다(400 API_PARAM_INVALID, payload.rejected_params): uid, ex_uid, external_uid, user_id, login_pw, user_group_id, is_group_admin, group, corporate_type, membership_type, status, role, join_at, extra.

응답

200 OK

가입 완료:

{
  "status": "finish",
  "user_id": "66f1...",
  "requires_login": true
}json

이메일 인증 대기:

{
  "status": "standby",
  "user_standby_id": "66f1...",
  "verification_context": "9c1e...",
  "requires_login": true
}json
필드 타입 설명
status string finish 가입 완료 | standby 이메일 인증 대기 | pending_approval 판매자 승인 대기
user_id string 만들어진 회원 ID (finish·pending_approval)
user_standby_id string 인증 대기 ID (standby). /v1/users/authenticate/:id 의 :id 입니다
verification_context string 인증 대기 소유 증명 값 (standby). 이 응답에서 한 번만 주므로 보관했다가 재발송·상태 조회에 보냅니다
requires_login boolean 항상 true — 로그인은 따로 합니다

오류

HTTP error_code 언제
400 API_PARAM_INVALID 받지 않는 키를 보냄(payload.rejected_params), address 가 객체가 아님
400 USER_NAME_BLANK 이름 없음
400 CUSTOMER_FIELD_TOO_LONG 길이 초과 (payload.field, payload.max_length)
400 USER_PASSWORD_FORMAT_INVALID 비밀번호 8자 미만
400 REQUIRED_PARAMETER_IS_MISSING 전화번호 수집 몰인데 phone 없음 (payload.field)
400 CUSTOMER_PHONE_INVALID 전화번호 형식 오류
400 USER_ADDRESS_BLANK 주소 수집 몰인데 우편번호·주소 없음
400 ADDRESS_ZIPCODE_INVALID 우편번호 형식 오류
400 USER_ID_BLANK / USER_ID_INVALID / USER_ID_EXIST (아이디 가입 몰) 아이디 없음 / 형식 오류 / 이미 사용 중
400 USER_EMAIL_BLANK / USER_EMAIL_INVALID / USER_EMAIL_EXIST 이메일 없음 / 형식 오류 / (이메일 가입 몰) 이미 사용 중
400 USER_PASSWORD_BLANK 비밀번호 없음
400 MEMBER_LEFT_RECENTLY 탈퇴 후 재가입 제한 기간 — 탈퇴 후 재가입 제한
409 SIGNUP_POLICY_VERSION_CHANGED policy_version 이 현재 정책과 다름. payload.policy_version 에 현재 값. 정책을 다시 조회해 동의를 받으세요
442 TERM_NOT_FOUND 목록에 없는 약관 ID (payload.term_ids)
442 REQUIRED_PARAMETER_IS_MISSING 필수 약관 미동의 (payload.field: "term_ids", payload.missing_term_ids)
442 MALL_INACTIVE 쇼핑몰이 비활성 상태

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-21 약관 동의·policy_version·address 검증 추가, 인증 대기 응답에 verification_context 추가
  • 2026-09-14 추가

GET /v1/users/authenticate/:id

가입 이메일 인증 대기 상태를 조회합니다. 인증 메일을 보낸 뒤 화면이 완료 여부를 확인할 때 씁니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: scope 검사 없음
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 가입 응답의 user_standby_id
query verification_context string 가입 응답의 값. 보내면 일치하는지 확인합니다

응답

200 OK

{
  "status": 3,
  "auth_email": false,
  "pending_approval": false,
  "email": "gos***@example.com",
  "client_key": "68a1...",
  "user_standby_id": "66f1...",
  "verification_state": "pending",
  "requires_login": true
}json
필드 타입 설명
verification_state string pending 대기 | verified 인증 완료 | expired 만료. 화면 분기에는 이 값을 쓰세요
auth_email boolean 이메일 인증 완료 여부
pending_approval boolean 인증은 끝났고 판매자 승인을 기다리는 중
email string 일부를 가린 이메일 (이메일 인증 몰에서만)
client_key string 프로젝트 clientKey
user_standby_id string 인증 대기 ID
status integer 내부 상태 숫자 (하위 호환용)
requires_login boolean 항상 true — 인증이 끝나도 토큰은 주지 않습니다

오류

HTTP error_code 언제
404 USER_STAND_BY_NOT_FOUND 이 프로젝트에 없는 ID
400 SIGNUP_CONTEXT_INVALID verification_context 불일치

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-21 프로젝트 범위 조회, verification_state·requires_login 추가

POST /v1/users/authenticate

인증 메일 링크의 토큰으로 이메일 인증을 완료합니다. 인증이 끝나면 회원이 만들어집니다(판매자 승인이 필요한 경우 승인 대기 상태로). 토큰은 발급하지 않습니다.

인증 링크는 메일 발송 후 30분 동안 유효합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: scope 검사 없음
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body token_key string O 인증 링크 경로 끝의 값(Base64) 그대로

응답

200 OK — GET /v1/users/authenticate/:id 와 같은 형식입니다. 이미 인증된 토큰이면 현재 상태를 그대로 돌려줍니다.

오류

HTTP error_code 언제
400 API_PARAM_INVALID token_key 가 Base64 가 아님 (payload.field)
404 USER_STAND_BY_NOT_FOUND 이 프로젝트에 없는 토큰
400 USER_EMAIL_AUTHENTICATE_EXPIRED 인증 시간(30분) 만료
500 USER_EMAIL_AUTHENTICATE_PROCESS_ERROR 인증 처리 중 서버 오류

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-21 인증된 프로젝트의 토큰만 처리

POST /v1/users/authenticate/:id/resend

인증 메일을 다시 보냅니다. 직전 발송 후 1분이 지나야 다시 보낼 수 있습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_signup_resend
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 가입 응답의 user_standby_id
body verification_context string O 가입 응답의 verification_context

응답

200 OK

{
  "accepted": true,
  "resend_after": "2026-09-23T10:01:00+09:00"
}json
필드 타입 설명
accepted boolean 항상 true
resend_after string 다음 재발송 가능 시각

오류

HTTP error_code 언제
400 SIGNUP_CONTEXT_INVALID verification_context 없음 또는 불일치
404 USER_STAND_BY_NOT_FOUND 이 프로젝트에 없는 ID
400 USER_EMAIL_AUTHENTICATE_EXPIRED 인증 시간 만료 또는 이미 인증됨 — 만료면 가입부터 다시 진행
400 USER_EMAIL_RECENTLY_SENT 1분 안에 다시 요청

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-21 추가

POST /v1/users/login

아이디(이메일 가입 몰은 이메일)와 비밀번호로 로그인해 회원 JWT 를 받습니다.

로그인 세션은 발급 후 1일 동안 유효합니다. 만료·로그아웃·비밀번호 변경 뒤에는 본인 API 가 401 USER_SESSION_INVALID 를 주므로 다시 로그인합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_login_token
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body login_id string O 아이디 또는 이메일. id 키로 보내도 됩니다
body password string O 비밀번호

이 API 는 회원을 증명하는 단계라 Bootpay-User-JWT·user_id 를 읽지 않습니다.

응답

200 OK

{
  "token": "eyJhbGciOiJSUzI1NiJ9...",
  "user_id": "66f1..."
}json
필드 타입 설명
token string 회원 JWT. Bootpay-User-JWT 헤더에 넣습니다
user_id string 회원 ID. JWT 대신 user_id 로 회원 API 를 부르는 쇼핑몰 서버는 이 값을 자기 로그인 세션에 저장합니다

오류

HTTP error_code 언제
404 USER_LOGIN_FAILED 없는 계정, 비밀번호 불일치, 사용 중지된 계정 (구분하지 않습니다)
400 USER_PENDING_APPROVAL 판매자 승인 대기 중인 계정
404 USER_LOGIN_SERVER_ERROR 서버 오류로 로그인 실패
442 MALL_INACTIVE 쇼핑몰이 비활성 상태

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 응답에 user_id 추가
  • 2026-09-23 문서 최초 작성

GET /v1/users/session

현재 JWT 의 로그인 회원 요약(이름·연락처는 가린 값)을 줍니다. 헤더 표시·로그인 여부 확인용입니다. 수정 폼을 채우려면 GET /v1/users/me 를 씁니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_session_detail
  • 회원 JWT(Bootpay-User-JWT): 선택 — 없거나 무효면 오류 없이 null 을 돌려줍니다

이 API 는 JWT 전용​​입니다. 대상이 회원이 아니라 "이 JWT 세션"이므로 user_id 로 회원을 정하지 않습니다. 가맹점 서버가 회원 정보를 보려면 GET /v1/users/:id 를 씁니다.

요청

파라미터 없음. user_id·user_ex_uid·user_external_uid·user_uid 를 보내면 400 API_PARAM_INVALID 로 거절합니다(payload.rejected_params).

응답

200 OK — 로그인 상태가 아니면 본문이 null 입니다.

{
  "user_id": "66f1...",
  "name": "홍​*​동",
  "phone": "010****5678",
  "email": "gos***@example.com",
  "identification": "gosomi84",
  "user_groups": [
    { "user_group_id": "66f1...", "corporate_type": 1 }
  ],
  "membership_type": 1,
  "is_ex": false,
  "pending_corporate_approval": false,
  "current_user_group": { "user_group_id": "66f1...", "corporate_type": 1 }
}json
필드 타입 설명
user_id string 회원 ID
name / phone / email string 일부를 가린 값
identification string 화면에 보여줄 로그인 식별자
user_groups array 소속 그룹(개인·기업·부서). 기업·부서면 그룹 정보와 role 이 더 붙습니다
membership_type integer 1 회원, 2 비회원
is_ex boolean 외부 동기화(POST /v1/users/join)로 들어온 회원
pending_corporate_approval boolean 기업 가입 승인 대기 중
current_user_group object | null 현재 선택된 그룹

오류

HTTP error_code 언제
400 API_PARAM_INVALID user_id 계열 파라미터를 보냄 — payload.rejected_params

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 scope user:user_session_detail 신설, user_id 계열 파라미터 거절
  • 2026-09-23 문서 최초 작성

DELETE /v1/users/session

로그아웃. 이 JWT 의 이 쇼핑몰 세션을 지웁니다. 이후 같은 JWT 로 본인 API 를 부르면 401 USER_SESSION_INVALID 가 옵니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_session_delete
  • 회원 JWT(Bootpay-User-JWT): 필수 (유효하지 않으면 401 USER_SESSION_INVALID)

이 API 는 JWT 전용​​입니다. 지울 세션은 JWT 가 정하므로 user_id 로는 로그아웃할 수 없습니다.

요청

파라미터 없음. user_id·user_ex_uid·user_external_uid·user_uid 를 보내면 400 API_PARAM_INVALID 로 거절합니다(payload.rejected_params) — 로그아웃되지 않습니다.

응답

200 OK — 본문은 boolean 입니다. 같은 JWT 에 다른 쇼핑몰의 세션이 남아 있으면 true, 없으면 false 입니다. 어느 쪽이든 이 쇼핑몰에서는 로그아웃됐습니다.

falsejson

오류

HTTP error_code 언제
401 USER_SESSION_INVALID JWT 없음, 이미 로그아웃·만료, 위조된 JWT
400 API_PARAM_INVALID user_id 계열 파라미터를 보냄 — payload.rejected_params

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 scope user:user_session_delete 신설, user_id 계열 파라미터 거절
  • 2026-09-23 문서 최초 작성

GET /v1/users/me

본인 프로필을 평문으로 줍니다. 수정 폼을 채우는 용도입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_me_detail
  • 회원: Bootpay-User-JWT 또는 user_id·login_id 중 하나 필수 — 회원 JWT. 둘 이상 보내면 JWT 가 우선이고, 서로 다른 회원이면 403 USER_NOT_MATCH 입니다. user_id·login_id 는 secretKey(Basic)·Bearer 인증일 때만 받습니다.
  • 범위: scope 키는 본인 프로필 용도를 표시합니다. user_id 로 이 몰의 어느 회원이든 지정할 수 있으므로, 로그인한 회원 본인의 값인지 확인하는 책임은 쇼핑몰 서버에 있습니다​.

요청

위치 이름 타입 필수 기본값 설명
query user_id string JWT 없으면 O 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다
query login_id string 로그인 아이디로 회원을 지정할 때. user_id 와 함께 보내면 같은 회원이어야 합니다

응답

200 OK

{
  "user": {
    "user_id": "66f1...",
    "name": "홍길동",
    "nickname": "길동",
    "email": "gildong@example.com",
    "phone": "01012345678",
    "login_id": "gildong01",
    "membership_type": 1,
    "gender": 1,
    "birth": "900101",
    "created_at": "2026-09-01"
  },
  "editable_fields": ["name", "nickname", "gender", "birth"],
  "profile_version": "a1b2c3d4e5f60718"
}json
필드 타입 설명
user.user_id string 회원 ID
user.name / nickname / email / phone string 평문 값
user.login_id string | null 로그인 아이디. 이메일 가입 몰이면 null
user.membership_type integer 1 회원
user.gender integer 값 코드
user.birth string 생년월일 6자리 (YYMMDD)
user.created_at string 가입일 (YYYY-MM-DD)
editable_fields string[] PATCH /v1/users/me 로 바꿀 수 있는 필드
profile_version string 수정 시 함께 보내 동시 수정을 막는 버전 값

오류

HTTP error_code 언제
401 USER_SESSION_INVALID JWT·user_id·login_id 모두 없음, 또는 JWT 세션 만료·로그아웃
401 USER_JWT_INVALID 위조·만료된 JWT
403 USER_NOT_MATCH JWT 회원과 user_id·login_id 회원이 다름
404 USER_NOT_FOUND user_id·login_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님
400 API_PARAM_INVALID secretKey 없이(client key 만으로) user_id·login_id 를 보냄 — payload.reason: merchant_auth_required

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id·login_id 로 정할 수 있게 변경(이전에는 JWT 전용)
  • 2026-09-21 추가

PATCH /v1/users/me

본인 프로필 수정. 보낸 필드만 바꾸고 보내지 않은 필드는 그대로 둡니다. 바꿀 필드가 없으면 저장하지 않고 현재 프로필을 돌려줍니다.

이메일·휴대폰은 로그인·본인확인 수단이라 이 API 로 바꿀 수 없습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_me_update
  • 회원: Bootpay-User-JWT 또는 user_id·login_id 중 하나 필수 — 회원 JWT. 둘 이상 보내면 JWT 가 우선이고, 서로 다른 회원이면 403 USER_NOT_MATCH 입니다. user_id·login_id 는 secretKey(Basic)·Bearer 인증일 때만 받습니다.
  • 범위: scope 키는 본인 프로필 용도를 표시합니다. user_id 로 이 몰의 어느 회원이든 지정할 수 있으므로, 로그인한 회원 본인의 값인지 확인하는 책임은 쇼핑몰 서버에 있습니다​.

요청

위치 이름 타입 필수 기본값 설명
body user_id string JWT 없으면 O 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다
body login_id string 로그인 아이디로 회원을 지정할 때(로그인 아이디를 바꾸는 값이 아닙니다). user_id 와 함께 보내면 같은 회원이어야 합니다
body name string 50자 이하. 빈 값 불가
body nickname string 30자 이하. 빈 문자열이면 닉네임을 비웁니다
body gender string -1, 0, 1, 2 중 하나
body birth string 숫자 6자리 (YYMMDD)
body profile_version string 마지막으로 읽은 profile_version. 보내면 그 사이 다른 곳에서 바뀌었는지 확인합니다

다음 키는 보내면 거절​​합니다(400 API_PARAM_INVALID): uid, ex_uid, external_uid, login_pw, password, role, group, user_group_id, is_group_admin, corporate_type, membership_type, status, email, phone, tel, comment, join_at, extra. payload.rejected_params 에 거절한 키가, email·phone 이 포함되면 payload.verification_required 에 그 키가 옵니다.

응답

200 OK — GET /v1/users/me 와 같은 형식(바뀐 값과 새 profile_version).

오류

HTTP error_code 언제
400 API_PARAM_INVALID 받지 않는 키(payload.rejected_params), gender·birth 형식 오류(payload.field)
400 USER_NAME_BLANK name 을 빈 값으로 보냄
400 CUSTOMER_FIELD_TOO_LONG 길이 초과 (payload.field, payload.max_length)
409 USER_PROFILE_VERSION_CHANGED profile_version 이 현재 값과 다름. payload.profile_version 에 현재 값. 다시 조회한 뒤 수정하세요
401 USER_SESSION_INVALID JWT·user_id·login_id 모두 없음, 또는 JWT 세션 만료·로그아웃
401 USER_JWT_INVALID 위조·만료된 JWT
403 USER_NOT_MATCH JWT 회원과 user_id·login_id 회원이 다름
404 USER_NOT_FOUND user_id·login_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님
400 API_PARAM_INVALID secretKey 없이(client key 만으로) user_id·login_id 를 보냄 — payload.reason: merchant_auth_required

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id·login_id 로 정할 수 있게 변경(이전에는 JWT 전용, user_id·login_id 는 거절 키였음)
  • 2026-09-21 추가

PUT /v1/users/me/password

본인 비밀번호 변경. 성공하면 이 회원의 모든 기기 로그인이 끊깁니다(요청한 기기 포함). 응답 뒤 다시 로그인하세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_me_password_update
  • 회원: Bootpay-User-JWT 또는 user_id 중 하나 필수 — 회원 JWT. 둘 다 보내면 JWT 가 우선이고, user_id 가 다른 회원이면 403 USER_NOT_MATCH 입니다. user_id 는 secretKey(Basic)·Bearer 인증일 때만 받습니다.

어느 방식이든 본인 확인은 current_password 가 합니다. Commerce 는 이 회원의 JWT 만 무효로 만들므로, user_id 로 부른 쇼핑몰 서버는 requires_login: true 를 받으면 자기 로그인 세션(쿠키 등)도 끊어야 합니다.

요청

위치 이름 타입 필수 기본값 설명
body user_id string JWT 없으면 O 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다
body current_password string O 현재 비밀번호
body new_password string O 8자 이상, 72바이트 이하. 현재 비밀번호와 달라야 합니다
body new_password_confirmation string 보내면 new_password 와 같은지 확인합니다

응답

200 OK

{
  "changed": true,
  "requires_login": true
}json

오류

HTTP error_code 언제
409 USER_PASSWORD_NOT_SET 비밀번호가 없는 계정(간편 로그인 전용). 비밀번호 찾기로 설정합니다
400 USER_PASSWORD_BLANK 현재 또는 새 비밀번호 없음
400 USER_LOGIN_PASSWORD_NOT_MATCH 현재 비밀번호 불일치
400 USER_PASSWORD_FORMAT_INVALID 새 비밀번호 8자 미만, 또는 현재와 같은 값
400 CUSTOMER_FIELD_TOO_LONG 새 비밀번호 72바이트 초과
400 USER_PASSWORD_CONFIRM_NOT_MATCH 확인 값 불일치
401 USER_SESSION_INVALID JWT·user_id 모두 없음, 또는 JWT 세션 만료·로그아웃 — 회원 JWT 참고
401 USER_JWT_INVALID 위조·만료된 JWT
403 USER_NOT_MATCH JWT 회원과 user_id 회원이 다름
404 USER_NOT_FOUND user_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님
400 API_PARAM_INVALID secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required

검증에서 거절되면 비밀번호와 로그인 상태는 바뀌지 않습니다.

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 JWT 없이 user_id 로도 회원을 정할 수 있게 변경
  • 2026-09-21 추가

GET /v1/users/me/withdrawal

탈퇴 화면이 그릴 정보: 탈퇴 가능 여부, 막는 이유, 본인 확인 방식, 개인정보 보관기간 선택지, 재가입 제한 기간, 안내 문구.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_me_withdrawal_detail
  • 회원: Bootpay-User-JWT 또는 user_id 중 하나 필수 — 회원 JWT. 둘 다 보내면 JWT 가 우선이고, user_id 가 다른 회원이면 403 USER_NOT_MATCH 입니다. user_id 는 secretKey(Basic)·Bearer 인증일 때만 받습니다.

요청

위치 이름 타입 필수 기본값 설명
query user_id string JWT 없으면 O 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다

응답

200 OK

{
  "withdrawable": false,
  "blockers": [
    { "type": "order", "count": 1 }
  ],
  "confirm_method": "password",
  "retention_options": [
    { "retention_type": "immediate", "label": "바로 폐기", "description": "탈퇴 즉시 모든 개인정보가 삭제돼요" },
    { "retention_type": "year_1", "label": "1년 보관 후 삭제", "description": "문의·분쟁 대응을 위해 1년 보관 후 자동으로 삭제돼요" },
    { "retention_type": "year_3", "label": "3년 보관 후 삭제", "description": "3년 보관 후 자동으로 삭제돼요" }
  ],
  "rejoin_restriction": { "enabled": true, "days": 30 },
  "guide_message": "탈퇴하면 적립금과 쿠폰이 모두 사라지고 되돌릴 수 없어요. ..."
}json
필드 타입 설명
withdrawable boolean 지금 탈퇴할 수 있는지
blockers array 막는 이유. type: subscription(이용 중인 정기구독) | order(진행 중인 주문), count: 건수
confirm_method string 본인 확인 방식. password(비밀번호 계정) | phrase(간편 로그인 전용 계정)
confirm_phrase string phrase 방식일 때 입력해야 하는 문구 (탈퇴합니다). password 면 없음
retention_options array 개인정보 보관기간 선택지
rejoin_restriction object enabled(항상 true), days(재가입 제한 일수, 최소 7) — 탈퇴 후 재가입 제한
guide_message string 탈퇴 전 유의사항. 쇼핑몰이 끄면 없음
guide_message_after string 탈퇴 완료 화면 문구. 쇼핑몰이 끄면 없음

오류

HTTP error_code 언제
442 WITHDRAWAL_NOT_ENABLED 쇼핑몰이 회원 탈퇴 기능을 쓰지 않음
403 USER_SESSION_INVALID 비회원
401 USER_SESSION_INVALID JWT·user_id 모두 없음, 또는 JWT 세션 만료·로그아웃 — 회원 JWT 참고
401 USER_JWT_INVALID 위조·만료된 JWT
403 USER_NOT_MATCH JWT 회원과 user_id 회원이 다름
404 USER_NOT_FOUND user_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님
400 API_PARAM_INVALID secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 JWT 없이 user_id 로도 회원을 정할 수 있게 변경
  • 2026-09-21 추가

POST /v1/users/me/withdrawal

본인 회원 탈퇴. 성공하면 현재 세션이 바로 끊기고, 이후 모든 본인 API 는 JWT 로 부르면 401 USER_SESSION_INVALID, 같은 user_id 로 부르면 404 USER_NOT_FOUND 를 줍니다. requires_login: true 를 받으면 저장한 JWT 와 쇼핑몰 서버의 로그인 세션을 지우고 로그인 화면으로 보내세요.

탈퇴 후 재가입은 탈퇴 후 재가입 제한을 따릅니다. 가맹점 관리용 DELETE /v1/users/:id 와 달리 진행 중 주문·구독 확인, 보관기간, 재가입 제한을 모두 거치므로 회원 본인의 탈퇴 버튼에는 이 API 를 쓰세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_me_withdrawal
  • 회원: Bootpay-User-JWT 또는 user_id 중 하나 필수 — 회원 JWT. 둘 다 보내면 JWT 가 우선이고, user_id 가 다른 회원이면 403 USER_NOT_MATCH 입니다. user_id 는 secretKey(Basic)·Bearer 인증일 때만 받습니다.

user_id 로 부를 때 간편 로그인 전용 계정(confirm_method: phrase)은 비밀번호가 없어 Commerce 가 본인을 확인할 수 없습니다(확인 문구는 고정값). 이 회원이 로그인한 상태에서 직접 탈퇴를 요청했는지는 쇼핑몰 서버가 책임지고 확인​​해야 합니다. 탈퇴는 되돌릴 수 없습니다.

요청

위치 이름 타입 필수 기본값 설명
body user_id string JWT 없으면 O 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다
body reason string O 탈퇴 사유. low_usage 자주 이용하지 않음, product 상품/서비스 불만족, benefit 가격/혜택 불만족, privacy 개인정보 우려, rejoin 새 계정으로 다시 가입 예정, etc 기타
body reason_text string 상세 사유
body retention_type string O 개인정보 보관기간. immediate | year_1 | year_3
body password string password 방식 O 현재 비밀번호
body confirm_phrase string phrase 방식 O 탈퇴합니다

응답

200 OK

{
  "withdrawn": true,
  "requires_login": true,
  "purge_scheduled_at": "2027-09-23T10:00:00.000+09:00"
}json
필드 타입 설명
withdrawn boolean 항상 true (실패는 오류로 옵니다)
requires_login boolean 항상 true
purge_scheduled_at string | null 보관 개인정보 파기 예정 시각. immediate 면 null

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING reason 없음 또는 목록에 없는 값
400 WITHDRAWAL_RETENTION_INVALID retention_type 없음 또는 잘못된 값
400 WITHDRAWAL_CONFIRM_INVALID 비밀번호 또는 확인 문구 불일치
442 WITHDRAWAL_BLOCKED_ACTIVE_SUBSCRIPTION 이용 중인 정기구독이 있음
442 WITHDRAWAL_BLOCKED_ACTIVE_ORDER 진행 중인 주문이 있음
442 WITHDRAWAL_NOT_ENABLED 쇼핑몰이 회원 탈퇴 기능을 쓰지 않음
403 USER_SESSION_INVALID 비회원
401 USER_SESSION_INVALID JWT·user_id 모두 없음, 또는 JWT 세션 만료·로그아웃 — 회원 JWT 참고
401 USER_JWT_INVALID 위조·만료된 JWT
403 USER_NOT_MATCH JWT 회원과 user_id 회원이 다름
404 USER_NOT_FOUND user_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님 — 이미 탈퇴한 회원 포함
400 API_PARAM_INVALID secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 JWT 없이 user_id 로도 회원을 정할 수 있게 변경
  • 2026-09-21 추가

POST /v1/users/password-recovery/requests

비밀번호 찾기 1단계. 이 쇼핑몰에 등록된 회원 연락처(이메일 또는 휴대폰)로 6자리 인증코드를 보냅니다.

계정이 있는지 드러내지 않기 위해 회원이 없어도, 연락처가 없어도, 발송이 실패해도 같은 응답​​을 줍니다. 받는 곳은 지정할 수 없습니다 — email, phone, contact 키를 보내면 거절합니다(세 단계 모두 같음).

회원은 login_id → challenge_id → reset_token 으로만 정해집니다. Bootpay-User-JWT 는 읽지 않고, user_id·user_ex_uid·user_external_uid·user_uid 키를 보내면 거절합니다(세 단계 모두 같음).

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_password_recovery
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body login_id string O 로그인 아이디 (이메일 가입 몰은 이메일)
body channel string O email | phone

응답

200 OK

{
  "accepted": true,
  "retry_after": 60,
  "challenge_id": "5c0e8f2a9b..."
}json
필드 타입 설명
accepted boolean 항상 true
retry_after integer 다시 요청할 수 있을 때까지 남은 초. 이 시간 안에 다시 요청하면 코드를 새로 보내지 않습니다
challenge_id string 2단계에 보낼 값

오류

HTTP error_code 언제
400 API_PARAM_INVALID channel 이 email/phone 이 아님(payload.field), 받는 곳 키 또는 user_id 계열 키를 보냄(payload.rejected_params)
400 USER_LOGIN_ID_BLANK login_id 없음

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 user_id 계열 키 거절(세 단계 모두)
  • 2026-09-21 추가

POST /v1/users/password-recovery/verifications

비밀번호 찾기 2단계. 인증코드를 확인하고 일회성 재설정 토큰을 줍니다. 인증코드는 발송 후 3분 안에 입력해야 하며, 여러 번 틀리면 이 요청은 더 쓸 수 없고 1단계부터 다시 해야 합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_password_recovery
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body challenge_id string O 1단계 응답의 값
body code string O 받은 6자리 인증코드

응답

200 OK

{
  "reset_token": "eyJhbGciOiJIUzI1NiJ9...",
  "expires_at": "2026-09-23T01:10:00Z"
}json
필드 타입 설명
reset_token string 3단계에 보낼 일회성 토큰
expires_at string 토큰 만료 시각 (UTC, 발급 후 10분)

오류

HTTP error_code 언제
400 FIND_PASSWORD_VERIFY_CODE_BLANK code 없음
404 VERIFICATION_CODE_EXPIRED 없는·이미 쓴·다른 쇼핑몰의 challenge_id
400 VERIFICATION_CODE_EXPIRED 코드 불일치 또는 3분 경과
400 VERIFICATION_ATTEMPT_EXCEEDED 시도 횟수 초과 — 1단계부터 다시

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-21 추가

PUT /v1/users/password-recovery/password

비밀번호 찾기 3단계. 재설정 토큰으로 새 비밀번호를 저장합니다. 회원은 토큰이 정하므로 아이디를 보내지 않습니다. 성공하면 이 회원의 기존 로그인이 모두 끊기고, 회원에게 변경 알림이 갑니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_password_recovery
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body reset_token string O 2단계 응답의 값. 한 번만 쓸 수 있습니다
body new_password string O 8자 이상, 72바이트 이하
body new_password_confirmation string 보내면 new_password 와 같은지 확인합니다

응답

200 OK

{
  "changed": true,
  "requires_login": true
}json

오류

HTTP error_code 언제
401 FIND_PASSWORD_RESET_TOKEN_INVALID 토큰 없음·위조·만료·다른 쇼핑몰의 토큰, 탈퇴한 회원
410 FIND_PASSWORD_RESET_TOKEN_USED 이미 사용한 토큰
400 USER_PASSWORD_BLANK 새 비밀번호 없음
400 USER_PASSWORD_FORMAT_INVALID 8자 미만
400 CUSTOMER_FIELD_TOO_LONG 72바이트 초과
400 USER_PASSWORD_CONFIRM_NOT_MATCH 확인 값 불일치

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-21 추가

GET /v1/users/address

회원 배송지 목록. 기본 배송지가 먼저, 그다음 최근 사용 순입니다. 페이지를 나누지 않습니다.

배송지 API 4종은 회원을 두 방식 중 하나로 정합니다.

  • JWT: Bootpay-User-JWT 를 보냅니다. 대상은 JWT 의 회원입니다. user_id 를 함께 보내면 본인일 때만 허용합니다(다르면 403 USER_NOT_MATCH).
  • user_id: JWT 없이 user_id 로 회원을 지정합니다. secretKey(Basic)·Bearer 인증일 때만 받습니다. 탈퇴한 회원은 찾지 않습니다.

scope 는 두 방식 모두 필요합니다. JWT 도 user_id 도 없으면 401 USER_SESSION_INVALID 입니다. 다른 회원의 배송지 ID 는 없는 배송지와 같은 404 로 답합니다.

user_id 는 24자리 회원 ID 형식이면 회원 ID, 아니면 가맹점 회원 고유 ID(external_uid)로 찾습니다. user_ex_uid·user_external_uid·user_uid 키도 받습니다. 로그인 아이디로 지정하려면 user_id 대신 login_id 를 보냅니다(둘 다 보내면 같은 회원이어야 합니다).

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_detail (JWT·user_id 모두)
  • 회원: Bootpay-User-JWT 또는 user_id 중 하나 필수 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
query user_id string JWT 없으면 O 회원 ID 또는 가맹점 회원 고유 ID(external_uid)

응답

200 OK

{
  "list": [
    {
      "address_id": "66f2...",
      "address_uid": "shop-addr-1",
      "alias_name": "집",
      "name": "홍길동",
      "phone": "01012345678",
      "zipcode": "06236",
      "address": "서울 강남구 테헤란로 1",
      "address_detail": "101호",
      "is_default": true
    }
  ],
  "count": 1
}json
필드 타입 설명
list[].address_id string 배송지 ID
list[].address_uid string | null 등록 시 보낸 가맹점 배송지 고유 ID
list[].alias_name string 별칭
list[].name / phone string 받는 사람 이름·연락처
list[].zipcode / address / address_detail string 우편번호·주소·상세주소
list[].is_default boolean 기본 배송지 여부 (회원당 최대 1개)
count integer 배송지 수

오류

HTTP error_code 언제
401 USER_SESSION_INVALID JWT 도 user_id 도 없음, 또는 JWT 세션이 유효하지 않음
401 USER_JWT_INVALID 위조·만료된 JWT
403 USER_NOT_MATCH JWT 회원과 user_id 회원이 다름
404 USER_NOT_FOUND (user_id) 없는 회원 또는 탈퇴한 회원
400 API_PARAM_INVALID secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 JWT 방식에도 scope 를 요구, user_ex_uid·user_external_uid·user_uid 키 추가
  • 2026-09-14 추가 (구매자·서버 호출 분리)

POST /v1/users/address

배송지 추가. 회원의 첫 배송지는 자동으로 기본 배송지가 됩니다. 호출 방식은 GET /v1/users/address를 봅니다.

address_uid 를 보내면 재시도에 안전합니다. 같은 회원이 같은 address_uid·같은 내용으로 다시 보내면 새로 만들지 않고 기존 address_id 를 돌려줍니다. 내용이 다르거나 다른 회원이 쓰는 address_uid 면 409 입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_create (JWT·user_id 모두)
  • 회원: Bootpay-User-JWT 또는 user_id 중 하나 필수 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body user_id string JWT 없으면 O 회원 ID 또는 external_uid
body name string O 받는 사람. 50자 이하
body phone string O 숫자 8~15자리 (하이픈 허용)
body zipcode string O 5자리 (구 우편번호 123-456 허용)
body address string O 200자 이하
body address_detail string O 200자 이하
body alias_name string 배송지 별칭. 50자 이하
body is_default boolean false true 면 기본 배송지로 지정
body address_uid string 가맹점 배송지 고유 ID. 100자 이하. ex_uid, external_uid, uid 키도 받습니다

응답

200 OK

{
  "address_id": "66f2..."
}json

오류

HTTP error_code 언제
400 API_PARAM_INVALID 필수 필드 누락
400 CUSTOMER_PHONE_INVALID 전화번호 형식 오류
400 ADDRESS_ZIPCODE_INVALID 우편번호 형식 오류
400 CUSTOMER_FIELD_TOO_LONG 길이 초과 (payload.field, payload.max_length)
409 ADDRESS_ALREADY_EXISTS address_uid 가 다른 내용·다른 회원·삭제된 배송지에 이미 쓰임
404 USER_GROUP_NOT_FOUND 회원의 개인 그룹을 찾거나 만들 수 없음
401 / 403 / 404 USER_SESSION_INVALID · USER_JWT_INVALID / USER_NOT_MATCH / USER_NOT_FOUND GET /v1/users/address 와 같음

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 JWT 방식에도 scope 를 요구
  • 2026-09-14 address_uid 재시도 처리, 입력 형식 검증 추가

PUT /v1/users/address/:address_id

배송지 수정. 보낸 필드만 바꿉니다. PATCH 도 같습니다. 이미 주문에 쓰인 배송지를 고쳐도 기존 주문의 배송지는 바뀌지 않습니다. 호출 방식은 GET /v1/users/address를 봅니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_update (JWT·user_id 모두)
  • 회원: Bootpay-User-JWT 또는 user_id 중 하나 필수 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path address_id string O 배송지 ID
body user_id string JWT 없으면 O 회원 ID 또는 external_uid
body name / phone / zipcode / address / address_detail string 보낸 값만 반영. 빈 값으로 지울 수 없습니다
body alias_name string 빈 값이면 무시
body is_default boolean true 기본 배송지로 지정, false 해제

바꿀 필드와 is_default 가 모두 없으면 400 API_PARAM_INVALID 입니다.

응답

200 OK

{
  "address_id": "66f2..."
}json

오류

HTTP error_code 언제
404 ADDRESS_NOT_FOUND 없는·삭제된·다른 회원의 배송지
400 API_PARAM_INVALID 바꿀 값이 없음, 필수 필드를 빈 값으로 보냄
400 CUSTOMER_PHONE_INVALID / ADDRESS_ZIPCODE_INVALID / CUSTOMER_FIELD_TOO_LONG 형식·길이 오류
401 / 403 / 404 USER_SESSION_INVALID · USER_JWT_INVALID / USER_NOT_MATCH / USER_NOT_FOUND GET /v1/users/address 와 같음

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 JWT 방식에도 scope 를 요구
  • 2026-09-14 추가

DELETE /v1/users/address/:address_id

배송지 삭제. 기본 배송지를 지우면 가장 최근에 쓴 배송지가 기본 배송지가 됩니다. 기존 주문의 배송지에는 영향이 없습니다. 호출 방식은 GET /v1/users/address를 봅니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_update (JWT·user_id 모두)
  • 회원: Bootpay-User-JWT 또는 user_id 중 하나 필수 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path address_id string O 배송지 ID
query user_id string JWT 없으면 O 회원 ID 또는 external_uid

응답

200 OK

{
  "success": true
}json

오류

HTTP error_code 언제
404 ADDRESS_NOT_FOUND 없는·이미 삭제된·다른 회원의 배송지
401 / 403 / 404 USER_SESSION_INVALID · USER_JWT_INVALID / USER_NOT_MATCH / USER_NOT_FOUND GET /v1/users/address 와 같음

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 JWT 방식에도 scope 를 요구
  • 2026-09-14 추가

POST /v1/users/join

가맹점의 기존 회원을 부트페이 회원으로 옮깁니다(외부 동기화). 약관 동의·탈퇴 후 재가입 제한·이메일 인증을 거치지 않으므로 서버 간 이관 전용​​입니다. 구매자 신규 가입은 POST /v1/users/signup 을 씁니다. JWT 는 발급하지 않습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_create
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body name string O 이름
body ex_uid string 가맹점 회원 고유 ID. 프로젝트 안에서 중복 불가. external_uid, uid 키도 받습니다
body login_id string 아이디 가입 몰 O 영문·숫자 5~30자
body login_email string 이메일 가입 몰 O email 값 로그인 이메일
body login_pw string O 8자 이상. extra.skip_password 가 true 면 생략 가능(비밀번호 없는 계정)
body email string 연락 이메일
body phone / tel string 휴대폰·전화번호
body nickname string 닉네임
body comment string 판매자 메모
body gender integer 값 코드
body birth string 생년월일 6자리
body individual_extension object 가맹점 정의 추가 정보
body join_at string 요청 시각 원래 가입일 (시각 문자열)
body user_group_id string 추가로 소속시킬 그룹 ID
body is_group_admin boolean false 그 그룹의 관리자로 지정
body extra object skip_password 만 사용

응답

200 OK — 회원 상세. 형식은 GET /v1/users/:id 와 같습니다.

오류

HTTP error_code 언제
400 API_PARAM_INVALID name 없음
400 USER_EXTERNAL_UID_EXIST 이미 쓰는 ex_uid
400 USER_ID_BLANK / USER_ID_INVALID / USER_ID_EXIST (아이디 가입 몰) 아이디 없음 / 형식 오류 / 이미 사용 중
400 USER_EMAIL_BLANK / USER_EMAIL_INVALID / USER_EMAIL_EXIST 로그인 이메일 없음 / 형식 오류 / 이미 사용 중
400 USER_PASSWORD_FORMAT_INVALID login_pw 없음 또는 8자 미만

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

GET /v1/users/join/:id

가입 전 중복 확인. :id 에 확인 종류를, pk 에 확인할 값을 넣습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_check_exist
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O email-exist | id-exist | phone-exist | uid-exist(회원 ID·external_uid) | group-business-number-exist(기업 사업자번호)
query pk string O 확인할 값
  • phone-exist: 하이픈·공백을 빼고 비교합니다. 010-1234-5678 과 01012345678 은 같은 번호입니다.
  • email-exist: 앞뒤 공백만 빼고 가입 때 받은 값과 그대로 비교합니다. 이메일을 수집하지 않는 몰에서 가입한 회원은 찾지 못해 false 가 옵니다.

응답

200 OK

{
  "exist": true,
  "data": null
}json
필드 타입 설명
exist boolean 이미 있으면 true
data object | null group-business-number-exist 로 찾은 기업 그룹 정보. 다른 종류는 null

오류

HTTP error_code 언제
400 API_PARAM_INVALID pk 없음, 지원하지 않는 확인 종류

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 phone-exist 가 항상 false 이던 결함 수정(저장 해시와 같은 방식으로 비교)
  • 2026-09-23 문서 최초 작성

GET /v1/users/join/:id/detail

회원 ID·external_uid·로그인 아이디로 회원 상세를 조회합니다. 탈퇴한 회원도 조회됩니다(status: -1).

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_detail
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 회원 ID 또는 external_uid

응답

200 OK — 형식은 GET /v1/users/:id 와 같습니다.

오류

HTTP error_code 언제
400 USER_NOT_FOUND 없는 회원

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

POST /v1/users/login/token

서버 전용. 비밀번호 없이 회원을 지정해 회원 JWT 를 발급합니다. 가맹점이 자체 로그인을 끝낸 회원을 부트페이 쇼핑몰 세션으로 넘길 때 씁니다. 이 API 를 부를 수 있는 키는 어떤 회원으로든 로그인할 수 있으므로 secretKey 를 절대 브라우저·앱에 두지 마세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_login_token
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body user_id string O 회원이면 회원 ID 또는 로그인 아이디(이메일 가입 몰은 이메일). 비회원이면 가맹점이 정한 비회원 고유 ID
body membership_type string member member | guest
body corporate_type string individual individual | corporate — 세션을 열 그룹 (회원만)

membership_type: "guest" 이면 user_id 로 비회원을 찾고, 없으면 그 ID 로 비회원을 새로 만든 뒤 토큰을 발급합니다.

응답

200 OK

{
  "token": "eyJhbGciOiJSUzI1NiJ9..."
}json

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING user_id 없음 — payload.field: user_id
400 INVOICE_TARGET_NOT_FOUND (회원) 해당하는 정상 회원이 없음
400 USER_CORPORATE_TYPE_INVALID corporate_type 이 individual/corporate 가 아님
400 MALL_CORPORATE_TYPE_NOT_ALLOWED 기업 회원을 받지 않는 쇼핑몰에 corporate 요청
400 USER_GROUP_NOT_FOUND 요청한 유형의 그룹이 회원에게 없음
400 USER_PENDING_APPROVAL 판매자 승인 대기 중인 계정
404 USER_LOGIN_FAILED 사용 중지된 계정 등 로그인 불가

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 user_id 누락 응답을 404 API_PARAM_INVALID → 400 REQUIRED_PARAMETER_IS_MISSING 으로 변경
  • 2026-09-23 문서 최초 작성

POST /v1/users/token

로그인 회원의 부트페이 결제 사용자 토큰과 결제 위젯 키를 받습니다. 저장된 결제수단을 여는 토큰이므로 서버에서만 호출하세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_token
  • 회원: Bootpay-User-JWT 또는 user_id 중 하나 필수 — 회원 JWT. 둘 다 보내면 JWT 가 우선이고, user_id 가 다른 회원이면 403 USER_NOT_MATCH 입니다. user_id 는 secretKey(Basic)·Bearer 인증일 때만 받습니다.

요청

위치 이름 타입 필수 기본값 설명
body user_id string JWT 없으면 O 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다

응답

200 OK

{
  "user_token": "...",
  "application_id": "...",
  "normal_widget_key": "...",
  "subscription_widget_key": "..."
}json
필드 타입 설명
user_token string 부트페이 결제 사용자 토큰
application_id string 결제 연동 application ID
normal_widget_key / subscription_widget_key string 일반·정기 결제 위젯 키

오류

HTTP error_code 언제
401 USER_SESSION_INVALID JWT·user_id 모두 없음, 또는 JWT 세션 만료·로그아웃
401 USER_JWT_INVALID 위조·만료된 JWT
403 USER_NOT_MATCH JWT 회원과 user_id 회원이 다름
404 USER_NOT_FOUND user_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님
400 API_PARAM_INVALID secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required
400 USER_NO_LOGIN_ID 로그인 아이디가 없는 계정
500 API_NOT_PERMIT 부트페이 결제 서버가 토큰 발급을 거절

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원을 Bootpay-User-JWT 또는 user_id 로 정하도록 변경(이전에는 항상 401), scope user:user_token 신설
  • 2026-09-23 문서 최초 작성

POST /v1/users/wallet

회원 그룹의 결제수단(지갑) 목록을 돌려줍니다. 부트페이 결제 서버가 새 지갑을 알려 주면 반영한 뒤 돌려줍니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_wallet
  • 회원: Bootpay-User-JWT 또는 user_id 중 하나 필수 — 회원 JWT. 둘 다 보내면 JWT 가 우선이고, user_id 가 다른 회원이면 403 USER_NOT_MATCH 입니다. user_id 는 secretKey(Basic)·Bearer 인증일 때만 받습니다.

요청

위치 이름 타입 필수 기본값 설명
body user_id string JWT 없으면 O 회원 ID(24자리) 또는 가맹점 회원 고유 ID(external_uid). user_ex_uid·user_external_uid·user_uid 키도 받습니다
body corporate_type integer O 지갑을 볼 그룹. 1 개인, 2 기업

응답

200 OK — 지갑 목록 배열. 등록된 지갑이 없으면 []. 빌링키는 포함하지 않습니다.

오류

HTTP error_code 언제
401 USER_SESSION_INVALID JWT·user_id 모두 없음, 또는 JWT 세션 만료·로그아웃
401 USER_JWT_INVALID 위조·만료된 JWT
403 USER_NOT_MATCH JWT 회원과 user_id 회원이 다름
404 USER_NOT_FOUND user_id 가 이 쇼핑몰의 (탈퇴하지 않은) 회원이 아님
400 API_PARAM_INVALID secretKey 없이(client key 만으로) user_id 를 보냄 — payload.reason: merchant_auth_required
404 USER_GROUP_NOT_FOUND 요청한 유형의 그룹이 없음
500 API_NOT_PERMIT 부트페이 결제 서버가 요청을 거절

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원을 Bootpay-User-JWT 또는 user_id(또는 login_id) 로 정하도록 변경(이전에는 항상 401), scope user:user_wallet 신설
  • 2026-09-28 응답을 지갑 목록으로 고정(이전에는 없는 메서드 호출로 항상 500)
  • 2026-09-23 문서 최초 작성

GET /v1/users

회원 목록(판매자·서버용). 정상 상태 회원만, 최근 가입 순입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_list
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
query type string user user 회원 검색 | user_group 그룹 소속 회원
query keyword string type=user: 회원 ID, 또는 이름·전화번호·이메일 전체 값​(부분 일치 안 됨, 하이픈·대소문자 차이는 허용). type=user_group: 그룹 ID
query membership_type integer 전체 1 회원, 2 비회원
query page integer 1 1 이상
query limit integer 24 최대 100

이 API 는 페이지네이션 공통 규칙과 다릅니다. 기본 limit 이 24 이고, page·limit 에 1 미만 값을 보정하지 않으므로 1 이상 값을 보내세요.

응답

200 OK

{
  "list": [
    {
      "user_id": "66f1...",
      "login_id": "gildong01",
      "name": "홍길동",
      "phone": "01012345678",
      "email": "gildong@example.com",
      "membership_type": 1,
      "corporate_type": 1,
      "status": 1,
      "user_groups": [],
      "social_login_providers": [],
      "created_at": "2026-09-01T10:00:00+09:00",
      "updated_at": "2026-09-01T10:00:00+09:00"
    }
  ],
  "count": 1
}json

list 항목은 GET /v1/users/:id 응답에서 deletable 을 뺀 형식입니다. count 는 조건에 맞는 전체 수입니다.

오류

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-03 keyword 가 하이픈·대소문자가 다른 표기도 찾도록 변경

GET /v1/users/:id

회원 상세(판매자·서버용). 탈퇴한 회원은 400 USER_DELETED 입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_detail
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 회원 ID 또는 external_uid

응답

200 OK — 값이 없는 필드는 응답에서 빠집니다.

{
  "user_id": "66f1...",
  "external_uid": "shop-user-1",
  "login_id": "gildong01",
  "login_types": [1],
  "name": "홍길동",
  "phone": "01012345678",
  "email": "gildong@example.com",
  "membership_type": 1,
  "corporate_type": 1,
  "gender": 1,
  "birth": "900101",
  "comment": "VIP",
  "tags": [],
  "auth_sms": false,
  "auth_phone": false,
  "auth_email": true,
  "count": 3,
  "status": 1,
  "user_groups": [
    {
      "user_group_id": "66f1...",
      "corporate_type": 1,
      "zip": "06236",
      "addr1": "서울 강남구 테헤란로 1",
      "addr2": "101호"
    }
  ],
  "social_login_providers": [],
  "created_at": "2026-09-01T10:00:00+09:00",
  "updated_at": "2026-09-20T12:00:00+09:00"
}json
필드 타입 설명
user_id string 회원 ID
external_uid string 가맹점 회원 고유 ID
login_id string 로그인 아이디
login_types integer[] 가입 방식
name / phone / email string 평문 값
membership_type / corporate_type / gender / status integer 값 코드
birth string 생년월일 6자리
comment string 판매자 메모
tags / metadata / individual_extension array / object 판매자·가맹점이 붙인 태그와 추가 정보
auth_sms / auth_phone / auth_email boolean 인증 완료 여부
count integer 결제 횟수
user_groups array 소속 그룹(개인·기업·부서)과 그룹 연락처·주소
social_login_providers array | null 연결된 간편 로그인 공급자 코드. 일반 가입이면 []
removed_at string 탈퇴 시각 (탈퇴 회원)
withdrawal_reason / withdrawal_reason_text string 셀프 탈퇴 사유 (탈퇴 회원)
withdrawal_retention_type string 탈퇴 시 선택한 보관기간 (탈퇴 회원)
purged_at string 개인정보 파기 완료 시각
withdrawal_block_code string 재가입 문의 코드 RJ-XXXX-XXXX (탈퇴 회원)
deletable boolean (비회원만) 청구서·주문 이력이 없어 삭제할 수 있는지
created_at / updated_at string 생성·수정 시각

오류

HTTP error_code 언제
400 USER_NOT_FOUND 없는 회원
400 USER_DELETED 탈퇴한 회원

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

PUT /v1/users/:id

회원 정보 수정(판매자·서버용). 값이 있는 필드만 바꾸며, 빈 값으로 지울 수 없습니다. PATCH 도 같습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_update
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 회원 ID 또는 external_uid
body name string 이름
body phone / tel string 휴대폰·전화번호 (하이픈 제거 후 저장)
body email string 이메일. 이메일 수집 몰이면 형식을 확인합니다
body nickname string 닉네임
body gender integer 값 코드
body birth string 생년월일 6자리
body comment string 판매자 메모
body bank_username / bank_account / bank_code string 환불 계좌 예금주·계좌번호·은행 코드
body login_id string 로그인 아이디 (형식·중복을 확인하지 않습니다)
body password string 새 비밀번호. login_pw 키도 받습니다. 형식을 확인하지 않고, 기존 로그인을 끊지 않습니다
body phone_hash / email_hash string 로그인·검색용 연락처 값
body marketing_accept_type integer 마케팅 수신 동의 유형

group.company_name, group.business_number, group.registration_number, login_type, term_ids 는 받지만 반영하지 않습니다.

응답

200 OK — 수정된 회원 상세. 형식은 GET /v1/users/:id 와 같습니다.

오류

HTTP error_code 언제
404 USER_NOT_FOUND 없는 회원
400 USER_EMAIL_INVALID 이메일 형식 오류

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

DELETE /v1/users/:id

회원을 탈퇴 상태(status: -1)로 바꿉니다(판매자·서버용). 이 회원의 기존 로그인은 모두 거부됩니다.

본인 탈퇴(POST /v1/users/me/withdrawal)와 달리 진행 중 주문·구독 확인, 개인정보 파기·보관 처리, 탈퇴 후 재가입 제한을 거치지 않습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:user_delete
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 회원 ID 또는 external_uid

응답

200 OK — 탈퇴 처리된 회원 상세. 형식은 GET /v1/users/:id 와 같습니다.

오류

HTTP error_code 언제
400 USER_NOT_FOUND 없는 회원
400 USER_DELETED 이미 탈퇴한 회원

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

함께 보기