결제 주기가 없는 수시결제 구독에서 재결제 키로 결제하고 키를 해지합니다. 고객에게 재결제 키를 한 번 받아 두고, 가맹점 서버가 필요할 때마다 그 키로 결제합니다. 수시결제는 다음 결제예정일을 만들지 않습니다.
먼저 수시결제 유형으로 계약이 있어야 합니다
재결제 키 확인
키가 발급됐는지는 주문 상세 응답의 auto_charge_key_issued 로 확인합니다. 키 평문(charge_key)은 서버 인증으로 주문을 조회할 때만 내려옵니다. SDK 응답·리다이렉트·웹훅에는 포함되지 않습니다.
결제 실행
키는 본문으로만 보냅니다
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 를 실패로 처리하면 중복 결제가 생깁니다.
키 해지
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
charge_key |
String | 필수 | 해지할 재결제 키 (본문) |
user_id |
String | 선택 | 로그인한 회원 ID 또는 이 몰의 외부 회원 ID. 보내면 키 소유자와 대조합니다. Bootpay-User-JWT 헤더로 보내도 됩니다 |
user |
Object | 선택 | 키 소유자 대조용 |
해지한 뒤 같은 키로 결제하면 CHARGE_KEY_REVOKED 로 거절됩니다.
에러 코드
공통 에러
인증·권한 관련 에러는 커머스 API 인증 에러를 참고합니다.
| 코드 | 메시지 | 대처 방법 |
|---|---|---|
CHARGE_ |
재결제 키를 찾을 수 없습니다 | 키 값과 프로젝트를 확인합니다 |
CHARGE_ |
재결제 키의 소유 회원 정보가 일치하지 않습니다 | user.user_id 를 확인합니다 |
CHARGE_ |
재결제 키 검증 실패가 누적되어 잠겼습니다 (HTTP 429) | 잠시 후 다시 시도합니다 |
CHARGE_ |
해지된 재결제 키입니다 | 고객에게 재등록을 요청합니다 |
CHARGE_ |
재결제 키에 연결된 결제 지갑이 삭제되었거나 만료되었습니다. | 결제수단 상태를 확인합니다 |
CHARGE_ |
구독이 해지되었거나 상품이 결제할 수 없는 상태입니다 | 계약이 구독 중인지, 상품이 판매 중인지 확인합니다 |
CHARGE_ |
결제 금액이 재결제 키의 1회 결제 상한을 초과했습니다 | 금액을 낮춥니다 |
SUBSCRIPTION_ |
결제가 진행 중입니다 (HTTP 202) | 실패로 처리하지 말고 웹훅으로 확정을 기다립니다 |



