결제창 개요

결제 버튼을 누르면 PG 결제창이 열리고, 구매자가 그 안에서 결제수단을 골라 결제하는 단건 결제입니다. 카드·간편결제·계좌이체·가상계좌·휴대폰결제를 SDK 하나로 받습니다.

핵심 흐름

requestPayment() 로 결제창 열기 → 구매자 인증 → confirm 으로 receipt_id 수신 → 서버가 승인 API 호출 → 승인 응답 금액으로 주문 확정.

언제 쓰나

맞는 경우

  • 주문마다 한 번 결제합니다
  • 결제 화면을 직접 만들지 않고 PG 화면을 씁니다
  • 회원가입 없는 주문도 받습니다

다른 상품이 맞는 경우

결제창은 두 가지로 엽니다.

종류 동작
통합결제창 관리자에서 켠 PG·결제수단 중 구매자가 고릅니다. 수단을 바꿔도 코드 배포가 필요 없습니다. pg·method 를 비우거나 일부만 지정합니다 → 통합결제창
다이렉트 결제창 특정 PG의 특정 수단으로 바로 엽니다. pg·method 를 지정합니다

결제 흐름

  1. 주문 생성 — 결제창을 열기 전에 주문번호와 금액을 DB 에 저장합니다
  2. 결제창 호출 — 프론트엔드가 extra.separately_confirmed: true 를 넣어 결제창을 엽니다
  3. 인증 — 구매자가 결제수단을 고르고 인증합니다. 아직 결제되지 않았습니다
  4. 인증 완료 — confirm 이벤트로 receipt_id 를 받습니다. Web redirect 창 모드에서는 redirect_url 서버 라우트가 받습니다
  5. 승인 — 서버가 재고·주문 상태를 확인한 뒤 승인 API 를 호출합니다
  6. 주문 확정 — 승인 응답의 price 가 DB 금액과 같으면 주문을 완료하고, 다르면 결제를 취소합니다
  7. 웹훅 — 4~6단계가 끊긴 주문을 웹훅으로 마무리합니다. 가상계좌는 입금 완료를 웹훅으로만 받습니다
결제 완료는 승인 응답으로 판단합니다

confirm 은 인증이 끝났다는 신호이고 결제 완료가 아닙니다. 화면 이벤트만 보고 주문을 확정하지 않습니다.

누가 무엇을 하나

위치 할 일 문서
관리자 PG·결제수단 활성화, 샌드박스 모드, 웹훅 URL 등록 환경 설정
프론트엔드 SDK 설치, 결제창 호출, confirm·issued·error 처리, 결과 화면 결제창 연동
백엔드 주문 생성, 승인 API 호출, 금액 비교, 웹훅 수신, 취소 결제창 연동 → 승인 · 웹훅

연동 전 확인

  • Web 은 SDK 5.5.2 이상에서 PC iframe, 모바일 redirect 로 엽니다. SDK 를 바로 올릴 수 없으면 PC 는 popup 으로 엽니다. 5.5.1 이하 iframe 에서는 ISP 카드 결제가 막힐 수 있습니다 → 창 모드
  • 앱 SDK(iOS·Android·Flutter·React Native)는 창 모드를 고르지 않습니다. 앱 복귀는 SDK 가 처리합니다.
  • 페이앱·페이레터·키움페이는 서버 승인을 지원하지 않습니다. 자동 승인 뒤 서버에서 결제 조회로 확정합니다 → 분리 승인
  • 가상계좌를 쓰면 PG사 관리자에 입금통보 URL 을 등록해야 입금 웹훅이 옵니다 → 가상계좌 입금 흐름
  • 앱 웹뷰에서 결제창을 열면 부트페이 웹뷰를 씁니다.

다음 문서

  • 결제창 연동 — SDK 설치부터 승인·결과 수신까지 플랫폼별 코드
  • 분리 승인 — 서버 승인 세부 흐름과 응답 코드
  • 창 모드 — iframe·popup·redirect 선택 기준
  • 에러 처리 — error 이벤트와 실패 시나리오

함께 보기