위젯 생성 | Bootpay 결제 매뉴얼

핵심 요약

이 문서는 관리자에서 끝내야 하는 초기 설정을 다뤄요. SDK 렌더링, 이벤트 처리, 서버 검증은 단건결제위젯 연동과 정기결제위젯 연동에서 다뤄요.
결제위젯은 관리자에서 먼저 만들고, 발급된 widget_key를 SDK 렌더링 payload에 넣어 사용해요.
한 위젯 안에서 노출할 결제수단, 결제수단별 PG, PG 가중치, 약관, 디자인, 브랜드페이 노출 여부를 설정할 수 있어요.
위젯 타입은 단건결제와 정기결제(구독) 두 종류예요. 유형은 widget_key에 묶이므로 SDK 호출 시 별도 type 인자를 넘기지 않아요.

관리자 설정은 아래 순서로 진행해요.

위젯에서 노출할 결제수단은 결제 설정에 활성화된 PG·결제수단을 기준으로 해요. 위젯을 만들기 전에 사용할 PG와 결제수단을 먼저 켜두면 설정 흐름이 덜 꼬여요.

관리자 → 결제위젯 설정으로 이동해서 우측 상단 새로운 위젯 만들기를 눌러요.

위젯은 카드사 바로가기 기능을 지원하는 PG에서만 동작해요. 현재 라이트페이, 나이스페이, KCP만 지원해요. 다른 PG로만 결제 설정이 되어 있으면 위젯이 뜨지 않아요.

항목	설명
위젯 유형	`단건 결제` 또는 `구독 결제` 중 선택. 한 번 정하면 위젯의 동작 모드가 바뀌어요
위젯 이름	관리자 목록에서 식별하기 위한 라벨. `기본 위젯`, `B2B 결제용`처럼 운영 기준으로 적어요
고유키 (widget_key)	SDK의 `widget_key` 파라미터로 전달되는 값. 중복 불가. 영문 소문자/숫자/하이픈 조합으로 지어요 (`default-widget`, `subscribe-pro` 등)

저장하면 위젯 카드가 목록에 추가되고, 카드의 key가 곧 SDK에서 쓸 식별자예요.

위젯 카드의 라이브 또는 샌드박스 버튼을 누르면 위젯 편집 화면으로 들어가요. 좌측 사이드바에서 결제수단 탭을 열면 한 위젯 안에서 노출할 결제수단을 결정할 수 있어요.

화면은 두 영역으로 나뉘어요.

결제수단 목록 (왼쪽) — 카드, 계좌이체, 가상계좌, 휴대폰, 간편결제 같은 결제수단별 항목. 각 항목에는 현재 활성화된 PG 개수와 대표 PG가 표시돼요.
PG 카드 목록 (오른쪽) — 선택한 결제수단에서 사용할 수 있는 PG사가 카드 형태로 나열돼요.

PG 카드의 토글 스위치로 위젯에서 해당 PG-결제수단 조합을 켜고 꺼요. 토글을 켜면 그 결제수단을 통해 결제할 때 이 PG가 후보로 들어가요.

카드 결제수단을 PG에 연결할 때, 카드 패널 상단에 안내가 떠요.

같은 결제수단에 여러 PG가 켜져 있으면 카드 하단에 가중치가 표시돼요. 위쪽/아래쪽 화살표로 숫자를 조절해요. 표시되는 %는 전체 가중치 합계 기준 분배 비율이에요.

가중치 7  →  70%
가중치 3  →  30%

위젯이 결제 요청을 보낼 때 이 비율대로 라운드로빈에 가까운 분배가 일어나요. PG 점검·장애 대응이나 결제 단가 조정이 필요할 때 코드 배포 없이 가중치만 바꿔서 트래픽을 옮길 수 있어요.

PG 연동 정보가 설정되지 않았다면 이곳에서도 설정할 수 있어요. PG 카드 하단의 연동정보 설정하기를 펼치면 PG가 요구하는 연동 키 입력 폼이 나와요. PG와 결제수단 조합마다 필요 항목이 달라요. (MID, 상점키, 라이센스키 등)

입력	의미
샌드박스 토글	켜져 있으면 Bootpay가 PG의 테스트 환경으로 요청을 보내요. 실서비스 전환 전에 반드시 꺼야 해요.
저장하기	입력한 연동정보를 저장해요. 샌드박스 모드에서는 비활성화되어 있고, 실서버 모드일 때만 저장 가능해요.

모든 활성 PG-결제수단 조합의 샌드박스 모드가 꺼져 있는지 확인해야 해요. 한 곳이라도 켜져 있으면 그 결제만 테스트 환경으로 빠져요.
연동정보 저장 후 위젯 미리보기에서 실제 PG 결제창이 떠야 정상이에요.

좌측 사이드바의 다른 탭은 모두 이 위젯에만 적용되는 옵션이에요. 위젯마다 따로 설정해요.

각 탭은 기능 / 디자인 두 모드로 나뉘어요. 기능 모드는 노출 여부·항목 구성, 디자인 모드는 색상·여백·폰트 사이즈 같은 시각 요소를 다뤄요. 모두 코드 변경 없이 관리자에서 조정해요.

관리자는 결제수단 노출, PG 우선순위, 약관, 색상, 레이아웃을 조정해요. 개발 코드는 widget_key로 위젯을 렌더링하고, 결제 요청·인증 결과·승인 요청·서버 검증·주문 확정을 처리해야 해요.

위젯 카드의 두 버튼은 각각 다른 환경의 미리보기 화면으로 이동해요.

미리보기 우측 패널은 실제 결제위젯 SDK가 렌더링한 화면이에요. 관리자에서 결제수단/가중치를 바꾸면 즉시 반영돼요.

위젯 키와 초기 설정이 끝났다면 위젯 유형에 맞는 연동 가이드로 넘어가요.

단건결제위젯 연동 — 발급받은 widget_key로 결제위젯을 페이지에 띄우는 SDK 사용법, 이벤트 처리, 금액 업데이트, 응답 처리까지 한 페이지로 정리