결제 버튼을 누르면 PG 결제창이 열리고, 구매자가 그 안에서 결제수단을 골라 결제하는 단건 결제입니다. 카드·간편결제·계좌이체·가상계좌·휴대폰결제를 SDK 하나로 받습니다.
핵심 흐름
requestPayment() 로 결제창 열기 → 구매자 인증 → confirm 으로 receipt_id 수신 → 서버가 승인 API 호출 → 승인 응답 금액으로 주문 확정.
언제 쓰나
맞는 경우
- 주문마다 한 번 결제합니다
- 결제 화면을 직접 만들지 않고 PG 화면을 씁니다
- 회원가입 없는 주문도 받습니다
결제창은 두 가지로 엽니다.
| 종류 | 동작 |
|---|---|
| 통합결제창 | 관리자에서 켠 PG·결제수단 중 구매자가 고릅니다. 수단을 바꿔도 코드 배포가 필요 없습니다. pg·method 를 비우거나 일부만 지정합니다 → 통합결제창 |
| 다이렉트 결제창 | 특정 PG의 특정 수단으로 바로 엽니다. pg·method 를 지정합니다 |
결제 흐름
- 주문 생성 — 결제창을 열기 전에 주문번호와 금액을 DB 에 저장합니다
- 결제창 호출 — 프론트엔드가
extra.separately_confirmed: true를 넣어 결제창을 엽니다 - 인증 — 구매자가 결제수단을 고르고 인증합니다. 아직 결제되지 않았습니다
- 인증 완료 —
confirm이벤트로receipt_id를 받습니다. Webredirect창 모드에서는redirect_url서버 라우트가 받습니다 - 승인 — 서버가 재고·주문 상태를 확인한 뒤 승인 API 를 호출합니다
- 주문 확정 — 승인 응답의
price가 DB 금액과 같으면 주문을 완료하고, 다르면 결제를 취소합니다 - 웹훅 — 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 을 등록해야 입금 웹훅이 옵니다 → 가상계좌 입금 흐름
- 앱 웹뷰에서 결제창을 열면 부트페이 웹뷰를 씁니다.



