마켓플레이스 API 는 리셀러(Reseller) 권한을 가진 한 계정이 코드만으로 하위 가맹점과 프로젝트를 생성·조회·관리할 수 있게 해준다. PG 계약·정산 구조는 그대로 두고, 가입 흐름과 운영 콘솔만 가맹점 서비스에 내재화하는 용도다.
플랫폼 사업자, 솔루션 SI, ERP, 호스팅, SaaS 같은 사업자가 자체 회원가입 흐름 안에서 부트페이 가맹점을 생성하고 곧바로 결제 연동까지 끝낼 수 있다.
핵심 요약
- 리셀러 계정 1개로 N 개의 하위 가맹점(seller)을 만든다. 가맹점마다 다시 N 개의 프로젝트(app)를 둘 수 있다.
- 인증은 평소 사용하는 Basic Auth 그대로다. 리셀러 계정의
client_key/secret_key를 쓴다. - 모든 엔드포인트는
provider.lv = 2 (리셀러)권한 검사를 통과해야 한다. 일반 가맹점 계정으로는 호출되지 않는다. - 하위 가맹점에서 중복을 식별할 키로
primary_key를 가맹점 측 회원 ID 와 1:1 로 묶어둔다. 중복이면PROVIDER_PK_EXIST가 떨어진다.
누가 쓰는가
이런 자리에서 자주 쓴다.
- 호스팅·쇼핑몰 빌더 — 입점 셀러가 가입하면 셀러 단위 가맹점을 자동 생성하고 결제수단까지 함께 붙인다.
- SaaS·예약 서비스 본사 — 지점·매장 단위로 별도 가맹점을 만들어 정산을 분리한다.
- B2B 솔루션 / SI — 고객사가 결제를 붙일 때 본사 콘솔에 들어와 셀러 키를 받아갈 필요 없이 자체 흐름 안에서 발급한다.
본사가 하위 가맹점의 PG 계약·정산 주체가 되는 게 아니라, 부트페이가 각 가맹점에게 PG 계약과 정산을 그대로 묶어준다. 본사는 발급·운영을 자동화할 뿐이다.
권한 모델
| 단계 | 객체 | 식별자 | 비고 |
|---|---|---|---|
| 1 | 리셀러(provider) | client_key / secret_key |
lv = 2. 하위를 만든다 |
| 2 | 셀러(provider) | provider_id, primary_key |
lv = 1. 본사 회원 ID 와 묶는다 |
| 3 | 프로젝트(app) | app_id, application_keys[] |
셀러당 N 개. 결제수단은 여기에 붙는다 |
primary_key 는 리셀러 입장에서 셀러를 식별하는 외부 키다. 본사 DB 의 회원 ID 를 넣으면 가장 자연스럽다. 동일 리셀러 안에서 유일해야 한다.
흐름 한눈에
가장 흔한 시나리오는 "본사에서 회원가입 → 셀러 + 첫 프로젝트 + PG 리소스까지 한 번에 생성" 이다.
추가 프로젝트나 PG 리소스 갱신은 셀러가 운영 중에도 본사 콘솔에서 다시 호출하면 된다. 셀러가 부트페이 콘솔에 들어오지 않아도 본사 흐름 안에서 끝난다.
엔드포인트 인덱스
| 메서드 | 경로 | 용도 | 문서 |
|---|---|---|---|
| POST | /v2/reseller/seller |
하위 가맹점 생성 (셀러 + 기본 프로젝트 + 첫 결제수단) | 가맹점 생성 |
| GET | /v2/reseller/seller/:provider_id |
하위 가맹점 단건 조회 | 가맹점 조회 |
| POST | /v2/reseller/seller/app |
셀러에 프로젝트 추가 | 프로젝트 생성 |
| PATCH | /v2/reseller/seller/app/resource/:app_id |
프로젝트 PG·결제수단 리소스 갱신 | PG 리소스 갱신 |
| POST | /v2/reseller/invite |
팀(provider) 또는 프로젝트(app) 에 멤버 초대 | 팀·프로젝트 초대 |
| DELETE | /v2/reseller/test/seller/:provider_id |
테스트용 가맹점·프로젝트·롤 일괄 삭제 | 테스트 데이터 삭제 |
인증
리셀러 계정의 백엔드 연동키로 Basic Auth 헤더를 그대로 만든다.
Authorization: Basic base64(reseller_client_key:reseller_secret_key)리셀러 본인의 client_key 와 하위 셀러 프로젝트가 받게 되는 application_keys 는 다른 값이다. 마켓플레이스 API 는 항상 리셀러 본인 키로 호출한다. 하위 셀러 결제는 셀러 측 키로 별도 호출한다.
자주 묻는 점
Q. 셀러가 가입한 직후 바로 결제까지 가능한가?
가능하다. POST /v2/reseller/seller 요청에 resources 배열을 같이 넣으면 첫 프로젝트에 결제수단까지 한 번에 등록된다. 응답으로 받은 application_keys 로 결제창을 띄울 수 있다.
Q. 리소스(PG·결제수단) 를 나중에 늘리려면?
PG 리소스 갱신 으로 app_id 와 갱신할 리소스 배열을 보내면 된다. 기존 결제수단은 유지되고 변경분만 반영된다.
Q. 이미 부트페이에 직접 가입된 가맹점을 내 리셀러로 옮길 수 있나? 이 API 만으로는 불가능하다. 이관은 별도 합의가 필요해서 부트페이 영업팀에 문의하면 된다.
Q. 테스트 데이터는 어떻게 정리하나? 통합 테스트나 CI 에서 만들어둔 셀러는 테스트 데이터 삭제 로 일괄 정리할 수 있다. 운영 데이터에는 절대 호출하지 않는다.