수시결제

v1 API 상세 명세

결제 주기가 없는 수시결제 구독에서 재결제 키로 결제하고 키를 해지합니다. 고객에게 재결제 키를 한 번 받아 두고, 가맹점 서버가 필요할 때마다 그 키로 결제합니다. 수시결제는 다음 결제예정일을 만들지 않습니다.

먼저 수시결제 유형으로 계약이 있어야 합니다

구독 템플릿의 type 이 on_demand_subscription(7)이어야 하고, 고객이 신청해 계약이 활성 상태여야 합니다. 유형 선택 가이드와 구독 템플릿을 참고합니다.

재결제 키 확인

키가 발급됐는지는 주문 상세 응답의 auto_charge_key_issued 로 확인합니다. 키 평문(charge_key)은 서버 인증으로 주문을 조회할 때만 내려옵니다. SDK 응답·리다이렉트·웹훅에는 포함되지 않습니다.

결제 실행

POSThttps://api.bootapi.com/v1/order_subscriptions/chargeBasic Auth (supervisor 권한 필요)
키는 본문으로만 보냅니다

charge_key 를 질의 문자열이나 경로에 넣지 않습니다. 접근 로그에 평문이 남습니다.

파라미터 타입 필수 설명
charge_key String 필수 재결제 키
price Number 선택 결제 금액(원 단위 정수, 소수는 버립니다). 생략하면 구독 계약 금액​​으로 결제합니다
tax_free_price Number 선택 비과세 금액
user_id String 선택 로그인한 회원 ID 또는 이 몰의 외부 회원 ID. 보내면 키 소유자와 대조합니다. Bootpay-User-JWT 헤더로 보내도 됩니다
user Object 선택 키 소유자 대조용. user.user_id 에 회원 ID·로그인 ID·이메일 중 하나를 넣으면 일치 여부를 확인합니다
metadata Object 선택 가맹점 커스텀 데이터. 트랜잭션에 저장됩니다
curl -X POST "https://api.bootapi.com/v1/order_subscriptions/charge" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Bootpay-Role: supervisor" \
  -H "Content-Type: application/json" \
  -d '{ "charge_key": "{charge_key}", "price": 4900, "metadata": { "usage_month": "2026-09" } }'bash

결제가 끝나면 bill_id·transaction_id·order_id·order_number·receipt_id·price·purchased_at 을 돌려줍니다.

PG 가 늦으면 202 로 응답합니다

결제가 즉시 확정되지 않으면 202 와 함께 SUBSCRIPTION_TRANSACTION_PENDING 이 돌아옵니다. 이때 payload.bill_id 로 추적하고, 최종 확정은 웹훅으로 받습니다. 202 를 실패로 처리하면 중복 결제가 생깁니다.

키 해지

DELETEhttps://api.bootapi.com/v1/order_subscriptions/chargeBasic Auth (supervisor 권한 필요)
파라미터 타입 필수 설명
charge_key String 필수 해지할 재결제 키 (본문)
user_id String 선택 로그인한 회원 ID 또는 이 몰의 외부 회원 ID. 보내면 키 소유자와 대조합니다. Bootpay-User-JWT 헤더로 보내도 됩니다
user Object 선택 키 소유자 대조용

해지한 뒤 같은 키로 결제하면 CHARGE_KEY_REVOKED 로 거절됩니다.

에러 코드

공통 에러

인증·권한 관련 에러는 커머스 API 인증 에러를 참고합니다.

코드 메시지 대처 방법
CHARGE_KEY_NOT_FOUND 재결제 키를 찾을 수 없습니다 키 값과 프로젝트를 확인합니다
CHARGE_KEY_USER_MISMATCH 재결제 키의 소유 회원 정보가 일치하지 않습니다 user.user_id 를 확인합니다
CHARGE_KEY_RATE_LIMITED 재결제 키 검증 실패가 누적되어 잠겼습니다 (HTTP 429) 잠시 후 다시 시도합니다
CHARGE_KEY_REVOKED 해지된 재결제 키입니다 고객에게 재등록을 요청합니다
CHARGE_KEY_WALLET_INVALID 재결제 키에 연결된 결제 지갑이 삭제되었거나 만료되었습니다. 결제수단 상태를 확인합니다
CHARGE_KEY_SUBSCRIPTION_INVALID 구독이 해지되었거나 상품이 결제할 수 없는 상태입니다 계약이 구독 중인지, 상품이 판매 중인지 확인합니다
CHARGE_KEY_PRICE_OVER_LIMIT 결제 금액이 재결제 키의 1회 결제 상한을 초과했습니다 금액을 낮춥니다
SUBSCRIPTION_TRANSACTION_PENDING 결제가 진행 중입니다 (HTTP 202) 실패로 처리하지 말고 웹훅으로 확정을 기다립니다

함께 보기