수시결제 동의 API: 한도 안에서 필요할 때 결제
회원이 동의한 1회·월 한도 안에서 가맹점 시스템이 필요할 때 결제를 요청하는 수시결제 동의 API를 설명합니다.
정기결제는 금액과 날짜가 정해져 있지만, 서비스에 따라 "필요할 때 등록된 카드로 결제"해야 하는 경우가 있습니다. 사용량 추가 요금이나 부가 서비스 결제가 그렇습니다. 빌링플러스에서는 이를 수시결제 동의로 처리합니다. 회원이 1회·월 한도에 동의하면, 가맹점 시스템은 그 한도 안에서 결제를 요청합니다.
정기결제 계약과의 차이
| 항목 | 정기결제 계약 | 수시결제 동의 |
|---|---|---|
| 금액·시점 | 계약 금액, 청구일 | 그때그때, 가맹점이 요청할 때 |
| 실행 | 빌링플러스 배치 | 가맹점 화면 또는 API |
| 실패하면 | 재청구·미납관리 | 즉시 거절 응답, 청구서는 무효 |
| 상한 | 계약 금액 | 회원이 동의한 1회·월 한도 |
동의는 회원이 직접 만듭니다
동의를 만드는 API는 없습니다. 등록창을 열 때 수시결제 방식과 1회·월 한도를 보내면 회원이 등록창에서 한도를 확인하고 카드를 등록하며 동의합니다. 등록 링크나 가입 링크, 담당자 대행 등록으로도 만들 수 있습니다. 같은 카드와 같은 품목명의 동의는 하나만 둘 수 있습니다.
결제 요청
- 동의 조회로 이번 달 사용액과 남은 한도, 지금 한 번에 요청할 수 있는 최대 금액을 확인합니다.
POST /v1/charge-consents/{id}/charges에 금액(필요하면 품목명·메모)을 보냅니다. Idempotency-Key가 필요합니다.- 청구서 발행부터 승인까지 한 번에 처리돼 응답에 청구서와 결제 결과가 실립니다.
응답 처리
- 카드 거절: 정상 응답에 결제 상태 실패가 실리고, 청구서는 무효가 되어 미수로 남지 않습니다.
- 1회·월 한도 초과, 해지된 동의, 카드 사용 불가: 결제사에 묻지 않고 422로 거절하며
detail.reason에 이유가 실립니다. - 같은 동의로 처리 중: 409와 Retry-After가 옵니다.
월 한도는 결과를 기다리는 결제까지 포함해 셉니다. 결과가 나오기 전에 한도가 풀리면 동의한 금액보다 많이 걷힐 수 있기 때문입니다.
웹훅
동의가 만들어지거나 해지되면 이벤트가 나가고, 동의로 일어난 결제·청구서 웹훅에는 동의 번호가 실립니다. 해지는 사유와 함께 남고 되살리지 않습니다. 한도를 바꾸려면 해지한 뒤 다시 동의받습니다.
구현 팁
결제 요청 전에 남은 한도를 확인해 화면에 보여 주면 422가 나기 전에 사용자에게 알릴 수 있습니다. 결제 요청의 멱등키는 가맹점 쪽 주문이나 사용 기록 단위로 만들어, 재시도해도 결제가 한 건만 생기게 하세요.
동의 결제도 일반 결제와 같은 승인 경로를 지나므로 결제 내역·카드 영수증·취소가 똑같이 동작합니다.
다음 단계
필드와 오류 코드는 수시결제 동의 문서에, 창 열기는 등록창 문서에 있습니다.