결제위젯(결제창형) 연동하기

결제위젯(결제창형)을 연동하는 방법이에요. 구매자가 결제하기 버튼을 누르면 결제창이 열리고, 결제 결과를 리다이렉트 URL과 서버 승인 API로 처리해요.

개발자센터의 API 키 메뉴에서 결제위젯 연동 키를 확인하세요. 테스트 키와 라이브 키의 차이점도 함께 확인하세요.

먼저 주문서 페이지에 결제창형 결제 요청을 연결할게요. 아래 코드는 주문서 페이지의 예시에요.

스크립트 태그 또는 패키지 매니저로 토스페이먼츠 SDK를 설치하고, 클라이언트 키로 SDK를 초기화하세요. 다음, widgets() 메서드로 결제위젯 인스턴스를 생성하세요. 아래 코드에서는 widgets라는 인스턴스를 생성했어요.

그럼 이제 결제창을 띄울 준비가 됐어요. widgets.requestPaymentWindow(결제 정보, 위젯UI 정보) 메서드를 호출하면 결제 요청이 시작되고, 결제창이 열려요.

위 코드를 실행한 다음 결제하기 버튼을 누르면 결제창이 열려요. 테스트 키를 사용하면 실제 결제되지 않으니 안심하고 테스트해보세요.

결제위젯 결제창형을 띄우는 메서드예요. 결제창을 띄우려면 파라미터에 결제 요청 정보와 결제 UI 설정 정보를 입력해야 해요.

1️⃣ 결제 요청 정보를 첫 번째 파라미터로 추가하세요. amount, orderId, orderName, successUrl, failUrl처럼 결제 요청에 필요한 값을 넣어요.

2️⃣ 결제 UI 설정 정보를 두 번째 파라미터로 추가하세요. variantKey.paymentMethod, variantKey.agreement를 넣어서 어떤 결제 UI를 사용할지 지정해요.

3️⃣ 결제수단은 직접 파라미터로 선택하지 않아요. 노출되는 결제수단은 결제위젯 어드민 설정과 variantKey에 따라 결정돼요. 자세한 선택 옵션은 SDK 레퍼런스를 참고하세요.

결제창에서 구매자의 결제수단을 인증하는데요. 인증 결과는 리다이렉트 URL로 확인할 수 있어요. 결제 인증이 성공했다면 성공 리다이렉트 URL(successUrl)의 쿼리 파라미터로 결제 정보를 확인하고 검증해주세요. 인증이 실패했다면 이동한 실패 리다이렉트 URL(failUrl)의 쿼리 파라미터로 에러를 확인해주세요.

성공 리다이렉트 URL에는 아래 쿼리 파라미터가 추가돼요. 쿼리 파라미터의 amount 값과 setAmount()의 amount 파라미터의 값이 같은지 반드시 확인하세요. 클라이언트에서 결제 금액을 조작하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요.

일반결제 및 해외 간편결제의 paymentType은 NORMAL입니다. 브랜드페이 결제의 paymentType은 BRANDPAY입니다.

실패 리다이렉트 URL에는 아래 쿼리 파라미터가 추가돼요.쿼리 파라미터로 돌아오는 에러 코드, 메시지를 확인하고 필요한 로직을 구현해주세요.

리다이렉트 성공 후 서버에서 결제 승인 API를 호출하세요. 인증 헤더는 시크릿 키 기반 Basic 인증을 사용해요.

결제 승인 API의 결과로 HTTP 200 OK와 함께 Payment 객체가 돌아오면 결제가 정상적으로 완료됐어요.

Payment 객체에 구매자가 선택한 결제수단 정보가 있는지 확인하세요. 카드를 선택해서 결제했다면 아래와 같이 card 필드에 카드 정보를 확인할 수 있어요. 간편결제를 선택했다면 응답이 조금씩 바뀌는데요. 자세한 내용은 간편결제 응답 확인 가이드를 참고하세요.

결제 승인에 실패하면 HTTP 4XX 또는 5XX 코드와 에러 객체를 받아요. 결제 승인의 전체 오류 목록은 에러 코드를 참고하세요. 테스트 환경에서 결제 승인 실패를 재현해보고 싶다면 토스페이먼츠 API 테스트 헤더를 사용해보세요.