연동 문서에 자주 나오는 용어를 처음 보는 사람 기준으로 풀어 둡니다. 흐름 안에서 각 용어가 어디에 쓰이는지는 결제 흐름 이해하기에 있습니다.
계약·설정
| 용어 |
뜻 |
더 보기 |
| PG |
Payment Gateway. 카드사·은행과 가맹점 사이에서 결제를 중계하는 회사입니다 (KCP, 나이스페이먼츠, KG이니시스 등). 계약·정산은 PG사와 합니다 |
PG 가맹과 바로오픈 |
| 가맹점 |
결제를 받는 사업자, 곧 연동하는 쪽입니다 |
|
| 프로젝트 |
Bootpay 관리자에서 결제를 붙일 서비스 단위입니다. 연동키·PG 설정·웹훅 URL 이 프로젝트마다 따로 있습니다 |
환경 설정 |
| 샌드박스 모드 |
관리자 PG 설정에서 결제수단마다 켜는 테스트 모드입니다. 켜 두면 실제 매출 없이 테스트 결제로 처리됩니다. 지원하지 않는 결제수단도 있습니다 |
환경 설정 |
| 바로오픈 |
약 2주 걸리는 PG 심사를 하루 수준으로 줄이는 라이트페이 신청 방식입니다 |
PG 가맹과 바로오픈 |
| MID |
PG사가 가맹점에 발급하는 상점 아이디입니다. 가맹이 끝나면 PG 연동 정보와 함께 관리자 PG 설정에 입력합니다 |
|
키·인증
| 용어 |
뜻 |
더 보기 |
| Client Key |
프로젝트를 가리키는 공개 키입니다. 프론트엔드 SDK 와 서버 인증 헤더에 씁니다 |
연동키 발급 |
| Secret Key |
Client Key 와 한 쌍인 비밀 키입니다. 서버에서만 씁니다. 노출되면 바로 폐기하고 재발급합니다 |
연동키 발급 |
| Application ID · Private Key |
이전 방식의 키입니다. 계속 지원하며 새 연동은 Client Key·Secret Key 를 씁니다 |
연동키 발급 |
| 권한 범위(Scope) |
키 한 쌍이 호출할 수 있는 API 묶음입니다. 범위 밖 API 를 부르면 API_SCOPE_INVALID 가 납니다 |
연동키 발급 |
결제 흐름
| 용어 |
뜻 |
더 보기 |
| 인증 |
구매자가 결제창에서 본인을 확인하는 단계입니다. 아직 돈이 빠져나가지 않습니다 |
결제 흐름 이해하기 |
| 승인 |
PG가 결제를 확정하는 단계입니다. 이때 매출이 생깁니다 |
결제 흐름 이해하기 |
| 서버 승인 · 분리 승인 |
extra.separately_confirmed: true 로 인증과 승인을 나누고, 가맹점 서버가 승인 API 를 호출하는 방식입니다. 권장 방식입니다 |
분리 승인 |
order_id |
가맹점이 만든 주문번호입니다. 결제 요청에 넣고, 서버가 DB 주문과 대조할 때 씁니다 |
|
receipt_id |
Bootpay 가 결제 한 건마다 만드는 거래 ID 입니다. 승인·조회·취소·웹훅이 전부 이 값을 기준으로 합니다 |
결제 조회 |
status |
결제 상태 숫자입니다. 1 결제완료, 2 승인대기, 5 가상계좌 발급, 20 취소완료 |
결제 조회 |
confirm 이벤트 |
서버 승인 방식에서 인증이 끝났을 때 오는 이벤트입니다. 결제 완료가 아닙니다 |
결제창 연동 |
done 이벤트 |
클라이언트 승인 방식에서 결제가 승인됐을 때 프론트엔드가 받는 이벤트입니다. 서버 승인 방식에서는 오지 않습니다. 주문 확정은 서버 검증 뒤에 합니다 |
결제창 연동 |
issued 이벤트 |
가상계좌가 발급됐을 때 오는 이벤트입니다. 입금 전이라 결제 완료가 아닙니다 |
결제창 연동 |
창 모드 (open_type) |
Web 에서 결제창을 여는 방식입니다. iframe·popup·redirect 가 있습니다 |
창 모드 |
redirect_url |
redirect 창 모드에서 결제 결과를 받을 가맹점 주소입니다 |
창 모드 |
서버·운영
| 용어 |
뜻 |
더 보기 |
| 웹훅 |
결제 상태가 바뀔 때 Bootpay 가 가맹점 서버로 보내는 HTTP 요청입니다. 응답 본문에 {"success": true} 를 돌려줘야 성공으로 기록됩니다 |
웹훅 |
webhook_type |
웹훅이 어떤 이벤트인지 나타냅니다. 예: PAYMENT_COMPLETED, PAYMENT_CANCELLED |
웹훅 이벤트 처리 |
feedback_url |
결제 요청마다 웹훅을 받을 주소를 따로 지정하는 옵션입니다 (extra.feedback_url) |
웹훅 |
| 입금통보 URL |
가상계좌 입금을 PG사가 Bootpay 로 알리는 주소입니다. PG사 관리자에 Bootpay 주소를 등록합니다 |
가상계좌 입금 흐름 |
| 멱등 처리 |
같은 요청·웹훅이 두 번 와도 결과가 한 번만 반영되게 하는 처리입니다. receipt_id 로 처리 여부를 확인합니다 |
|
| 부분 취소 |
결제 금액 중 일부만 취소하는 것입니다. 결제수단·PG 에 따라 제한이 있습니다 |
결제 취소 |
저장 결제·반복 결제
| 용어 |
뜻 |
더 보기 |
빌링키 (billing_key) |
고객이 등록한 결제수단 대신 쓰는 암호화된 값입니다. 서버가 이 값으로 결제를 요청합니다 |
자동결제 개요 |
| 자동결제 |
빌링키로 가맹점 서버가 원하는 시점에 청구하는 방식입니다. 청구 시점·재시도는 가맹점이 관리합니다 |
자동결제 개요 |
| 예약결제 |
빌링키로 미래의 결제 한 건을 미리 등록하는 방식입니다. 등록 성공은 결제 성공이 아닙니다 |
예약결제 개요 |
user_id |
가맹점이 회원을 식별하는 고유값입니다 (회원 PK·UUID 등). 바뀌면 저장된 결제수단을 찾지 못합니다 |
회원 토큰 |
user_token |
서버가 user_id 로 발급하는 회원 토큰입니다. 1시간 유효하며 브랜드페이·지갑 결제에 씁니다 |
회원 토큰 |
| 브랜드페이 |
결제위젯에서 로그인 회원이 저장한 카드·계좌로 다시 결제하는 기능입니다 |
브랜드페이 개요 |