토스페이먼츠 결제위젯 연동 순서와 테스트 결제 방법

최근 전자상거래가 활발해지면서, 온라인 결제를 위한 위젯 연동의 중요성이 커지고 있습니다. 2025년 기준으로 국내 온라인 결제 시장의 성장률이 급격히 증가하면서 결제 시스템의 안정성과 편의성이 한층 강조되고 있습니다. 이 블로그 글에서는 토스페이먼츠의 결제위젯 연동과 그 테스트 방법에 대해 설명합니다. 특히, 결제 승인 API의 필요성과 테스트 결제의 실제 금액 차감 여부에 대해 알아보겠습니다.

결제 시스템을 구축해야 하는 상황이라면, 아래의 자가진단 문구를 참고하세요. “토스페이먼츠 결제위젯을 제대로 연동하고 테스트 결제를 안전하게 진행했나요?” 이 질문에 대해 답을 찾아보겠습니다.

결제위젯 연동의 시작, 준비할 것

결제위젯 연동의 첫 단계는 토스페이먼츠 SDK 설치입니다. 두 가지 방법으로 설치할 수 있는데, 하나는 스크립트 태그를 이용하는 것이고, 다른 하나는 npm을 이용하는 것입니다. 설치 후 클라이언트 키를 사용하여 TossPayments()를 초기화하고, widgets()를 사용해 주문서형 결제 인스턴스를 만듭니다. 이 과정에서 회원과 비회원 구분도 필수적입니다. 회원은 고유 customerKey를 사용하고, 비회원은 ANONYMOUS로 설정합니다.

금액 설정은 setAmount() 함수를 통해 진행합니다. 결제 금액이 설정되면, 결제 UI와 이용약관 UI, 결제 버튼을 위한 div 영역을 정의한 후 renderPaymentMethods()와 renderAgreement()를 이용해 해당 UI 요소들을 렌더링합니다. 이 작업은 비동기로 진행되므로 화면 출력 이후에 확인할 필요가 있습니다.

마지막으로 결제 요청 전, orderId와 결제 금액(amount)을 서버에 임시 저장해야만 합니다. 이러한 절차를 통해 결제 프로세스의 일관성을 유지하고, 데이터를 안전하게 관리할 수 있습니다. 또한, 이후 승인 API 호출에 대비할 수 있습니다.

결제 요청과 이후 확인할 것

결제 요청이 정상적으로 이루어지고 나면, 리다이렉트 처리 단계가 시작됩니다. 사용자 인증에 성공하면, 설정된 successUrl로 이동하며, 실패 시에는 failUrl로 이동합니다. successUrl로 이동 시, 여러 쿼리 파라미터가 부여됩니다: paymentKey, orderId, amount, paymentType 등이 그렇습니다. 여기서 중요한 것은 amount가 setAmount()로 설정한 값과 일치하는지 반드시 확인해야 한다는 것입니다. 만약 다르다면, 결제가 무효화되므로 즉시 처리해야 합니다.

리다이렉트 과정에서 파라미터 확인을 마친 후에는, 결제 승인 API를 호출하게 됩니다. 시크릿 키를 이용해 인증을 진행하며, 반드시 서버에서 이루어져야 합니다. 이때 주의할 점은 승인 API를 10분 내에 호출해야 결제 승인이 가능하다는 것입니다.

만약 승인 과정에서 오류가 발생할 경우, HTTP 코드와 함께 에러 객체가 회신될 수 있습니다. 이러한 오류는 성공적인 결과를 보장하지 않으므로, 별도의 오류 처리 로직을 반드시 준비해야 합니다.

테스트 결제의 절차, 가상의 결제

테스트 결제는 실제 금액이 차감되지 않는 가상 환경에서 이루어집니다. 테스트 키로 연동된 상태에서 결제 수단을 선택하고 결제 버튼을 누르면 테스트 결제가 진행됩니다. 결제 내역은 개발자센터의 테스트 결제내역에서 확인이 가능합니다. 이러한 테스트를 통해 실 결제 환경에서 발생할 수 있는 오류를 사전에 잡을 수 있다는 점이 매우 유리합니다.

가상계좌의 경우, 일반적인 테스트 키로는 테스트가 불가능합니다. 따라서, 전자결제 계약 후 발급된 상점의 API 테스트 키로 진행해야 합니다. 가상계좌 입금 처리는 개발자센터를 통해 별도로 수행할 수 있습니다.

이와 같은 테스트 결제 환경은 결제 시스템을 초기 설정하고 안정화하는 데 큰 도움이 됩니다. 실제 연동 전에 여러 번의 테스트를 통해 결제 흐름이 올바르게 작동하는지 확인하는 것은 필수적입니다.

결제 승인 API, 이를 꼭 호출해야 하는 이유

결제 승인 API는 결제 과정을 최종적으로 종료시키는 중요한 역할을 합니다. 결제 요청만으로는 사용자의 비용이 실질적으로 청구되지 않기 때문에, 결제 승인 API 호출이 필수적입니다. 이 절차가 완료되어야 사용자의 결제 정보가 확정되고 거래가 완료됩니다.

API 호출 시에는 시크릿 키를 이용해 진행합니다. 특히, 이 과정에서 시크릿 키는 서버에서만 사용되어야 하며, 클라이언트나 외부에 노출되어서는 안 됩니다. 기본 인증 헤더를 만들 때, 시크릿 키 뒤에 콜론을 붙여 base64로 인코딩하는 과정을 통해 보안을 강화합니다.

마지막으로, 결제 승인 API의 호출은 결제 요청 후 10분 내에 반드시 완료되어야 합니다. 이 단계가 지연되면 거래 데이터가 유실될 위험이 있습니다. 시간 안에 처리할 수 있도록 시스템을 설계하는 것이 중요합니다.

이것만은 주의하세요

실무에서 가장 흔하게 발생하는 실수 중 하나는 시크릿 키의 노출입니다. 시크릿 키는 반드시 보안된 서버에만 저장하고, 외부 노출을 엄격히 차단해야 합니다. 또한, 결제 승인 API 호출을 잊는 경우도 빈번합니다. 이 호출 없이 결제가 완료되지 않으므로 반드시 실행해야 합니다.

결제 금액이 일치하는지 확인하지 않아 문제가 발생할 수 있습니다. 리다이렉트 후 각 파라미터를 정확히 체크하고 일치 여부를 확인하는 습관을 갖는 것이 좋습니다. 이런 작은 실수가 큰 문제로 발전할 수 있음을 기억하세요.