결제위젯 클라이언트 에러 가이드

2024년 5월 2일 ・ 읽는 시간 5분

개발을 하다보면 문서에 나오는 기본 시나리오대로, 해피 패스로 한 번에 연동하기란 정말 어렵죠. 대부분의 개발자는 디버깅에 고생하면서 연동을 마무리하게 돼요. 이번 가이드는 그런 고생을 덜기 위해 결제 연동하기 가이드를 기반으로 클라이언트 연동 단계에서 만날 수 있는 에러와 대응 방법을 알려드릴게요.

먼저, 이 가이드를 보기 전에 다음 세 가지를 확인해 주세요.

✅ API 키를 결제위젯 연동 키로 사용해야 해요. 결제위젯 연동 키는 토스페이먼츠 전자결제 신청 이후에만 확인할 수 있어요. 신청 전에는 문서에 있는 테스트 키만 사용할 수 있어요.

✅ 사용하는 API 키의 클라이언트 키-시크릿 키 쌍이 맞아야 해요.

✅ 결제 UI가 렌더된 후에 결제를 요청해야 돼요.

혹시 해결됐나요? 그럼 나머지 가이드는 보지 않아도 괜찮아요. 아직 문제가 해결되지 않았다면 같이 살펴봐요!

결제위젯을 사용하기 위해 SDK를 초기화 하려면 클라이언트 키, customerKey를 올바르게 넣어야 해요.

올바른 클라이언트 키를 넣었는지 확인해야 해요. 임의의 값을 넣으면 안돼요. 초기화를 위해서는 ‘내 프로젝트’임을 알려줄 수 있는 정보가 필요해요. 그래서 가입한 내 계정에 발급된 클라이언트 키를 사용해야 해요. 개발자센터에서 결제위젯 연동 키 > 클라이언트 키가 맞는지 확인하세요. 결제위젯을 연동해야 하기 때문에 ‘결제위젯 연동 키’를 사용해야 해요. 'API 개별 연동 키'는 사용하지 마세요.

customerKey 형식이 잘못됐어요. 초기화를 위해서는 구매자를 식별하는 데 사용되는 customerKey를 넣어줘야 해요. 이 값은 각 구매자에게 고유한 식별 번호를 부여해요. 구매자를 식별하는 값이니 안전하게 관리해야겠죠. 따라서 customerKey는 영문 대소문자, 숫자, 특수문자 -, *, =, ., @로 2자 이상 255자 이하로, 혹은 UUID 형식으로 만들어 주세요.

초기화 코드는 다음과 같이 작성해 주세요.

결제 UI를 렌더하는 메서드를 실행하려면 아까 만든 결제 영역의 CSS 선택자와 결제 금액을 메서드의 파라미터로 넣어야 해요.

만들었던 결제 영역의 CSS 선택자를 첫 번째 파라미터로 넣어야 실행돼요.

선택 파라미터인 variantKey는 결제 UI를 여러 개 만들 때 각각을 구분하는 역할을 해요. 만약 어드민에서 결제 UI를 여러 개 만들었다면 이 값이 비어있으면 안돼요. DEFAULT라는 variantKey를 사용해서 기본 결제 UI를 렌더링 하거나, 설정한 결제 UI의 variantKey를 넣어주세요.

개발에 사용하고 있는 브라우저를 확인해요. 애플페이는 iPhone 및 Mac Safari 에서만 노출돼요. 어드민 페이지에서 예상 이미지를 확인할 수 있어요.

• UNAUTHORIZED_KEY 에러가 난다면 클라이언트 키를 다시 확인하세요.
• NOT_REGISTERED_PAYMENT_WIDGET 에러가 난다면 어드민에서 결제 UI를 추가하세요. 결제 UI가 생성되지 않았을 때 발생하는 에러입니다.
• IE 환경은 지원하지 않습니다.

결제 UI가 렌더링되기 전에 결제를 요청했기 때문이에요. 반드시 결제 UI가 렌더링된 이후에 결제 요청 메서드를 호출하세요. 만약 UI가 렌더링됐는지 확인한 뒤 메서드를 실행하려면 ready 이벤트를 추가하세요.

아직 결제 요청 중이에요. successUrl, failUrl 페이지에서 요청 결과를 확인한 뒤, 결제 승인 API까지 호출해야 결제가 완료돼요. 결제 승인 API를 호출하는 코드가 있는지 확인하세요.

만약 iframe을 사용하고 있다면 요청 결과 페이지(successUrl, failUrl)로 이동할 수 없어요.

• 앱으로 개발했는데, 카드사 앱으로 이동하지 않는다면 카드사 앱스킴을 등록해야 돼요. 자세한 내용은 웹뷰 가이드에서 확인하세요.

• iframe을 이용한 결제창 팝업 형태는 PC에서만 제공해요.

failUrl의 쿼리 파라미터에 있는 에러 코드와 메시지를 확인해 보세요.

• PAY_PROCESS_CANCELED

  • 구매자에 의해 결제가 취소된 거에요. 결제 과정이 중단된 것이라서 failUrl로 orderId가 전달되지 않아요. 구매 고객에게 안내해 주세요.

• PAY_PROCESS_ABORTED

  • 상점 계약 또는 원천사 문제가 있을 때 발생해요. 토스페이먼츠와 계약, 카드사 심사 등 모든 계약 과정이 완료됐는지 확인하세요. 계약 상태는 1544-7772로 문의해주세요. 계약이 모두 완료됐어도 테스트 키와 라이브 키가 동기화 안 되어있을 수도 있습니다. 라이브 키로 테스트하거나 디스코드에서 실시간 문의를 남겨주세요.
  • 테스트 환경에서 간편결제는 토스페이, 네이버페이, 카카오페이만 지원해요. 토스페이, 네이버페이만 모든 테스트 키로 연동할 수 있습니다. 카카오페이는 계약 후 발급받는 내 테스트 키로 연동할 수 있습니다. 페이코 등 기타 간편결제는 라이브 키로 테스트하세요.
  • 인증실패 등 원천사 에러 메시지를 받았다면, PG와 관련없는 에러입니다. 원천사에 문의해주세요.

• REJECT_CARD_COMPANY

  • 구매자가 입력한 카드 정보에 문제가 있을 때 발생해요. 원인은 비밀번호 오류, 한도 초과, 포인트 부족 등 다양합니다. 오류 메시지를 확인하고 구매 고객에게 안내해 주세요.

✅ 결제위젯 초기화가 실패할 때는 클라이언트 키, customerKey를 확인해 보세요.

✅ 결제 UI 렌더가 실패할 때는 renderPaymentMethods()의 파라미터를 확인해 보세요.

✅ 결제 요청에 실패했다면 결제 UI가 렌더된 상태인지 확인해 보세요.

아직도 에러가 해결되지 않았나요? 그렇다면 디스코드에서 실시간 문의를 남겨주세요.

서버 에러는 에러 코드와 API 로그에서 이유와 해결 방법을 알 수 있어요.

📍 함께 읽어보기

• SDK 에러 코드 확인하기