Claude Code 같은 AI 에이전트를 쓴다면, 채팅창에 이 한 줄이면 시작돼요.
https://github.com/bootpay/bootpay-mcp 참조해서 결제 연동해줘.Claude Code 같은 AI 에이전트에게 이렇게 던지면 Bootpay MCP의 문서와 예제를 읽고 결제창·결제위젯·서버 검증 코드까지 만들어줘요. 동작 원리와 직접 붙이는 순서가 궁금하면 아래를 이어서 읽어요.
Bootpay 결제 SDK로 웹·앱에 결제를 붙일 수 있어요. 처음부터 모든 기능을 다 볼 필요는 없어요. 먼저 단건 결제 하나를 성공시키고, 그 다음 결제수단·위젯·브랜드페이·자동결제·예약결제로 확장하면 돼요.
이 문서는 코드를 바로 쓰는 문서라기보다, 어떤 순서로 문서를 읽고 어떤 책임을 나눠야 하는지 잡는 입구예요.
처음 읽는 순서
처음 연동한다면 아래 순서로 보면 가장 덜 헷갈려요.
| 순서 | 볼 문서 | 여기서 결정할 것 |
|---|---|---|
| 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 제공 | 금액·상태·재고·쿠폰 확인 |
| 주문 저장 | 결제 결과 데이터 제공 | 주문 상태를 done 등으로 저장 |
| 웹훅 | 결제 완료, 취소, 입금 상태 알림 | 웹훅 수신, 중복 처리, 주문 상태 업데이트 |
| 취소·환불 | 취소 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 저장소를 같이 넘기면 좋아요.
https://github.com/bootpay/bootpay-mcp 참조해서 결제 연동해줘.AI는 문서와 예제 코드를 읽고 현재 프로젝트에 맞는 결제창·결제위젯·서버 검증 코드를 만들 수 있어요. 자세한 내용은 AI 연동 가이드에서 확인해요.
커머스 SDK를 찾고 있다면
이 문서의 범위는 결제 SDK예요. 체크아웃, 주문, 카탈로그, 고객, 구독, 마켓플레이스까지 묶어서 쓰는 독립몰 시나리오는 Bootpay 커머스 SDK에서 따로 다뤄요.
| 상황 | 가야 할 문서 |
|---|---|
| 결제창·결제위젯·브랜드페이·자동결제·예약결제만 붙인다 | 이 문서 (결제 SDK) |
| 주문서·체크아웃·주문 상태·정산까지 SDK로 묶는다 | 커머스 시작하기 |
| 회차·계약·해지가 있는 구독을 운영한다 | 커머스 구독 |
| 결제 링크 한 줄로 받는다 | 링크페이 |
| 판매자·정산까지 다루는 마켓플레이스를 만든다 | 마켓플레이스 |
커머스 SDK는 결제 SDK 위에 주문·상품·고객 추상화를 얹은 형태예요. 결제 연동을 먼저 붙인 뒤 커머스 흐름을 그 위에 올리면 돼요.