등록창 API로 카드번호 없이 카드 등록 받기

가맹점 서버가 카드번호를 다루지 않고도 회원 카드를 등록받는 등록창 API의 흐름과 구현 시 주의할 점을 정리했습니다.

자체 회원 시스템이 있는 서비스는 "우리 사이트 안에서 카드를 등록받고 싶다"고 생각합니다. 하지만 카드번호가 가맹점 서버를 지나면 보안 부담이 커집니다. 빌링플러스는 가맹점 API로 카드번호를 받는 엔드포인트를 두지 않고, 대신 등록창을 제공합니다.

등록창의 흐름

카드번호는 회원 브라우저에서 등록창으로만 들어가므로 가맹점 서버를 지나지 않습니다.

복귀 도메인 등록: 설정 > 가맹점 정보에 홈페이지 주소를 등록합니다. 등록하지 않은 도메인으로는 결과를 돌려보내지 않습니다. 하나도 없으면 창 생성이 거부됩니다.
Idempotency-Key: 창 생성도 POST이므로 멱등키가 필요합니다. 같은 키로 다시 보내도 창은 하나만 생깁니다.

규칙	이유
생성 응답에만 실림	조회로 다시 꺼낼 수 없음. 잃어버리면 새로 엽니다
문자·메일로 보내지 않음	회원에게 보낼 링크가 필요하면 등록 링크를 씁니다
같은 키 재요청 시	아직 아무도 열지 않은 창이면 새 주소를 발급하고 옛 주소는 무효

금액·청구일 같은 계약 조건은 창을 열 때 먼저 검증합니다. 회원이 카드를 다 입력한 뒤에 조건 오류가 나면 되돌릴 수 없기 때문입니다. 창 생성 요청이 422로 오면 조건을 고쳐 다시 여세요.

이미 등록이 끝난 창은 닫히지 않습니다. 계약을 끝내려면 계약 해지 API를 써야 합니다. "창을 닫았으니 취소됐겠지"로 두면 다음 청구일에 그대로 결제됩니다.

정기결제 대신 '필요할 때 결제' 동의를 받으려면 창을 열 때 수시결제 방식과 1회·월 한도를 함께 보냅니다. 동의를 API로 직접 만드는 경로는 없고 회원이 등록창에서 직접 동의합니다.

창을 열 때 붙인 가맹점 측 참조값으로 창 목록을 거를 수 있어, 자체 주문이나 회원과 연결해 상태를 확인하기 쉽습니다. 창 목록은 열림·사용됨·만료 상태로도 거를 수 있습니다.

창을 여는 요청은 결제 경로와 같은 낮은 호출 한도가 적용되므로 필요할 때만 여세요.

요청·응답 필드는 등록창 문서에 있습니다. 홈페이지 버튼만으로 가입을 받고 싶다면 가입 링크 문서도 비교해 보세요.

우리 사업에 맞게 시작하고 싶다면

회원 규모와 지금의 결제 방식을 알려 주시면 담당자가 도입 방법을 안내해 드립니다.