Version 2
새로 나온
AI 도구로 결제 연동하기
Cursor, Windsurf, Claude Desktop 등 다양한 AI 도구를 활용해서 결제 연동을 쉽게 시작해보세요.
AI 도구와 함께 개발하면 결제 연동 속도를 크게 높일 수 있어요. 토스페이먼츠가 AI 도구를 위해 제공하는 자원과 활용 방법을 알려드릴게요.
AI를 위한 토스페이먼츠 자원
토스페이먼츠는 AI 도구가 결제 연동을 더 잘 이해하도록 3가지를 제공하고 있어요.
LLM Quick Reference
LLM Quick Reference는 토스페이먼츠 결제 연동에 필요한 핵심을 한 페이지에 압축한 LLM 컨텍스트 페이지예요. 결제 흐름 모델·결정 룰·시나리오 진입점·자주 틀리는 패턴이 정리되어 있어서 AI가 첫 코드를 더 빠르고 정확하게 작성할 수 있어요.
활용 방법
- AI 채팅에 페이지 URL을 공유하거나 페이지 내용을 컨텍스트로 첨부해보세요.
- "이 페이지 참고해서 결제 연동 코드 작성해줘"처럼 명시적으로 활용을 요청하면 더 안정적이에요.
- 토큰 효율을 위해 본문이 영어로 작성되어 있어요. 디테일이 필요하면 아래 MCP 서버나 llms.txt를 함께 사용하세요.
MCP 서버 활용하기
Model Context Protocol(이하 MCP)은 AI 모델이 다양한 상황과 맥락을 잘 이해하도록 돕기 위해 Anthropic이 정의한 표준이에요. 문제 상황에 적합한 MCP 서버를 활용하면 AI가 더 정확한 답변을 줄 수 있어요.
토스페이먼츠 MCP 서버를 설치하면 AI 도구가 토스페이먼츠 docs를 직접 검색해서 답변해요. 아래 JSON 설정을 추가하면 AI 도구와 MCP 서버가 연결돼요.
MCP 서버 설치하기
사용 중인 AI 도구에서 MCP 서버를 연결해보세요. 자동 설치 deeplink를 지원하는 도구는 클릭 한 번으로 설정돼요. 그 외에는 위 mcp.json 내용을 아래 경로에 추가하세요. (Codex는 TOML 형식이라 변환이 필요해요.)
| AI 도구 | 설치 경로 | 자동 설치 | 공식 가이드 |
|---|---|---|---|
| Cursor | ~/.cursor/mcp.json | 설치 | ↗ |
| VS Code | .vscode/mcp.json | 설치 | ↗ |
| Claude Code | .mcp.json (프로젝트 루트) 또는 ~/.claude.json | - | ↗ |
| Claude Desktop | claude_desktop_config.json | - | ↗ |
| Codex | ~/.codex/config.toml | - | ↗ |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | - | ↗ |
MCP 서버가 잘 연결되지 않을 때
- AI 도구의 MCP 설정 화면에서
tosspayments-integration-guide서버가 활성 상태인지 확인하세요. npx명령이 실행 가능한 환경인지(Node.js 설치 여부) 확인하세요. 회사 네트워크에서는 npm 레지스트리 접근이 차단될 수 있어요.- AI가 MCP 도구를 사용하지 않는 것 같다면 "토스페이먼츠 MCP를 사용해서 답변해줘"처럼 명시적으로 도구 사용을 요청해보세요.
MCP 서버가 제공하는 도구
| 도구 | 사용자 관점에서 동작 |
|---|---|
get-v2-documents | "결제위젯 코드 짜줘" 등 버전을 명시하지 않은 질문에 → AI가 V2 문서를 자동으로 검색해요 (기본 동작) |
get-v1-documents | "V1으로 작성해줘" 등 V1을 명시한 질문에 → AI가 V1 문서를 자동으로 검색해요 |
get-glossary-documents | "가상계좌 입금 정책 알려줘", "거래·정산 용어 차이 비교해줘" 등 결제수단·용어 관련 질문에 → AI가 결제 용어집(glossary) 문서를 자동으로 조회해요 |
document-by-id | 특정 페이지 디테일이 필요할 때 → AI가 문서 ID로 원본 전체를 조회해요 |
llms.txt
llms.txt는 LLM이 웹사이트 정보를 효과적으로 탐색하도록 돕는 표준 파일이에요. 토스페이먼츠 docs 인덱스가 LLM이 읽기 좋은 형태로 정리되어 있어서, AI 도구가 이 파일을 보고 정확한 페이지를 찾아갈 수 있어요.
토스페이먼츠 llms.txt 주소는 https://docs.tosspayments.com/llms.txt예요.
활용 방법
- AI 채팅에 "이 llms.txt 참고해서 답변해줘" 식으로 프롬프트에 첨부해보세요.
- 일부 AI 도구는 자동으로 llms.txt를 인식해요. (예: Cursor, Claude.ai)
- 결제수단별 디테일이 필요할 때 llms.txt를 참고하라고 명시하면 더 정확한 답변을 받을 수 있어요.
llms.txt 표준에 대해 자세히 알고 싶다면 llmstxt.org를 방문해보세요.
LLM에 질문하기
AI 도구에 자원을 연결한 뒤에 다양한 질문을 채팅으로 할 수 있어요. AI 답변이 이해되지 않거나 잘못된 경우 토스페이먼츠 개발자 커뮤니티로 알려주세요.
활용 예시
코드 생성
- "V2 SDK로 주문서 안에 결제위젯을 삽입하는 코드를 작성해줘"
- "결제 승인 요청하는 Node.js 서버 코드를 작성해줘"
- "가상계좌 발급 후 입금 콜백을 처리하는 코드를 작성해줘"
- "구독 결제(빌링) 흐름을 처음부터 끝까지 만들어줘"
에러 디버깅
- "결제 승인 API에서
NOT_MATCHES_REQUESTED_AMOUNT에러가 나와요. 원인이랑 해결법 알려줘" - "결제창에서
INVALID_REQUEST에러가 뜨는데 어떻게 해결하지?"
도큐먼트 조회
- "토스페이먼츠 빌링 API의 요청 바디 필드를 모두 알려줘"
- "결제수단별 취소 정책 차이를 표로 비교해줘"
추가 Tip
페이지 내용을 markdown으로 가져오면 외부 AI 도구에 붙여넣어 질문할 때 페이지의 맥락(결제 흐름, 정책, 코드 예시 등)을 그대로 전달할 수 있어서 더 정확한 답변을 받을 수 있어요. 두 가지 방법이 있어요.
페이지 markdown 원본 접근
모든 docs 페이지는 URL 끝에 .md를 붙이면 markdown 원본을 받을 수 있어요. AI 도구의 컨텍스트로 직접 전달할 때 편리하고, HTML 파싱이 필요 없어 토큰 효율도 좋아요. 탭에 숨겨진 콘텐츠도 모두 노출돼요.
예시:
https://docs.tosspayments.com/reference.md— 코어 API 레퍼런스https://docs.tosspayments.com/guides/v2/payment-widget.md— 결제위젯 가이드https://docs.tosspayments.com/guides/v2/get-started/llms-guide.md— 이 페이지
llms.txt에 명시된 페이지들도 모두 이 형식으로 가져갈 수 있어요.
Markdown으로 복사하기
개발자 문서 페이지 상단의 'Markdown으로 복사' 버튼으로 페이지 내용을 markdown 형식으로 클립보드에 즉시 복사할 수 있어요. 페이지를 보면서 AI 도구에 바로 붙여넣을 때 편리해요.
