고객 이해하기 | Bootpay 커머스 매뉴얼

핵심 요약

customer는 checkout과 주문에 연결되는 구매자 계정 원장이에요.
email, phone, custom fields를 어떻게 쓸지 먼저 정하면 중복 체크와 SSO 흐름이 단순해져요.
check-exist는 가입 직전 검증용이고, login-token은 이미 식별된 고객을 checkout에 이어 붙이는 용도예요.
고객 모델을 안정적으로 잡아야 일반 쇼핑몰, 구독, B2B 마켓플레이스가 같은 기반 위에서 움직여요.

이 기능이 왜 필요한지·무엇을 먼저 정할지는 블로그에서 다뤄요.

결제만 붙이면 되나요, 주문까지 해야 하나요? — 고객 식별을 commerce에 맡길지 결정하는 판단 틀

이런 상황이라면

비회원 결제보다 회원 기반 재구매 흐름이 중요하다면 customer 모델을 먼저 만들어야 해요. 같은 이메일이나 전화번호로 중복 가입이 자주 생겨요면 check-exist를 가입 앞단에 넣어야 해요. 자체 로그인 시스템이 있고 checkout에서 Bootpay 고객 세션만 연결하고 싶다면 login-token이 핵심이에요.

고객 문서는 회원관리 전체를 대체하는 것이 아니라 구매자 식별을 commerce에 연결하는 기준을 제공해요.

1고객 모델

customer 모델은 결제만을 위한 임시 입력값이 아니라, 주문과 구독을 묶는 구매자 식별 단위예요.

기본 필드는 다음과 같아요.

필드	역할	비고
`email`	대표 식별자	로그인 ID 또는 알림 채널로 활용
`phone`	보조 식별자	본인 확인, 알림, 중복 체크
`custom fields`	서비스별 확장 필드	사번, 회원등급, 외부 CRM 키 등

핵심은 어떤 값을 canonical 키로 쓸지 정하는 것이에요.

이메일을 기준으로 묶을 것인가
전화번호를 1차 식별자로 둘 것인가
외부 회원번호를 custom field로 넣을 것인가

이 기준이 모호하면 중복 고객이 쉽게 생기고, 주문 이력과 구독 이력이 갈라져요.

2중복 체크

check-exist는 고객을 실제 생성하기 전에 특정 키가 이미 존재하는지 확인하는 단계예요. 이 문서는 가입 성공 API가 아니라 방어용 API라고 이해하면 돼요.

중복 체크가 필요한 대표 상황은 다음과 같아요.

자체 회원가입 폼에서 이메일 중복을 바로 막아야 할 때
전화번호가 이미 Bootpay customer에 등록되어 있는지 확인해야 할 때
외부 회원번호나 사업자번호를 유일 키로 관리할 때

흐름은 단순해요.

프론트 또는 서버에서 가입 전 값을 받아요.
check-exist로 동일 키 존재 여부를 조회해요.
없으면 등록을 진행하고, 있으면 기존 계정 연결이나 로그인 흐름으로 보내요.

3로그인 토큰으로 SSO

login-token은 이미 가맹점이 알고 있는 고객을 Bootpay checkout 세션에 연결할 때 써요. 자체 로그인과 Bootpay customer를 이어 주는 얇은 다리라고 보면 돼요.

이 기능이 필요한 장면은 다음과 같아요.

가맹점 서비스에 로그인된 사용자가 checkout으로 넘어갈 때
checkout 화면에서 고객 정보를 다시 입력받고 싶지 않을 때
고객별 가격, 그룹 정책, 구독 상태를 바로 반영하고 싶을 때

SSO 관점에서 보면 흐름은 아래와 같아요.

가맹점 서버가 현재 로그인 사용자를 확인해요.
해당 사용자를 Bootpay customer와 매핑해요.
login-token을 발급해 checkout 요청에 연결해요.
checkout은 그 고객 컨텍스트를 기준으로 동작해요.

4다음 단계

고객 구조를 정했어요면 아래 순서로 문서를 읽으면 돼요.

중복 확인으로 가입 전 방어 로직을 넣어요.
고객 등록과 고객 수정로 고객 원장을 만들어요.
로그인 토큰으로 checkout 연결을 완성해요.
조직 단위 관리가 필요하면 B2B 마켓플레이스 이해하기로 넘어가요.

customer를 먼저 정리해 두면 checkout과 subscription에서 고객 식별을 다시 설계할 일이 줄어들어요.