LLM Quick Reference: AI 에이전트를 위한 토스페이먼츠 V2 결제 연동 퀵레퍼런스

AI Workflow & Decision Rules

AI 도구를 통해 코드를 생성할 때 권장하는 단계별 워크플로우입니다:

1. 정신 모델(Mental Model) 확립: 결제 흐름 모델(클라이언트 인증 → 서버 최종 승인) 파악.
2. 결정(Decision): SDK 버전(V2 기본) → 제품 유형(주문서형 기본) → 결제 시나리오.
3. 문서 탐색: 세부 사항이 필요할 때 llms.txt를 먼저 조회하여 정확한 가이드 페이지로 이동.
4. 코드 생성: V2 최신 표준 API 규격에 맞춰 작성.
5. 검증(Validation): 공통 실수(Common Mistakes) 목록을 대조하여 검증.

Server-authoritative 원칙: 클라이언트는 결제 인증만 요청할 수 있으며, 결제 금액 검증 및 최종 승인(Confirm), 환불, 웹훅 재조회는 반드시 머천트 서버에서 Secret Key를 통해 실행해야 합니다. 클라이언트가 전달한 결제 상태(금액, 상태값 등)를 절대 신뢰하지 마세요.

1. Payment Flow Model (결제 흐름 모델)

토스페이먼츠는 클라이언트(브라우저) / 머천트 서버 / 토스페이먼츠 3개 주체로 동작합니다. 일반 단건 결제(카드, 계좌이체, 간편결제)의 기본 흐름은 다음과 같습니다.

1. 클라이언트 → 머천트 서버: 주문 생성 요청
2. 머천트 서버 → 클라이언트: orderId, amount 반환
3. 클라이언트 → 토스페이먼츠: requestPayment(amount) 호출 (사용자 인증 진행)
4. 토스페이먼츠 → 클라이언트: 인증 결과 반환 후 successUrl 리다이렉트 (paymentKey, orderId, amount)
5. 머천트 서버: 요청 금액과 successUrl의 amount 일치 여부 검증 (필수)
6. 머천트 서버 → 토스페이먼츠: 결제 승인 API 호출 (/v1/payments/confirm with Secret Key)
7. 머천트 서버: 결제 결과 저장 및 주문 완료 처리
8. 토스페이먼츠 → 머천트 서버: (선택 사항) 웹훅 이벤트 수신

2. Critical Guardrails (필수 보안 원칙 4가지)

2.1 Secret Key는 서버 전용, Client Key는 브라우저 전용

• Secret Key ((test|live)_sk_*): 머천트 서버에서만 사용. 프론트엔드 코드, 깃허브 커밋, 클라이언트 응답 노출 절대 금지.
• Client Key ((test|live)_ck_*): 브라우저 클라이언트 JS SDK 초기화 시 사용.

2.2 결제 승인 전 서버 측 금액(Amount) 필수 검증

클라이언트 SDK의 requestPayment는 브라우저 콘솔에서 임의로 조작(예: 50,000원 주문을 100원으로 변조)될 수 있습니다. successUrl로 전달받은 amount가 실제 머천트 서버 DB에 기록된 주문 금액과 완벽히 일치하는지 반드시 검증한 후에만 결제 승인 API를 호출해야 합니다.

2.3 Authorization 헤더는 Basic base64(SECRET_KEY:)

Secret Key 뒤에 콜론(:)을 반드시 붙인 후 Base64 인코딩해야 합니다. 콜론 누락은 가장 흔한 인증 오류 원인입니다.

2.4 임의의 필드 위조(Hallucination) 금지

다른 PG사(Stripe, KCP 등)의 필드명을 추측해서 쓰거나 문서에 없는 필드명을 임의 생성하지 마세요. 불확실한 필드는 llms.txt를 통해 확인하세요.

3. SDK Version Selection (V2 기본 권장)

별도의 구버전 요구가 없는 한 항상 V2 SDK를 선택합니다. V1과 V2를 혼용하여 호출하지 마세요.

// V2 SDK 초기화 및 메서드 분기
const tossPayments = TossPayments(clientKey);

const widgets = tossPayments.widgets({ customerKey });            // 주문서형 / 결제창형 결제
const payment = tossPayments.payment({ customerKey });            // 자체창 / 구버전 결제창
const brandpay = tossPayments.brandpay({ customerKey, redirectUrl }); // 브랜드페이

4. Product Selection (제품 선택 및 2026 명칭 변경 매핑)

2026 명칭 변경 대조표

• 결제위젯 → 주문서형 결제 / 결제창형 결제
• 통합결제창 → 결제창(구버전)

5. Scenario Entry Points (시나리오별 진입점)

공통 식별자 및 데이터 타입

• customerKey: 2~300자, 영문/숫자/특수문자(-, _, =, ., @) 포함 필수. UUID 권장. 비회원은 ANONYMOUS 사용.
• orderId: 6~64자, 영문/숫자/-_ 조합의 고유 ID.
• amount: V2 SDK에서는 객체 형태 { value: 50000, currency: "KRW" }로 전달.

공통 결제 승인 API (서버 호출)

curl -X POST https://api.tosspayments.com/v1/payments/confirm   -H 'Authorization: Basic {base64(secretKey:)}'   -H 'Content-Type: application/json'   -H 'Idempotency-Key: {UUID_V4}'   -d '{"paymentKey":"...","orderId":"...","amount":50000}'

6. Common Mistakes (자주 발생하는 오류 패턴)

7. Reference & Meta Resources

• llms.txt (전체 문서 인덱스): https://docs.tosspayments.com/llms.txt
• MCP 서버 가이드: AI 도구로 결제 연동하기 (MCP 설정)
• 토스페이먼츠 공식 개발자 센터: https://docs.tosspayments.com