결제 코드를 쓰기 전에 알아야 할 개념 네 가지를 정리합니다. 이 페이지의 용어가 낯설면 용어 사전을 함께 엽니다.
구매자가 결제창에서 인증 → 가맹점 서버가 승인 API 호출 → 승인 응답의 금액·상태로 주문 확정 → 웹훅으로 한 번 더 확인.
1Bootpay 가 대신하는 일
온라인 결제는 PG(Payment Gateway, 카드사·은행과 가맹점 사이에서 결제를 중계하는 회사)를 거칩니다. PG마다 SDK·요청 형식·결과 통보 방식이 다르고, Bootpay 는 그 차이를 하나의 SDK·API로 묶습니다.
| 구분 | PG 직접 연동 | Bootpay 연동 |
|---|---|---|
| 결제 호출 | PG마다 다른 SDK·요청 형식 | Bootpay SDK 하나 (Web·iOS·Android·Flutter·React Native) |
| 서버 API | PG마다 다른 승인·조회·취소 API | Bootpay REST API 하나 (receipt_id 기준) |
| PG 추가·변경 | PG별 연동 코드를 새로 작성 | 관리자 PG 설정에서 활성화. 통합결제창·결제위젯은 코드 수정 없이 반영 |
| 결과 통보 | PG마다 다른 형식 | Bootpay 웹훅 하나 (webhook_type 으로 이벤트 구분) |
| PG 계약·정산 | PG사와 직접 | PG사와 계약하고 PG사가 정산합니다. 신청은 Bootpay 관리자에서 합니다 |
2인증과 승인
결제는 두 단계로 나뉩니다. 이 구분이 연동 코드 전체의 기준입니다.
| 단계 | 하는 일 | 돈이 빠져나가나 |
|---|---|---|
| 인증 | 구매자가 결제창에서 카드사 앱·간편결제 비밀번호 등으로 본인을 확인합니다 | 아니요 |
| 승인 | PG가 카드사·은행에 결제를 확정합니다. 이때 매출이 생깁니다 | 예 |
인증이 끝났다고 결제가 끝난 것이 아닙니다. 인증 뒤 창을 닫거나 네트워크가 끊기면 승인이 일어나지 않습니다. 인증과 승인 사이에 일어나는 일(카카오페이 잔액 자동 충전 등)은 결제 흐름 레퍼런스에 있습니다.
3승인은 서버가 합니다
Bootpay 는 승인을 누가 호출하느냐에 따라 두 가지 방식을 지원합니다. 기본으로 권장하는 방식은 서버 승인입니다.
| 서버 승인 (권장) | 클라이언트 승인 | |
|---|---|---|
| 설정 | extra.separately_confirmed: true |
기본값 |
| 흐름 | 인증 완료 시 confirm 이벤트 → 서버가 재고·주문을 확인하고 승인 API 호출 |
인증 뒤 SDK 가 자동으로 승인 → done 이벤트 |
| 주문 확정 기준 | 승인 API 응답의 status·price |
서버에서 receipt_id 로 결제 조회한 결과 |
| 장점 | 승인 전에 재고·쿠폰을 막을 수 있습니다 | 구현이 짧습니다 |
서버 승인을 쓰면 승인 응답이 곧 결제 결과입니다. 승인 전에 결제 조회를 따로 부를 필요가 없습니다. 페이앱·페이레터·키움페이는 서버 승인을 지원하지 않아 클라이언트 승인 후 조회로 확정합니다. 자세한 흐름은 분리 승인에 있습니다.
프론트엔드가 받는 confirm·done 이벤트는 다음 처리를 이어갈 식별값(receipt_id)일 뿐입니다. 화면 이벤트만 보고 주문을 완료하면 금액을 조작한 요청도 통과합니다. 서버가 받은 승인 응답(또는 조회 결과)의 금액을 DB 주문 금액과 비교한 뒤 확정합니다.
4웹훅은 보험입니다
구매자가 결제 직후 앱을 닫거나 네트워크가 끊기면 프론트엔드 이벤트가 서버에 도착하지 않습니다. 웹훅(Bootpay 가 결제 상태가 바뀔 때 가맹점 서버로 보내는 HTTP 요청)은 이 누락을 메웁니다.
- 가상계좌는 결제창이 닫힐 때 계좌 발급만 끝납니다. 실제 입금 완료는 웹훅으로만 알 수 있습니다.
- 웹훅 URL 은 관리자 개발자 설정 또는 결제 요청의
extra.feedback_url에 등록해야 발송됩니다. - 응답 본문에
{"success": true}를 돌려줘야 성공으로 기록됩니다. HTTP 200만 돌려주면 재시도합니다. - 같은 이벤트가 두 번 올 수 있습니다.
receipt_id기준으로 이미 처리한 건은 건너뜁니다.
설정 방법은 웹훅에 있습니다.
결제 상태 값
결제 조회·승인 응답의 status 중 연동에서 자주 보는 값입니다. 전체 목록은 결제 조회에 있습니다.
| status | 의미 | 주문 처리 |
|---|---|---|
1 |
결제완료 | 금액·주문번호가 맞으면 주문 확정 |
2 |
입금/승인대기 | 서버 승인 방식에서 승인 API 호출 전 상태 |
5 |
가상계좌발급완료 | 입금 대기로 저장, 입금 웹훅(status: 1)에서 확정 |
20 |
결제취소완료 | 주문을 취소 상태로 보정 |
다음 문서
- 결제 연동 시작하기 — 연동 단계와 테스트·운영 차이
- 결제 상품 둘러보기 — 어떤 결제 상품을 쓸지 고르기
- 용어 사전 — 문서에 나오는 용어 뜻



