결제 흐름 이해하기

결제 코드를 쓰기 전에 알아야 할 개념 네 가지를 정리합니다. 이 페이지의 용어가 낯설면 용어 사전을 함께 엽니다.

한 줄 요약

구매자가 결제창에서 인증 → 가맹점 서버가 승인 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 결제취소완료 주문을 취소 상태로 보정

다음 문서

함께 보기