# Bootpay PG

> 부트페이 PG 연동 개발자 문서. 한 번 연동으로 여러 PG를 지원합니다.

---

## 관련 문서

| 문서 | 설명 |
|------|------|
| [llms.txt](https://developers.bootpay.co.kr/llms/llms.txt) | 전체 문서 인덱스 (PG + Commerce) |
| [commerce.txt](https://developers.bootpay.co.kr/llms/commerce.txt) | Commerce API (상품 판매, 구독 결제) |

---

## AI 에이전트 주의사항

1. **이 문서에 명시된 링크만 사용** - URL을 추측하거나 변형하지 마세요
2. **존재하지 않는 URL 추측 금지** - `docs.bootpay.co.kr` 등 레거시 URL 무효
3. **언어별 예제 경로 패턴**: `{기능}/{언어}.md` (예: `pg/server/token/nodejs.md`)

### 존재하는 서버 API (언어별 파일 있음)

| API | 경로 패턴 | 설명 |
|-----|----------|------|
| 토큰 발급 | `pg/server/token/{언어}.md` | Access Token 발급 |
| 영수증 조회 | `pg/server/receipt/{언어}.md` | 결제 정보 조회 (**결제 검증용**) |
| 결제 취소 | `pg/server/cancel/{언어}.md` | 환불/취소 처리 |

### 존재하지 않는 경로 (추측 금지)

- `pg/server/verify/...` - 없음 (영수증 조회 `receipt` 사용)
- `pg/server/confirm/{언어}.md` - 없음 (개요 파일 `confirm.md`만 존재)
- `pg/server/payment/...` - 없음
- `pg/server/refund/...` - 없음 (결제 취소 `cancel` 사용)

---

## PG 연동 순서 (매우 중요)

**국내 PG 결제는 반드시 브라우저/앱(프론트엔드)에서 시작합니다.**

```
1. 프론트엔드 (JS/Android/iOS): 결제 위젯 렌더링 → 사용자 결제 → receipt_id 받음
2. 백엔드 (Python/Node.js 등): receipt_id로 검증만 수행
```

### 흔한 실수 (절대 금지)

- 백엔드에서 결제 시작하기 → 불가능! 결제창은 브라우저에서만 열림
- Python/Node.js로 "Bootpay HTTP 래퍼" 만들기 → 사용자가 직접 결제창에서 진행해야 함
- API 규격 보고 fetch/requests로 직접 구현 → **SDK 설치해서 사용!**

---

## 백엔드 SDK 사용 필수

```
잘못된 구현: requests.post('https://api.bootpay.co.kr/v2/...')
올바른 구현: SDK 설치 후 메서드 호출
```

| 언어 | 설치 | 패키지 |
|------|------|--------|
| Node.js | `npm i @bootpay/backend-js` | @bootpay/backend-js |
| Python | `pip install bootpay-backend` | bootpay-backend |
| PHP | `composer require bootpay/backend-php` | bootpay/backend-php |
| Java | Maven/Gradle | kr.co.bootpay:backend |
| Go | `go get github.com/bootpay/backend-go` | backend-go |
| Ruby | `gem install bootpay` | bootpay |
| .NET | `dotnet add package Bootpay.BackendApi` | Bootpay.BackendApi |

> **SDK 버전 명시 금지**: `@1.2.3`, `==2.0.0` 등 버전 추론 금지. 최신 버전 설치.

---

## 프론트엔드 CDN URL

```html
<!-- PG 위젯 (5.0.0 이상 필수) -->
<script src="https://js.bootpay.co.kr/bootpay-widget-5.2.0.min.js"></script>

<!-- PG 기본 -->
<script src="https://js.bootpay.co.kr/bootpay-5.2.0.min.js"></script>
```

> **위젯(BootpayWidget)은 5.0.0 이상 버전에서만 사용 가능** (4.x 이하 불가)
> 버전 번호 추론 금지 (5.3.0, 6.0.0 등 임의 버전 사용 금지)

---

## 코드 작성 규칙

```javascript
// 잘못된 메서드 (추론)
Bootpay.renderWidget()
Bootpay.render()
Bootpay.openPayment()

// 올바른 메서드 (문서에서 복사)
BootpayWidget.render('#selector', { ... })
BootpayWidget.requestPayment({ ... })
BootpayWidget.update({ ... })
```

---

## 구현 순서 (5단계)

| 순서 | 단계 | 역할 | 문서 |
|------|------|------|------|
| **1** | 위젯 렌더링 | 프론트엔드 | [quickstart.md](https://developers.bootpay.co.kr/llms/pg/quickstart.md) |
| **2** | 결제 검증 | 백엔드 (필수) | [receipt.md](https://developers.bootpay.co.kr/llms/pg/server/receipt.md) |
| **3** | 분리 승인 | 백엔드 (선택) | [confirm.md](https://developers.bootpay.co.kr/llms/pg/server/confirm.md) |
| **4** | 웹훅 처리 | 백엔드 (권장) | [webhook/server.md](https://developers.bootpay.co.kr/llms/pg/webhook/server.md) |
| **5** | 결제 취소 | 백엔드 (필요시) | [cancel.md](https://developers.bootpay.co.kr/llms/pg/server/cancel.md) |

> **순서 중요**: Step 1 (프론트엔드) → Step 2 (백엔드 검증) 순서를 반드시 지키세요.

---

## 정산 구조

**PG 연동 = 결제 수납만. 정산은 PG사가 가맹점에게 직접 처리합니다.**

- 고객 결제 → PG사 수납 → D+n일 후 가맹점 계좌로 정산
- 정산/출금/에스크로 시스템을 직접 구현할 필요 없음
- 플랫폼(마켓플레이스)에서 판매자 정산이 필요하면 → Commerce API 또는 지급대행 서비스 검토

---

## 시작하기

- [PG 소개](https://developers.bootpay.co.kr/llms/pg/intro.md): 부트페이 PG 서비스 개요
- [빠른 시작](https://developers.bootpay.co.kr/llms/pg/quickstart.md): 5분 안에 결제 연동하기

## 환경 설정

1. [부트페이 관리자](https://admin.bootpay.co.kr) 가입
2. [프로젝트 생성](https://admin.bootpay.co.kr/project)
3. [API 키 확인](https://admin.bootpay.co.kr/setting/developer) (Application ID, Private Key)
4. [위젯 설정](https://admin.bootpay.co.kr/payment/bootpay-widget)

## 프론트엔드 SDK

- [JavaScript](https://developers.bootpay.co.kr/llms/pg/sdk/web.md): 웹 결제 연동
- [위젯 소개](https://developers.bootpay.co.kr/llms/pg/widget/intro.md): 결제 위젯 개요

## 서버 연동

> 언어별 예제: `{기능}/{언어}.md` (nodejs, python, php, java, ruby, go, dotnet)

- [토큰 발급](https://developers.bootpay.co.kr/llms/pg/server/token.md): Access Token 발급
- [결제 승인](https://developers.bootpay.co.kr/llms/pg/server/confirm.md): 분리승인 모드에서 결제 최종 승인
- [결제 취소](https://developers.bootpay.co.kr/llms/pg/server/cancel.md): 결제 취소/환불
- [영수증 조회](https://developers.bootpay.co.kr/llms/pg/server/receipt.md): 결제 내역 조회

## 자동결제 (빌링)

- [빌링 흐름](https://developers.bootpay.co.kr/llms/pg/billing/flow.md): 자동결제 개념과 흐름
- [빌링키 발급](https://developers.bootpay.co.kr/llms/pg/billing/card-key.md): 카드 빌링키 발급
- [빌링 결제](https://developers.bootpay.co.kr/llms/pg/billing/request.md): 빌링 결제 요청
- [빌링 조회](https://developers.bootpay.co.kr/llms/pg/billing/lookup.md): 빌링 정보 조회
- [빌링 해지](https://developers.bootpay.co.kr/llms/pg/billing/destroy.md): 빌링키 해지
- [예약 결제](https://developers.bootpay.co.kr/llms/pg/billing/reserve.md): 예약 결제 등록

## 웹훅

- [웹훅 설정](https://developers.bootpay.co.kr/llms/pg/webhook/server.md): 서버 웹훅 URL 설정

---

## 도움말

- 개발자센터: https://developers.bootpay.co.kr
- 관리자: https://admin.bootpay.co.kr
- 기술문의: https://bootpay.channel.io/home