수시결제 | Bootpay 커머스 매뉴얼

결제 주기가 없는 구독이에요. 고객에게 재결제 키를 한 번 받아 두고, 가맹점 서버가 필요할 때마다 그 키로 결제해요.

정기구독이 스케줄러가 회차를 만들어 청구한다면, 수시결제는 다음 결제예정일을 만들지 않아요. 쓴 만큼 그때그때 청구하거나 충전형 잔액을 다루는 서비스에 맞아요.

구독 템플릿의 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 을 돌려줘요.

결제가 즉시 확정되지 않으면 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)	실패로 처리하지 말고 웹훅으로 확정을 기다려요

함께 보기

유형 선택 가이드 — 수시결제가 내 서비스에 맞는지
구독 템플릿 — expose_auto_charge_consent 로 동의 화면을 켜요
회차 청구 내역 — 수시결제도 청구 기록이 남아요