가상계좌 API로 연동하기

✅ 가상계좌 발급 API로 구매자가 원하는 은행의 가상계좌를 발급받으세요. (서버 투 서버)

✅ 발급한 계좌에 주문 금액이 입금되면 결제가 완료됩니다. 입금 통보는 웹훅으로 확인할 수 있습니다.

결제 정보와 구매자가 입금하려는 은행 정보를 담아 가상계좌 발급 요청 API를 호출합니다.

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

두 파라미터 중 하나만 선택해서 사용해야 합니다. 두 파라미터는 사용 기한을 발급 시점으로부터 상대적으로 설정할 지, 특정 시점으로 설정할 지에 차이가 있습니다.

예를 들어 가상계좌 입금 기한을 발급 시점부터 하루로 설정하고 싶다면, 아래와 같이 validHours 파라미터를 24로 설정해서 가상계좌 발급 요청 API를 호출하세요.

• validHours number
  

  가상계좌 발급 시점으로부터 가상계좌가 유효한 시간입니다. 설정한 validHours 안에 구매자가 입금을 하지 않으면 주문은 취소됩니다. 설정할 수 있는 최대값은 2160시간(90일)입니다.

• dueDate number
  

  가상계좌 입금 기한입니다. dueDate이 지난 시점에 입금을 시도하면 실패합니다. 티켓 예매 등 주문 시간과 상관없이 정해진 시점까지 결제를 받아야 할 때도 사용할 수 있습니다. 설정할 수 있는 최대값은 결제 요청일로부터 90일입니다. yyyy-MM-dd'T'HH:mm:ss ISO 8601 형식을 사용합니다.

가상계좌 발급에 성공하면 HTTP 200 OK와 Payment 객체를 받습니다. 응답에는 virtualAccount 필드가 포함되어 있습니다. 가상계좌의 계좌번호, 은행, 입금기한 등 돌아온 정보를 구매자에게 안내해주세요.

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

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

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

가상계좌 결제는 환불할 결제수단이 미리 등록되어 있지 않습니다. 따라서 결제 취소 API를 요청할 때 아래와 같이 refundReceiveAccount를 설정해야 합니다. 은행명, 계좌번호, 예금주 이름으로 구성된 환불 계좌 정보입니다.

취소할 때는 예금주 이름을 정확히 설정하세요. 예금주 이름이 올바르지 않으면 정상적으로 환볼되지 않습니다.

결제가 취소되면 웹훅으로 아래와 같은 이벤트 본문이 돌아옵니다.