등록 API 접수

리셀러가 자기 화면에서 판매자의 사업자 정보·서류·약관 동의를 받아, 리셀러 서버가 하위 가맹점의 PG 가맹 신청서를 직접 낸다. 부트페이 신청 화면을 띄우지 않는 길이다. 부트페이 화면으로 받고 싶다면 등록 폼 세션 발급 을 쓴다.

핵심 요약

• 순서는 약관 조회 → (서류가 있으면) 업로드 허가 받기 → storage 에 서류 올리기 → 신청서 접수 다. 진행 상태는 등록 상태 조회 로 읽는다.
• 신청서와 약관 동의 기록은 한 번에 저장​​된다. 동의가 빠지거나 버전이 다르면 신청서도 남지 않는다.
• 약관 동의는 리셀러 화면에서 받으므로, 약관마다 동의 시각·동의한 사람의 IP·동의자​​를 함께 보낸다. 이 값이 그대로 동의 기록이 된다.
• 접수 응답은 등록 상태 조회의 한 항목과 같은 모양이다(channel 은 api).
• 지금 낼 수 있는 신청은 PG 가맹 신청(pg_join) 하나다. A형(대표가맹점) 리셀러는 아직 쓸 수 없다.

전체 흐름

1약관 조회

판매자에게 보여 줄 약관의 현재 버전과 원문을 읽는다. 접수 때 agreements[] 에는 여기서 받은 code·version 을 그대로 넣는다. 약관이 바뀌면 이전 버전으로 낸 접수는 거부된다.

[
  {
    "code":         "pg_terms",
    "version":      2,
    "title":        "PG 서비스 이용약관",
    "body":         "(약관 원문)",
    "effective_at": "2026-10-01T00:00:00+09:00",
    "hash":         "sha256:example_hash",
    "required":     true
  }
]json

2서류 업로드 허가

사업자등록증을 올릴 수 있는 10분짜리 허가를 받는다. 파일은 부트페이 API 서버를 거치지 않고 리셀러 서버가 upload_url 로 직접 올린다.

{
  "grant":      "eyJ2IjoxLCJwX2lkIjoi...example.0f1e2d3c...",
  "upload_url": "https://s.bootapi.com/api/v1/secure_documents",
  "expires_at": "2026-10-27T15:10:00+09:00"
}json

받은 grant 를 X-Upload-Grant 헤더에 넣고, upload_url 로 multipart 업로드한다. 파일은 PDF·JPG·PNG, 10MB 이하다.

storage 응답의 file_id 를 접수의 file_ids[] 에 넣는다. 접수할 때 부트페이가 그 파일이 이 하위 가맹점이 올린 사업자등록증인지 확인하고, 파일 이름·형식·크기는 저장된 값으로 신청서에 남긴다. 다른 가맹점이 올린 파일 id 는 받지 않는다. 나머지 값(file_name·ext·mime_type·size)은 business_license 로 함께 보내도 되지만 저장된 값이 우선한다.

{
  "file_id":   "6718a0aa8f1b5b00367a0201",
  "file_name": "사업자등록증.pdf",
  "ext":       "pdf",
  "mime_type": "application/pdf",
  "size":      182044
}json

허가 하나로 여러 번 올릴 수 있지만 10분이 지나면 다시 받는다. 하위 가맹점의 커머스 연동이 아직 없으면 storage 가 STORAGE_SECURE_DOC_GRANT_OWNER_NOT_FOUND(3037)로 거부한다 — 커머스 연동 재시도 뒤 다시 올린다.

3신청서 접수

라이트페이(lightpay)는 희망 MID(expect_mid, 영문·숫자 10자 이내)와 정산 계좌(bank_code·account_number·account_owner)가 필수이고, 법인이면 대표자 생년월일(owner_birth_date, YYYYMMDD)·자본금(corp_capital)도 필수다. 글자 칸에는 문자열이나 숫자만 보낸다.

동의 항목 (agreements[] 한 개)

코드 예제

import fetch from 'node-fetch'
import fs from 'node:fs'

const RESELLER_AUTH = 'Basic ' + Buffer
  .from(`${process.env.BOOTPAY_RESELLER_CLIENT_KEY}:${process.env.BOOTPAY_RESELLER_SECRET_KEY}`)
  .toString('base64')
const API = 'https://api.bootpay.co.kr/v2/reseller'
const providerId = '65a1c0aa8f1b5b00367a0001'

// 1. 지금 동의받을 약관
const terms = await (await fetch(`${API}/agreements`, { headers: { Authorization: RESELLER_AUTH } })).json()

// 2·3. 업로드 허가 → storage 에 직접 올리기
const grant = await (await fetch(`${API}/seller/${providerId}/files/grant`, {
    method: 'POST',
    headers: { Authorization: RESELLER_AUTH, 'Content-Type': 'application/json' },
    body: JSON.stringify({ kind: 'business_license' })
})).json()
const form = new FormData()
form.append('doc_type', 'business_license')
form.append('file', new Blob([fs.readFileSync('./license.pdf')], { type: 'application/pdf' }), 'license.pdf')
const file = await (await fetch(grant.upload_url, {
    method: 'POST',
    headers: { 'X-Upload-Grant': grant.grant },
    body: form
})).json()

// 4. 접수 — 판매자가 리셀러 화면에서 동의한 시각·IP 를 그대로 보낸다
const consent = { agreed_at: '2026-10-27T10:15:00+09:00', ip: '198.51.100.7', signer: { name: '김대표', phone: '01011112222' } }
const submitKey = crypto.randomUUID() // 이 접수를 다시 보낼 때도 같은 값을 쓴다
const res = await fetch(`${API}/seller/${providerId}/onboarding`, {
    method: 'POST',
    headers: { Authorization: RESELLER_AUTH, 'Content-Type': 'application/json', 'Idempotency-Key': submitKey },
    body: JSON.stringify({
        pg_alias: 'nicepay',
        company_name: '예시상점', seller_type: 4, regist_no: '1234567890', corp_reg_no: '1101111234567',
        owner_name: '김대표', business_type: '서비스', business_item: '소프트웨어',
        biz_email: 'biz@example.com', biz_tel: '0212345678', site_url: 'https://shop.example.com',
        name: '이담당', email: 'manager@example.com', phone: '01033334444',
        file_ids: [file.file_id],
        business_license: { file_name: file.file_name, ext: file.ext, mime_type: file.mime_type, size: file.size },
        agreements: terms.map((t) => ({ code: t.code, version: t.version, ...consent }))
    })
})
const onboarding = await res.json() // { pg_wait_id, status, stage, due_at, ... }javascript

import base64, os, requests

auth = 'Basic ' + base64.b64encode(
    f"{os.environ['BOOTPAY_RESELLER_CLIENT_KEY']}:{os.environ['BOOTPAY_RESELLER_SECRET_KEY']}".encode()
).decode()
api = 'https://api.bootpay.co.kr/v2/reseller'
provider_id = '65a1c0aa8f1b5b00367a0001'

terms = requests.get(f'{api}/agreements', headers={'Authorization': auth}).json()
grant = requests.post(f'{api}/seller/{provider_id}/files/grant', headers={'Authorization': auth},
                      json={'kind': 'business_license'}).json()
with open('license.pdf', 'rb') as f:
    file = requests.post(grant['upload_url'], headers={'X-Upload-Grant': grant['grant']},
                         data={'doc_type': 'business_license'},
                         files={'file': ('license.pdf', f, 'application/pdf')}).json()

consent = {'agreed_at': '2026-10-27T10:15:00+09:00', 'ip': '198.51.100.7'}
res = requests.post(f'{api}/seller/{provider_id}/onboarding', headers={'Authorization': auth}, json={
    'pg_alias': 'nicepay',
    'company_name': '예시상점', 'seller_type': 4, 'regist_no': '1234567890', 'corp_reg_no': '1101111234567',
    'owner_name': '김대표', 'business_type': '서비스', 'business_item': '소프트웨어',
    'biz_email': 'biz@example.com', 'biz_tel': '0212345678', 'site_url': 'https://shop.example.com',
    'name': '이담당', 'email': 'manager@example.com', 'phone': '01033334444',
    'file_ids': [file['file_id']],
    'agreements': [{'code': t['code'], 'version': t['version'], **consent} for t in terms]
})
onboarding = res.json()python

RESELLER_AUTH=$(printf '%s' "$BOOTPAY_RESELLER_CLIENT_KEY:$BOOTPAY_RESELLER_SECRET_KEY" | base64)
PROVIDER_ID='65a1c0aa8f1b5b00367a0001'

# 2. 업로드 허가
curl -X POST "https://api.bootpay.co.kr/v2/reseller/seller/$PROVIDER_ID/files/grant" \
  -H "Authorization: Basic $RESELLER_AUTH" -H 'Content-Type: application/json' \
  -d '{"kind":"business_license"}'

# 3. storage 에 올리기 — 위 응답의 grant·upload_url
curl -X POST "$UPLOAD_URL" -H "X-Upload-Grant: $UPLOAD_GRANT" \
  -F doc_type=business_license -F file=@license.pdf

# 4. 접수
curl -X POST "https://api.bootpay.co.kr/v2/reseller/seller/$PROVIDER_ID/onboarding" \
  -H "Authorization: Basic $RESELLER_AUTH" -H 'Content-Type: application/json' \
  -d @onboarding.jsonbash

응답

접수·보완 응답은 등록 상태 조회 목록의 한 항목과 같다.

{
  "provider_id":        "65a1c0aa8f1b5b00367a0001",
  "onboarding_id":      "6718a0aa8f1b5b00367a0101",
  "kind":               "pg_join",
  "status":             0,
  "status_name":        "미확인",
  "stage":              "intake",
  "stage_owner":        "ours",
  "due_at":             "2026-10-28T10:20:00+09:00",
  "reject_reason":      null,
  "pg_wait_id":         "6718a0aa8f1b5b00367a0101",
  "pg":                 "nicepay",
  "overdue":            false,
  "required_documents": [],
  "channel":            "api",
  "c_at":               "2026-10-27T10:20:00+09:00",
  "u_at":               "2026-10-27T10:20:00+09:00"
}json

4보완·재제출

서류 보완 요청을 받았거나 내용을 고칠 때 같은 신청서를 다시 낸다. 판매자가 부트페이 콘솔이나 등록 폼으로 낸 그 가맹점의 신청서도 고칠 수 있다.

신청이 끝난(status 6) 신청서는 고칠 수 없다. 새로 신청하려면 3. 신청서 접수로 다시 낸다. 응답은 접수와 같다.

에러 코드