연동 가이드

매달 금액이 다른 정기결제

수동 정기결제 계약에 회차별 금액을 넣고 고치고 건너뛰는 API.

정기결제 계약은 금액 방식이 둘입니다. 둘 다 결제일에 빌링플러스가 자동으로 결제합니다.

`amount_mode`	걷는 금액	어울리는 경우
`FIXED` 자동	계약 금액(매 회차 같음)	월 회비·구독료
`VARIABLE` 수동	회차마다 넣은 금액. 계약 금액은 참고용 기준 금액입니다	사용량·검침·수업 횟수처럼 달마다 금액이 다른 경우

계약을 만들 때(POST /api/v1/subscriptions) amount_mode 를 VARIABLE 로 보내면 수동 계약이 됩니다. 비우면 자동입니다. 수정(PATCH)에서 보내지 않으면 지금 값이 유지됩니다.

금액을 넣지 않은 회차는 결제하지 않고 기다립니다. 기준 금액으로 대신 걷지 않고, 다음 회차로 넘어가지도 않습니다. 금액을 넣으면 그 결제일(지났으면 다음 자동결제 시각)에 결제됩니다. 이 API 는 금액만 정하고, 결제는 빌링플러스가 합니다.

회차 목록 — GET /api/v1/subscriptions/{id}/charges

앞으로 걷을 회차(최대 12회차, 약정 종료 뒤는 없음)와 최근 지난 회차(최대 6개)를 함께 돌려줍니다. 페이지네이션은 없습니다.

응답 200

{
  "subscription_id": 210,
  "contract_no": "C-2026-0057",
  "amount_mode": "VARIABLE",
  "current_month": "2026-11",
  "data": [
    {"billing_month": "2026-10", "regular_date": "2026-10-05", "status": "INVOICED", "amount": 41200,
     "charge_date": "2026-10-05", "item_name": "10월 이용료", "invoice_id": 5502, "updated_at": "2026-09-28T11:00:00+09:00"},
    {"billing_month": "2026-11", "regular_date": "2026-11-05", "status": "PENDING", "amount": 38900,
     "charge_date": "2026-11-05", "item_name": "11월 이용료", "invoice_id": null, "updated_at": "2026-10-28T09:12:00+09:00"},
    {"billing_month": "2026-12", "regular_date": "2026-12-05", "status": "NONE", "amount": null,
     "charge_date": null, "item_name": "월 이용료", "invoice_id": null, "updated_at": null}
  ]
}

값	뜻
`current_month`	지금 걷을 회차의 달. 이 달 금액이 없으면 결제일이 지나도 결제하지 않습니다. 자동 계약이면 `null`
`billing_month`	청구월(무엇에 대한 돈인지). 결제일을 옮겨도 바뀌지 않습니다
`regular_date`	그 달의 계약 청구일(참고)
`status` `NONE`	금액 미입력 — 결제하지 않고 기다립니다
`status` `PENDING`	결제 대기 — 결제일에 결제합니다. 이 상태일 때만 고치거나 거둘 수 있습니다
`status` `INVOICED`	청구됨 — 청구서(`invoice_id`)가 만들어졌습니다. 고칠 수 없습니다
`status` `SKIPPED`	건너뜀 — 그 회차는 청구 없이 넘깁니다

금액 넣기·고치기 — POST /api/v1/subscriptions/{id}/charges

청구월마다 금액은 하나입니다. 같은 청구월로 다시 보내면 고칩니다(결제 대기일 때만). 응답은 위 회차 목록 전체입니다.

필드	필수	설명
`billing_month`	필수	청구월 `"2026-11"`. 이 계약의 앞으로 걷을 회차여야 합니다(최대 12회차 앞까지)
`amount`	필수	그 회차에 걷을 금액(원, 부가세 포함, 1 이상 정수)
`charge_date`		결제일 `"2026-11-03"`. 비우면 그 달 계약 청구일(이미 지났으면 오늘). 정할 때는 오늘 이후이고 다음 회차 청구일보다 앞이어야 합니다
`item_name`		그 회차의 품목명. 비우면 계약 품목명
`memo`		메모(200자)

요청

POST /api/v1/subscriptions/210/charges
Idempotency-Key: sub210-2026-11-v1

{"billing_month": "2026-11", "amount": 38900, "item_name": "11월 이용료"}

같은 달 금액을 고칠 때는 본문이 달라지므로 새 멱등키를 씁니다(같은 키에 다른 본문은 422). 같은 달에 금액을 더 받아야 하면 회차 금액을 늘리거나, 수시결제(동의)·청구서로 따로 받습니다.

넣은 금액 거두기 — POST …/charges/{YYYY-MM}/cancel

결제 대기(PENDING) 또는 건너뜀(SKIPPED) 회차를 다시 NONE(금액 미입력)으로 되돌립니다. 본문은 비우거나 {"reason": "…"} 를 보냅니다. 이미 청구된 회차, 이미 지나간 회차는 되돌릴 수 없습니다.

요청

POST /api/v1/subscriptions/210/charges/2026-11/cancel
Idempotency-Key: sub210-2026-11-cancel

{"reason": "금액 재산정"}

이 회차 건너뛰기 — POST …/charges/{YYYY-MM}/skip

그 회차는 청구하지 않고 넘깁니다(휴무 달 등). 사유(reason, 2자 이상)가 필수입니다. 결제일이 되면 빌링플러스가 청구 없이 다음 회차로 넘어갑니다. 결제일 전이면 cancel 로 되돌릴 수 있습니다.

요청 본문

{"reason": "12월 휴원"}

거절 사유 — 422

처리할 수 없으면 422 UNPROCESSABLE 과 함께 error.detail.reason 이 옵니다. message 에는 "지금 회차는 2026-11 입니다" 처럼 고칠 단서가 들어 있습니다.

detail.reason	뜻
`NOT_VARIABLE`	자동(고정 금액) 계약입니다. 월별 금액은 수동 계약에만 넣습니다
`SUBSCRIPTION_CLOSED`	진행중·일시정지 계약이 아닙니다(해지·만료)
`NOT_A_ROUND`	그 달은 이 계약의 앞으로 걷을 회차가 아닙니다(지난 달, 청구 없는 달, 12회차보다 먼 달)
`ROUND_LOCKED`	이미 청구됐거나 건너뛴 회차라 고칠 수 없습니다. 청구된 회차는 결제 취소 후 따로 받습니다
`INVALID_MONTH`	청구월 형식 오류(`2026-11` 처럼)
`INVALID_DATE`	결제일 형식 오류, 오늘보다 이전, 또는 다음 회차 청구일 이후
`INVALID_AMOUNT`	금액이 숫자가 아니거나 1원 미만
`REASON_REQUIRED`	건너뛰는 사유가 없습니다
`NOT_FOUND`	거두려는 달에 넣은 금액이 없습니다(`cancel`)

계약 자체가 없거나 다른 가맹점의 계약이면 404 NOT_FOUND 입니다.

결제 결과

결제일에 결제가 시도되면 웹훅 subscription.charged 가 갑니다. 수동 계약이면 본문의 amount 가 그 회차에 넣은 금액이고, subscription.amount_mode 가 VARIABLE 입니다. 승인·거절은 result 와 payment.status 로 가릅니다 — 이벤트 예시