가상계좌 결제창 연동하기

✅ 토스페이먼츠 가상계좌 결제창에서 가상계좌를 발급받고, 입금 결과를 웹훅으로 받을 수 있어요.

결제창은 API 개별 연동 키로 연동하세요.

토스페이먼츠에 회원가입하기 전이라면, 다음 문서 테스트 키로 연동할 수 있어요. 토스페이먼츠에 회원가입했다면, 로그인 후 내 테스트 키로 결제를 연동하고 개발자센터에서 테스트 결제내역을 확인하세요.

아래 예제 코드를 실행하면 다음과 같은 가상계좌 결제창을 띄울 수 있습니다. 실제로 결제되지 않으니 안심하세요.

가상계좌 입금 기한의 기본 값은 발급 시점으로부터 7일입니다. 입금 기한을 바꾸려면 validHours, dueDate 선택 파라미터를 사용하세요. 설정할 수 있는 최대 기한은 발급 시점으로부터 30일입니다. 입금 기한을 넘기면 발급된 가상계좌는 더 이상 사용할 수 없습니다.

두 파라미터 중 하나만 선택해서 사용해야 합니다. 두 파라미터는 사용 기한을 발급 시점으로부터 상대적으로 설정할 지, 특정 시점으로 설정할 지에 차이가 있습니다. 예를 들어 가상계좌 입금 기한을 발급시점부터 하루로 설정하고 싶다면, 위와 같이 validHours 파라미터를 24로 설정하세요.

• validHours number
  

  가상계좌가 유효한 시점을 시간 단위로 설정할 때 사용합니다. 예를 들어 가상계좌 발급 시점이 2022년 1월 1일 오전 1시(2022-01-01T01:00:00+09:00)이고, validHours를 120으로 설정하면 발급 후 120시간 뒤인 2022년 1월 5일 오전 1시 전까지 입금되어야 합니다.

• dueDate number
  

  입금 기한을 특정 시점으로 설정할 때 사용합니다. 예를 들어 가상계좌 발급 시점이 2022년 1월 1일 오전 1시(2022-01-01T01:00:00+09:00)이고, dueDate를 2022-01-10T01:00:00로 설정하면 2022년 1월 10일 오전 1시 전까지 입금되어야 합니다.

결제 요청이 성공하면 결제창을 열 때 설정한 결제 성공 페이지(successUrl)로 이동합니다.

결제 성공 페이지의 URL에는 paymentKey, orderId, amount 세 가지 쿼리 파라미터가 들어있습니다.

• paymentKey: 결제의 키값입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인에 사용됩니다.
• orderId: 주문번호입니다. 결제 요청에서 내 상점이 직접 생성한 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 orderId는 유지됩니다.
• amount: 결제할 금액입니다.

* 결제 요청이 실패하면 결제창을 열 때 설정한 결제 실패 페이지(failUrl)로 이동합니다. 결제 실패 URL을 살펴보세요.

결제 승인 API를 호출해서 마지막 단계를 완료합니다. 먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다.

시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. :을 빠트리지 않도록 주의하세요.

아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.

인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문도 추가하세요. 앞 단계에서 리다이렉트 URL로 받은 paymentKey, orderId, amount를 넣어주세요. 아래 예제 코드에는 내 테스트 결제의 paymentKey 값을 넣어 실행해주세요.

API 호출 결과로 HTTP 200 OK와 함께 Payment 객체가 돌아오면 가상계좌 발급 완료입니다. 응답에서 virtualAccount 필드를 확인하세요. 가상계좌의 계좌번호, 은행, 입금기한 등 정보를 구매자에게 안내해주세요.

가상계좌 결제는 발급된 계좌에 구매자가 입금한 시점에 결제가 됩니다. 직접 테스트 입금을 하고 비동기적으로 바뀌는 결제 상태는 웹훅으로 확인하세요. 금액이 입금되거나 결제가 취소되는 등 가상계좌 결제 상태가 바뀌면 등록된 웹훅 URL로 알림이 발송됩니다.

테스트 환경에서 발급된 계좌로 직접 입금할 수 없지만, 개발자센터의 테스트 거래내역 페이지에서 가장 오른쪽 칼럼의 입금처리・취소를 선택해보세요. 실제 동작과 동일하게 테스트 할 수 있습니다.

• 개발자센터의 웹훅 페이지에서 DEPOSIT_CALLBACK 웹훅을 등록하세요.
• 입금이 완료되면 결제 상태가 DONE으로 바뀌고 아래와 같은 이벤트 본문이 등록한 웹훅 URL로 전송됩니다.
• 이벤트 본문의 secret 값이 결제 승인 응답으로 돌아온 Payment 객체의 secret 값과 같은지 확인하세요. 값이 같다면 토스페이먼츠 서버에서 돌아온 올바른 요청입니다.