참고
API 레퍼런스
모든 엔드포인트의 요청·응답 스키마(OpenAPI 3.1)와 문서 내려받기.
모든 엔드포인트의 요청·응답 스키마는 OpenAPI 3.1 스펙으로 제공합니다. 스펙은 코드에서 자동으로 만들어지므로 늘 실제 동작과 같습니다.
주소API 문서 https://api.billingplus.co.kr/api/v1/docs
OpenAPI 스펙 https://api.billingplus.co.kr/api/openapi.json
API 문서 화면의 [Try it out] 으로는 호출되지 않습니다. 모든 요청에 HMAC 서명이 필요한데 문서 화면은 서명을 만들지 못하기 때문입니다. 호출 시험은 빠른 시작의 예제로 하세요.
스펙의 Webhooks 절에는 빌링플러스가 보내는 이벤트별 요청 예시가 함께 들어 있습니다.
엔드포인트
경로는 서명에 그대로 쓰는 전체 경로입니다. {…} 는 숫자 ID(월별 금액은 YYYY-MM)로 바꿉니다.
연동 점검
| 메서드 | 경로 | 설명 |
|---|
| POST | /api/v1/ping | 연동 점검 (POST) |
| GET | /api/v1/ping | 연동 점검 |
회원
| 메서드 | 경로 | 설명 |
|---|
| GET | /api/v1/customers | 회원 목록 |
| POST | /api/v1/customers | 회원 등록 |
| GET | /api/v1/customers/{customer_id} | 회원 조회 |
| PATCH | /api/v1/customers/{customer_id} | 회원 수정 |
| POST | /api/v1/customers/{customer_id}/close | 회원 해지 |
결제수단(카드)
| 메서드 | 경로 | 설명 |
|---|
| GET | /api/v1/billing-keys | 결제수단 목록 |
| GET | /api/v1/billing-keys/{method_id} | 결제수단 조회 |
| DELETE | /api/v1/billing-keys/{method_id} | 결제수단 폐기 |
청구서
| 메서드 | 경로 | 설명 |
|---|
| GET | /api/v1/invoices | 청구서 목록 |
| POST | /api/v1/invoices | 청구서 발행 |
| GET | /api/v1/invoices/{invoice_id} | 청구서 조회 |
| POST | /api/v1/invoices/{invoice_id}/confirm | 청구 확정 |
| POST | /api/v1/invoices/{invoice_id}/void | 청구 무효화 |
결제
| 메서드 | 경로 | 설명 |
|---|
| GET | /api/v1/payments | 결제 목록 |
| POST | /api/v1/payments | 결제 승인 |
| GET | /api/v1/payments/{payment_id} | 결제 조회 |
| POST | /api/v1/payments/{payment_id}/cancel | 결제 취소 |
정기결제 계약
| 메서드 | 경로 | 설명 |
|---|
| GET | /api/v1/subscriptions | 계약 목록 |
| POST | /api/v1/subscriptions | 계약 등록 |
| GET | /api/v1/subscriptions/{subscription_id} | 계약 조회 |
| PATCH | /api/v1/subscriptions/{subscription_id} | 계약 수정 |
| POST | /api/v1/subscriptions/{subscription_id}/pause | 계약 일시정지 |
| POST | /api/v1/subscriptions/{subscription_id}/resume | 계약 재개 |
| POST | /api/v1/subscriptions/{subscription_id}/cancel | 계약 해지 |
월별 청구 금액(수동 정기결제)
| 메서드 | 경로 | 설명 |
|---|
| GET | /api/v1/subscriptions/{subscription_id}/charges | 월별 청구 금액 목록 |
| POST | /api/v1/subscriptions/{subscription_id}/charges | 월별 청구 금액 넣기·고치기 |
| POST | /api/v1/subscriptions/{subscription_id}/charges/{billing_month}/cancel | 월별 청구 금액 거두기 |
| POST | /api/v1/subscriptions/{subscription_id}/charges/{billing_month}/skip | 이 회차 청구하지 않기 |
등록창
| 메서드 | 경로 | 설명 |
|---|
| POST | /api/v1/register-windows | 등록창 생성 |
| GET | /api/v1/register-windows | 등록창 목록 |
| GET | /api/v1/register-windows/{window_id} | 등록창 조회 |
| POST | /api/v1/register-windows/{window_id}/close | 등록창 닫기 |
수시결제 동의
| 메서드 | 경로 | 설명 |
|---|
| GET | /api/v1/charge-consents | 수시결제 동의 목록 |
| GET | /api/v1/charge-consents/{consent_id} | 수시결제 동의 조회 |
| POST | /api/v1/charge-consents/{consent_id}/charges | 수시결제 요청 |
| POST | /api/v1/charge-consents/{consent_id}/revoke | 수시결제 동의 해지 |
공통 규칙
- 모든 요청에 인증 헤더와 서명이 필요합니다 — 인증 · 요청 서명
- 모든 POST 에
Idempotency-Key 가 필요합니다 — 멱등키
- 회원 수정(
PATCH /api/v1/customers/{id})은 보낸 항목만 바꿉니다. 보내지 않은 항목은 그대로 두고, null 을 보내면 비웁니다.
- 계약 수정(
PATCH /api/v1/subscriptions/{id})도 보낸 항목만 바꿉니다. 등록 때 필수였던 항목도 수정에서는 보내지 않아도 됩니다. null 을 보내면 비웁니다(term_months → 무기한, payment_method_id → 결제수단 없음). 청구일·주기·시작일을 바꾸면 다음 청구일을 다시 계산합니다.
- 다른 가맹점의 자원이나 없는 ID 는
404 입니다.
- 결제 승인·수시결제 요청의 거절은
200 + status: FAILED 입니다 — 에러 응답
- 카드번호를 받는 엔드포인트는 없습니다. 결제수단(
billing-keys)은 조회와 폐기만 할 수 있고, 등록은 등록창·가입 링크로 합니다.
- 결제 취소는 남은 금액 전체만 합니다. 부분취소는 하지 않습니다(
amount 를 보내면 남은 금액과 같아야 하고, 다르면 422).
개발자센터