Claude Code 같은 AI 에이전트를 쓴다면, 채팅창에 이 한 줄이면 시작돼요.
https://github.com/bootpay/bootpay-mcp 참조해서 mcp 설치해주고, 결제 연동해줘.에이전트가 Bootpay MCP 를 먼저 설치하고, 그 도구로 연동키까지 조회해서 결제창·결제위젯·서버 검증 코드를 만들어줘요. MCP 를 붙이면 매번 GitHub 을 새로 읽지 않고 최신 문서·SDK 버전·관리자 도구를 바로 부를 수 있어요. 동작 원리와 직접 붙이는 순서가 궁금하면 아래를 이어서 읽어요.
부트페이 결제 SDK로 웹·앱에 결제를 붙일 수 있어요. 처음부터 모든 기능을 다 볼 필요는 없어요. 먼저 단건 결제 하나를 성공시키고, 그 다음 결제수단·위젯·브랜드페이·자동결제·예약결제로 확장하면 돼요.
이 문서는 코드를 바로 쓰는 문서라기보다, 어떤 순서로 문서를 읽고 어떤 책임을 나눠야 하는지 잡는 입구예요.
영상으로 보기
PG 연동부터 런칭까지 전체 로드맵 · 7분 1초
처음 읽는 순서
처음 연동한다면 아래 순서로 보면 가장 덜 헷갈려요.
| 순서 | 볼 문서 | 여기서 결정할 것 |
|---|---|---|
| 1 | 환경 설정 | 프로젝트, PG사, Sandbox |
| 2 | 연동키 발급 | Client Key·Secret Key, 권한, 만료 |
| 3 | 결제 상품 둘러보기 | 결제창·위젯·브랜드페이·자동결제·예약결제 중 선택 |
| 4 | 빠른 매뉴얼 | 선택한 상품의 최소 구현 흐름 확인 |
| 5 | 상세 문서 | 옵션, 예외, 운영 정책까지 보강 |
| 6 | 배포 체크리스트 | 운영 전 누락된 설정 점검 |
처음이라면 결제창 또는 결제위젯으로 첫 결제를 붙이는 게 좋아요. 결제 경험을 먼저 만들고, 서버 검증·웹훅·취소 처리를 붙이면 운영 흐름이 잡혀요.
첫 결제 흐름
단건 결제는 보통 아래 순서로 붙여요.
여기서 중요한 건 “결제창을 띄웠다”가 끝이 아니라는 점이에요. 백엔드에서 receipt_id로 결제 정보를 다시 조회하고, DB에 저장해 둔 금액·주문 상태와 비교한 뒤 주문을 확정해야 해요.
서버 승인 방식이 필요한 경우에는 상세 문서에서 다뤄요. 첫 연동 단계에서는 먼저 receipt_id를 서버로 보내 검증하고 주문 상태를 저장하는 경계를 이해하면 충분해요.
Bootpay가 줄여주는 일, 그래도 챙겨야 할 일
Bootpay는 결제창, 결제위젯, 승인 API, 취소 API, 웹훅처럼 결제에 필요한 여러 기능을 PG사 상관없이 동일한 인터페이스로 제공해요. 그래서 카드사·PG사마다 다른 결제 화면과 통신 방식을 직접 만들 필요는 없어요.
다만 Bootpay가 알 수 없는 영역이 있어요. 이 결제가 내 서비스의 어떤 주문인지, 정확히 얼마를 받아야 하는지, 결제 후 주문을 어떤 상태로 바꿀지는 서비스 쪽에서 정해야 해요.
| 구분 | Bootpay가 맡는 일 | 서비스 쪽에서 챙길 일 |
|---|---|---|
| 결제 화면 | 결제창 또는 결제위젯 제공 | SDK 설치, 결제 요청 데이터 생성 |
| 결제 식별 | receipt_id 발급 |
내부 order_id와 매칭 |
| 결제 조회·승인 | 조회·승인 API 제공 | 금액·상태·재고·쿠폰 확인 |
| 주문 저장 | 결제 결과 데이터 제공 | 서비스 자체 주문 상태(예: 결제완료)로 저장 |
| 웹훅 | 결제 완료, 취소, 입금 상태 알림 | 웹훅 수신, 중복 처리, 주문 상태 업데이트 |
| 취소·환불 | 취소 API와 결과 데이터 제공 | 취소 가능 여부 확인 후 API 호출 |
정리하면, 결제 기능 자체는 Bootpay가 줄여줘요. 대신 주문 상태, 금액 검증, 재고·쿠폰 같은 서비스 판단은 내 서버가 책임져야 해요.
화면·서버·관리자의 역할
결제 연동은 화면, 서버, Bootpay 관리자 역할을 나눠서 보면 쉬워요.
| 영역 | 해야 할 일 |
|---|---|
| 화면 | SDK 설치, 결제 요청 데이터 생성, 결제 이벤트 처리, 결과 화면 표시 |
| 서버 | API 인증, 주문 생성, 결제 조회·검증, 주문 상태 저장, 취소·환불 처리, 웹훅 수신 |
| Bootpay 관리자 | 프로젝트 생성, PG 활성화, 결제수단 설정, Sandbox 설정, 웹훅 URL 등록 |
화면에서는 결제를 시작해요. 서버에서는 결제 결과를 확인하고 주문 상태를 저장해요. Bootpay 관리자에서는 결제수단과 운영 환경을 맞춰요.
어떤 결제 상품부터 볼까
자세한 비교는 결제 상품 둘러보기에서 확인해요. 여기서는 첫 선택만 빠르게 잡으면 돼요.
| 상황 | 먼저 볼 문서 | 구현 포인트 |
|---|---|---|
| 버튼을 누르면 PG 결제창을 열고 단건 결제를 받는다 | 결제창 | 결제창 실행 → 서버 검증 → 주문 확정 |
| 주문서 안에 결제수단 선택 UI를 보여준다 | 결제위젯 | 위젯 렌더링 → 결제 요청 → 서버 검증 |
| 로그인 회원이 저장된 결제수단으로 다시 결제한다 | 브랜드페이 | user_token 발급 → 결제위젯에 전달 |
| 결제수단을 저장해 두고 서버가 원하는 시점에 청구한다 | 자동결제 | 빌링키 발급·저장 → 서버 청구 |
| 정해진 미래 시점에 한 번 결제를 실행한다 | 예약결제 | 빌링키 저장 → 예약 등록 → 웹훅 처리 |
처음이라면 결제창 또는 결제위젯으로 단건 결제를 먼저 구현해요. 그다음 재결제를 줄여야 하면 브랜드페이, 반복 청구가 필요하면 자동결제, 미래 시점 청구가 필요하면 예약결제로 확장해요.
개발 전에 정할 것
구현을 시작하기 전에 아래 값을 먼저 정하면 연동이 빨라져요.
| 항목 | 예시 |
|---|---|
| 사용할 상품 | 결제창, 결제위젯, 브랜드페이, 자동결제, 예약결제 |
| 클라이언트 플랫폼 | Web, iOS, Android, Flutter, React Native |
| 서버 언어 | Node.js, Python, Java, PHP, Ruby, Go, .NET |
| 승인·검증 방식 | 서버 승인 가능 여부, 결제 완료 후 검증 기준 |
| 테스트 환경 | Sandbox 사용 여부 |
| 결제수단 | 카드, 계좌이체, 가상계좌, 간편결제 |
| 주문 식별자 | 서비스 내부 주문 ID |
| 서버 확인 기준 | 주문 금액, 재고, 쿠폰, 회원 권한, 결제 상태 |
| 웹훅 URL | 결제 완료, 취소, 입금 상태를 받을 서버 엔드포인트 |
이 값이 정리되어 있으면 SDK 설치 이후 바로 결제 요청과 서버 검증 흐름을 구현할 수 있어요.
AI로 시작한다면
Claude Code, Cursor, Codex 같은 AI 코딩 도구를 쓴다면 Bootpay MCP 저장소를 같이 넘기면서 MCP 설치까지 시켜요.
https://github.com/bootpay/bootpay-mcp 참조해서 mcp 설치해주고, 결제 연동해줘.AI는 MCP 를 붙인 뒤 문서와 예제 코드를 읽고 현재 프로젝트에 맞는 결제창·결제위젯·서버 검증 코드를 만들 수 있어요. 자세한 내용은 AI 연동 가이드에서 확인해요.
커머스 SDK를 찾고 있다면
이 문서의 범위는 결제 SDK예요. 체크아웃, 주문, 카탈로그, 고객, 구독, 마켓플레이스까지 묶어서 쓰는 독립몰 시나리오는 Bootpay 커머스 SDK에서 따로 다뤄요.
| 상황 | 가야 할 문서 |
|---|---|
| 결제창·결제위젯·브랜드페이·자동결제·예약결제만 붙인다 | 이 문서 (결제 SDK) |
| 주문서·체크아웃·주문 상태·정산까지 SDK로 묶는다 | 커머스 시작하기 |
| 회차·계약·해지가 있는 구독을 운영한다 | 커머스 구독 |
| 결제 링크 한 줄로 받는다 | 링크페이 |
| 판매자·정산까지 다루는 마켓플레이스를 만든다 | 마켓플레이스 |
커머스 SDK는 결제 SDK 위에 주문·상품·고객 추상화를 얹은 형태예요. 결제 연동을 먼저 붙인 뒤 커머스 흐름을 그 위에 올리면 돼요.