참고

변경 이력

공개 API v1 의 변경 이력과 폐기 예고 정책.

버전 정책

추가에 견디는 코드를 써 주세요. 응답이나 웹훅에 모르는 필드가 오면 무시하고, 상태·사유 코드나 이벤트 이름에 모르는 값이 오면 오류로 멈추지 말고 "확인 필요" 로 다루세요. v1 안에서도 이런 값은 늘어날 수 있습니다.

등록창 생성의 멱등 재요청이 같은 주소를 돌려주지 않습니다. 창 주소를 저장하지 않게 바꿨습니다. 같은 키로 다시 보내면 아직 열리지 않은 창은 주소를 새로 발급하고(window_url_reissued: true, 앞 주소는 무효), 열린·만료·사용된 창은 window_url: null 과 지금 상태를 돌려줍니다. 응답에 window_url_reissued 필드를 더했습니다 — 등록창
계약 수정(PATCH /api/v1/subscriptions/{id})이 보낸 항목만 바꿉니다. 전에는 보내지 않은 cycle 이 MONTHLY 로, term_months · payment_method_id · memo 가 빈 값으로 저장됐습니다. 등록 때 필수였던 항목도 수정에서는 선택입니다.
결제 승인이 같은 청구서의 결과 대기 결제 때문에 막히면 422 의 detail.kind 가 PAYMENT_IN_FLIGHT 입니다(전에는 PG_CONFIGURATION). detail.payment_id · detail.payment_status 를 함께 싣습니다 — 에러 처리

없는 경로(404)·받지 않는 메서드(405)도 표준 에러 형식으로 응답합니다. 404 는 NOT_FOUND, 405 는 INVALID_REQUEST + Allow 헤더 · detail.allowed_methods.
멱등키 비교에 경로·메서드를 더했습니다. 같은 키로 본문이 같아도 다른 경로(예: 다른 결제의 취소)를 보내면 422 IDEMPOTENCY_KEY_REUSED 입니다. 전에는 앞 요청의 응답이 그대로 돌아갔습니다.
허용 IP 검사를 서명 확인 뒤로 옮겼습니다. 서명이 틀린 요청은 IP 와 관계없이 401, 서명이 맞고 IP 가 허용 밖이면 403 FORBIDDEN_IP 입니다. 403 호출은 API 호출 로그에 남습니다.
웹훅 재시도를 첫 발송 + 최대 8회로 맞췄습니다(전에는 첫 발송을 포함해 8회).
웹훅은 리다이렉트(3xx)를 따라가지 않고 실패로 봅니다. 내부망·사설 주소로는 보내지 않습니다.
웹훅 재시도는 보내는 순간의 설정(수신 주소·시크릿)을 씁니다. 주소를 비우거나 키를 폐기하면 밀린 재시도를 보내지 않습니다.

월별 청구 금액 API 추가 — GET · POST /api/v1/subscriptions/{id}/charges, …/charges/{YYYY-MM}/cancel, …/charges/{YYYY-MM}/skip. 문서
계약 입출력에 amount_mode(FIXED 자동 / VARIABLE 수동) 추가. 웹훅 계약 요약에도 실립니다.

수시결제 동의 API 추가 — GET /api/v1/charge-consents, GET …/{id}, POST …/{id}/charges, POST …/{id}/revoke. 문서
등록창에 billing_mode(RECURRING / ON_DEMAND) · limit_once · limit_month 입력 추가. 수시결제 동의 창이면 amount · billing_day 는 선택입니다(필수에서 완화). 창 응답에 charge_consent_id · charge_consent_no 추가.
웹훅 charge_consent.created · charge_consent.revoked 추가. 결제·청구서 본문에 charge_consent_no, signup.completed 에 billing_mode · charge_consent 추가.
회원 입력에 payer_email(납부자 이메일) 추가.

가입 링크에 '회원이 요금제 선택'·'고객사 서버가 조건 전달' 방식 추가. signup.completed 에 terms_mode · plan_code 추가. 문서

회원에 external_ref(고객사 회원 ID) 입출력 추가. GET /api/v1/customers?external_ref=…(정확히 일치) 필터 추가.
공용 가입 링크와 웹훅 signup.completed 추가.

결제 취소는 전체취소만 합니다. POST /api/v1/payments/{id}/cancel 의 amount 는 호환을 위해 남겼으며, 비우거나 남은 금액과 같게 보냅니다(다르면 422).
회원 입력 확장 — tel · zipcode · address · address_detail · payer_name · payer_relation · payer_phone · sms_billing · sms_marketing · group(그룹명) · custom_fields. 회원 PATCH 는 보낸 항목만 바꿉니다.
웹훅 이벤트 추가 — customer.created · customer.updated · customer.closed · subscription.created · subscription.updated · subscription.paused · subscription.canceled · subscription.completed · billing_key.registered · invoice.direct_receipt · invoice.direct_receipt_canceled · invoice.written_off · webhook.test.
웹훅 본문 확장 — 결제에 billing_type · channel · method_kind · attempt_no · is_retry · executor 등, 청구서에 items · subscription · collected_via 등, 회원·계약·결제수단 등록 이벤트에 source(되울림 방지).
키마다 받을 웹훅 이벤트 선택, 웹훅 테스트 발송.
레이트리밋 응답 헤더 X-RateLimit-Reset 추가(Retry-After 와 같은 값).
활성 API 키 상한을 4개로.
OpenAPI 스펙에 Webhooks 절(이벤트별 요청 예시) 추가.

회원 · 결제수단(조회·폐기) · 청구서 · 결제(승인·취소·조회) · 정기결제 계약 API.
등록창 API(/api/v1/register-windows), 연동 점검 /api/v1/ping.
아웃바운드 웹훅 payment.approved · payment.failed · payment.canceled · subscription.charged · invoice.paid · billing_key.deleted.