정기결제 API 연동 가이드: 화면과 API 함께 쓰기
빌링플러스 정기결제 API로 무엇을 연결할 수 있는지, 인증 방식과 연동 순서, 화면과 API를 섞어 쓰는 방법을 개발자 관점에서 정리했습니다.
자체 서비스에 정기결제를 붙이려는 개발자에게 가장 큰 부담은 결제사 승인 API 자체보다 그 주변입니다. 청구일 계산, 매일 도는 배치, 재청구, 미확정 처리, 운영 화면까지 만들어야 하기 때문입니다. 빌링플러스는 이 부분을 플랫폼이 운영하고, 개발자는 필요한 업무만 API와 웹훅으로 연결합니다.
무엇을 직접 만들지 않아도 되나
결제사 정기결제를 직접 연동해 배치·재청구·관리 화면까지 만드는 경우와 비교하면 개발 기간과 작업량이 90% 이상 줄어듭니다(빌링플러스 자체 기준). 청구일에 결제를 실행하는 배치는 빌링플러스가 운영하므로, 가맹점 서버가 크론을 돌릴 필요가 없습니다.
연동 순서
- 설정 > API 연동에서 API 키와 시크릿을 발급합니다. 시크릿은 발급 화면에서 한 번만 보입니다.
- 서명 헤더를 만들어
GET /api/v1/ping으로 연결을 확인합니다. 응답의 가맹점명과 서버 시각으로 키와 시계를 점검합니다. - 회원 등록 API로 회원을 만들고, 카드는 등록창이나 등록 링크로 받습니다.
- 계약 API로 금액·청구일·주기를 정합니다.
- 웹훅 수신 주소를 등록해 결제 결과를 받습니다.
인증: HMAC 서명
요청마다 X-BillingPlus-Key, X-BillingPlus-Timestamp, X-BillingPlus-Nonce, X-BillingPlus-Signature 헤더를 보냅니다. 서명은 메서드, 쿼리스트링을 포함한 경로, 타임스탬프, 논스, 본문 해시를 줄바꿈으로 이어 시크릿으로 HMAC-SHA256 한 값입니다. 시각은 서버와 5분 이상 어긋나면 거부되고, 같은 논스는 다시 쓸 수 없습니다. 자세한 예제는 인증 문서에 있습니다.
POST에는 Idempotency-Key
모든 POST 요청에는 Idempotency-Key 헤더가 필요합니다. 같은 키로 다시 보내면 새로 처리하지 않고 저장된 응답을 돌려주므로, 네트워크 오류로 재시도해도 결제가 두 번 나가지 않습니다.
화면과 API를 섞어 써도 됩니다
- 화면과 API는 같은 결제 경로를 쓰므로 결과가 한곳에 모입니다.
- 회원은 API로 만들고 미납 처리는 화면에서 해도 됩니다.
- 카드번호를 우리 API로 보내는 엔드포인트는 없습니다. 카드는 등록창이나 링크로 회원이 직접 입력합니다.
- 결제 거절은 서버 오류가 아니라 정상 응답의 실패 상태로 옵니다.
연동 뒤에는 설정 메뉴의 연동 현황 화면에서 호출 실패율과 웹훅 전달률을 확인하세요. 문제가 생기면 화면이 경고와 함께 할 일을 알려 줍니다.
다음 단계
처음이라면 빠른 시작부터 보세요. 전체 엔드포인트는 API 레퍼런스에, 오류 형식은 오류 문서에 있습니다. 연동 범위를 정하기 어렵다면 도입 상담을 남겨 주세요.