Bootpay 커머스 매뉴얼

참고

입점사 지급 요청

가맹점 지정 금액(manual) 정산 방식의 쇼핑몰이 입점사와 지급액을 정해 지급을 요청하는 서버 API 입니다. 요청은 지급 원장에 등록되며 실제 송금은 별도 배치가 약 5분 간격으로 처리합니다.

  • 모두 판매자 서버 전용이며 supervisor 역할의 scope 가 필요합니다.
  • 응답의 status 는 숫자가 아닌 문자열입니다.
  • 응답에는 지급 조회·대사에 필요한 필드만 포함되며 내부 처리 이력은 포함되지 않습니다.

지급 상태

값 설명
ready 송금 대기
held 입점사 지급 중지 등으로 보류
sending 배치가 송금 요청을 준비 중
requested 지급사에 송금 요청 완료
processing 지급사 처리 중
succeeded 지급 성공
failed 지급 실패
cancelled 지급 취소
unknown 지급 결과 확인 필요
void 지급 대상에서 제외

POST /v1/sdk/payouts

입점사와 지급액을 지정해 지급 원장에 등록합니다. 쇼핑몰 정산 방식이 manual 일 때만 사용할 수 있습니다.

같은 프로젝트에서 같은 merchant_payout_id 로 유효한 요청을 다시 보내면 새 항목을 만들지 않고 처음 만든 항목을 그대로 돌려줍니다. 이 값은 앞뒤 공백을 제거한 뒤 비교합니다. 이미 등록한 항목의 금액·입점사·지급일을 재요청으로 바꿀 수 없습니다.

인증

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

요청

위치 이름 타입 필수 기본값 설명
body sub_seller_id string O 이 프로젝트에 속한 입점사 ID
body amount integer O 지급액. 1원 이상 정수
body merchant_payout_id string O 가맹점 지급 번호이자 프로젝트별 멱등 키. 앞뒤 공백을 제외하고 1~100자
body order_number string 가맹점 주문 번호
body payout_date string 오늘 지급 예정일(YYYY-MM-DD). 한국 시간 기준 오늘 이후

응답

200 OK — 생성됐거나 같은 merchant_payout_id 로 먼저 생성된 지급 항목

{
  "id": "6719a0c2a1b2c3d4e5f60001",
  "merchant_payout_id": "merchant-payout-20261023-001",
  "sub_seller_id": "6719a0c2a1b2c3d4e5f60002",
  "amount": 150000,
  "status": "ready",
  "payout_date": "2026-10-24",
  "order_number": "ORDER-20261023-001",
  "last_code": null,
  "last_message": null,
  "created_at": "2026-10-23T10:20:30+09:00",
  "updated_at": "2026-10-23T10:20:30+09:00"
}json
필드 타입 설명
id string 지급 항목 ID
merchant_payout_id string 가맹점 지급 번호
sub_seller_id string 입점사 ID
amount integer 지급액(원)
status string 지급 상태
payout_date string 지급 예정일(YYYY-MM-DD)
order_number string 가맹점 주문 번호. 없으면 null
last_code string 마지막 지급 결과 코드. 아직 결과가 없으면 null
last_message string 마지막 지급 결과 메시지. 부트페이가 남긴 결과는 last_code 숫자 코드의 안내 문구다(예: 18381 지급됐는지 확인하지 못함). 아직 결과가 없으면 null
created_at string 생성 시각
updated_at string 마지막 변경 시각

오류

HTTP error_code 언제
400 PAYOUT_SETTING_INVALID (18360) 지급 설정이 없거나, 지급 기능이 꺼져 있거나, 정산 방식이 manual 이 아님
400 PAYOUT_SELLER_NOT_FOUND (18364) sub_seller_id 가 없거나 이 프로젝트의 입점사가 아님
400 PAYOUT_MERCHANT_ID_REQUIRED (18369) merchant_payout_id 가 비었거나 앞뒤 공백 제거 후 100자를 넘음
400 PAYOUT_AMOUNT_INVALID (18370) amount 가 1원 이상 정수가 아니거나 payout_date 가 날짜 형식이 아니거나 오늘보다 이전임
400 PAYOUT_SELLER_NOT_REGISTERED (18378) 입점사의 PG 판매자 등록이 끝나지 않음
400 PAYOUT_NOT_READY (18374) 지급대행 준비(원장 인덱스)가 끝나지 않아 요청을 받지 않음 — 잠시 뒤 다시 시도하거나 부트페이에 문의

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

변경 이력

  • 2026-10-23 최초 작성
  • 2026-11-04 PG 미등록 입점사 거절(18378) · 준비 전 거절(18374) · last_message 를 숫자 코드 안내 문구로

GET /v1/sdk/payouts/:id

지급 항목 한 건을 조회합니다. 현재 프로젝트의 항목만 조회할 수 있으며, 다른 프로젝트의 값은 노출하지 않습니다.

인증

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

요청

위치 이름 타입 필수 기본값 설명
path id string O merchant_payout_id 또는 지급 항목 id

응답

200 OK — 항목 형식은 지급 요청 응답과 같습니다.

오류

HTTP error_code 언제
404 PAYOUT_RESULT_INVALID (18366) 현재 프로젝트에서 id 또는 merchant_payout_id 가 일치하는 지급 항목을 찾지 못함

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

변경 이력

  • 2026-10-23 최초 작성

GET /v1/sdk/payouts

현재 프로젝트의 지급 항목을 최근 생성 순으로 조회합니다.

인증

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

요청

위치 이름 타입 필수 기본값 설명
query status string 지급 상태로 필터. 위 지급 상태 값 중 하나
query sub_seller_id string 입점사 ID로 필터
query from string 지급 예정일 시작(YYYY-MM-DD, 포함)
query to string 지급 예정일 끝(YYYY-MM-DD, 포함)
query page integer 1 페이지 번호. 정수로 변환한 값이 1 미만이면 1
query limit integer 20 페이지 크기. 정수로 변환한 값이 1 미만이면 1, 100을 넘으면 100

응답

200 OK

[
  {
    "id": "6719a0c2a1b2c3d4e5f60001",
    "merchant_payout_id": "merchant-payout-20261023-001",
    "sub_seller_id": "6719a0c2a1b2c3d4e5f60002",
    "amount": 150000,
    "status": "ready",
    "payout_date": "2026-10-24",
    "order_number": "ORDER-20261023-001",
    "last_code": null,
    "last_message": null,
    "created_at": "2026-10-23T10:20:30+09:00",
    "updated_at": "2026-10-23T10:20:30+09:00"
  }
]json

응답은 이번 페이지의 지급 항목 배열입니다. 각 항목은 지급 요청 응답과 같은 필드로 구성됩니다. 전체 개수는 오지 않으므로 받은 항목 수가 limit 보다 적으면 마지막 페이지로 판단하세요.

오류

HTTP error_code 언제
400 API_PARAM_INVALID (-48) status 가 지급 상태 값이 아니거나 from·to 가 유효한 YYYY-MM-DD 날짜가 아니거나 시작일이 끝일보다 늦음

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

변경 이력

  • 2026-10-23 최초 작성

함께 보기