1. Toss Payments API 연동 중 마주친 문제들과 해결 방법
최근 DevMountain 프로젝트에서 Toss Payments를 연동하며 여러 문제와 상황들이 겹쳤다. 이에 대해 간단하게 정리해두고 다음에 비슷한 상황이 생기면 아래와 같은 방법으로 해결할 예정이다.
2. 연동 목표
• 사용자가 버튼 클릭 → 주문 생성 → Toss 결제창 호출
• orderId, amount, customerName, successUrl 등의 파라미터 포함
• 결제 성공 시 서버에 결과 저장3. API 호출 전 기본 설정
const tossPayments = window.TossPayments("test_ck_...");
tossPayments.requestPayment('카드', {
amount: 10000,
orderId: "ORDER_12345",
...
});✅ 요구 조건
Toss는 orderId에 다음 조건을 강제합니다:
• 영문 대소문자, 숫자, 특수문자(-, _)만 허용
• 길이: 6자 이상, 64자 이하
💀 문제 1: 숫자형 orderId로 인해 요청 실패
📌 에러 메시지
Uncaught (in promise) t: `orderId`는 영문 대소문자, 숫자, 특수문자(-, _) 만 허용합니다. 6자 이상 64자 이하여야 합니다.⚠️ 원인
• 백엔드에서 Long 타입의 order.getId()를 그대로 JSON으로 넘김 → 숫자형 ID가 들어감
• Toss는 순수 숫자만 있는 ID를 허용하지 않음
✅ 해결
// OrderResponseDto
public static OrderResponseDto from(Order order) {
return new OrderResponseDto("ORDER_" + order.getId(), ...);
}
→ orderId를 문자열로 가공하여 프론트에 전달하도록 변경
💀 문제 2: 클라이언트 키 작동 안함 오류
📌 에러 메시지
App.jsx:46 주문 생성 실패 ReferenceError: orderId is not defined at onClick ⚠️ 원인
• 공식 사이트에서 하라던 클라이언트 키로는 작동 안함 (버전마다 다른 키를 가지고 있으므로 업데이트가 안된 것 같음)
✅ 해결
• 상세하게 검색해서 최신 버전의 클라이언트 키를 찾음
🔍 그 외 여러 작은 생각해 둘 요소들
• Toss 테스트 키는 testck...로 시작함
• 실제 결제 요청은 반드시 successUrl, failUrl이 올바르게 설정되어야 정상 동작
• 프론트에서 Toss SDK가 로드되기 전에 requestPayment 호출 시 오류 발생하므로 useEffect로 스크립트 주입을 함.
4. 결론
Toss API는 사용법이 비교적 간단한 편이지만, 사소한 형식이나 파라미터 미스매치로 에러가 자주 발생합니다. 특히 orderId 포맷 요구사항은 반드시 지켜야 하며, 응답 구조를 프론트와 백엔드에서 일치시켜야 한다!
