정의
가상계좌 결제는 토스페이먼츠가 은행으로부터 발급받아 보유하고 있는 각 은행별 가상계좌를 고객에게 발급하고 고객은 발급된 가상계좌로 거래 금액을 송금하여 결제를 완료하는 결제방식을 의미합니다. 주문자와 입금자가 달라도 입금할 수 있지만, 주문금액과 입금금액이 같아야 입금이 가능합니다. - [링크]
다른 말로는 무통장 입금이라고도 불립니다.
가상계좌는 고객에게 발급(활성화) 되지 않으면 해당 가상계좌 번호를 알고 있다고 해도 입금이 되지 않습니다. 가상계좌를 발급 요청 할 때 입금 마감시간을 정할 수 있어서 해당 시간이 지나면 발급된 가상계좌에 더 이상 입금이 불가능합니다. 반납된 가상계좌번호는 다시 토스페이먼츠의 가상계좌 Pool (발급되지 않은 상태의 가상계좌번호 리스트)에 들어가게 되고 이후 다른 가상계좌 결제 건이 요청되면 발급 될 수 있습니다. 즉, 개별적인 다른 거래 건으로 가상계좌를 요청했을 때 앞서 사용되었던 가상계좌번호가 재발급이 될 수 있습니다.
가상계좌는 발급 받을 때 입금 가능 금액을 명시해서 발급하게 되는데, 고객이 입금할 때 이 입금 가능 금액에 맞추어 한번에 입금을 하셔야 합니다. 다른 금액의 경우에는 입금 자체가 되지 않기 때문에 15000원 입금을 위해 10000원, 5000원 이렇게 2번 입금하는 것은 불가능합니다. 무조건 한번에 15000원을 입금해야 합니다.
가상계좌 결제의 특징
가상계좌 결제의 프로세스 중 다른 결제수단과 다른 가장 큰 특징은 결제 요청을 했을 때 실제 결제가 발생하지 않고 단순히 가상계좌만 발급된다는 점입니다. 카드나 휴대폰 등 다른 결제는 결제 요청 API 를 호출하면 그 응답으로 결제의 성공/실패 여부가 바로 전달되지만, 가상계좌는 결제요청 API 를 호출했을 때 그 결과로 가상계좌가 발급됩니다. 즉, 가상계좌 결제 flow 에서 구매자의 액션은 2가지 단계로 구분이 됩니다. 1번째는 가상계좌 결제 요청하여 계좌를 발급 받는 액션과, 2번째로 발급된 계좌에 입금을 하는 액션으로 나뉘게 됩니다.
가상계좌가 발급되면 초기 주문번호의 status 는 WAITING_FOR_DEPOSIT 이 됩니다. 그리고 실제 결제는 고객이 발급된 가상계좌에 정해진 금액을 입금해야 결제가 완료(status = DONE) 됩니다.
고객이 발급된 가상계좌에 언제 금액을 입금할지 PG사도 가맹점도 알 수가 없습니다. 이 때문에 가상계좌 발급요청시 입금 이벤트를 안내 받을 수 있는 가맹점 서버의 URL 을 전달해주어야 합니다. 이를 입금 통보 URL이라고 합니다. 입금이 되면 PG사는 은행으로 부터 입금 통지를 받게 되고, 수신한 입금 통지를 앞서 설정한 고객사 통보 수신 URL 로 계좌 상태(입금완료) 정보를 전달합니다. 가맹점에서는 이 이벤트 정보를 받아서 주문 건에 대해 결제 완료를 처리하고 서비스 또는 물품을 구매자에게 제공하면 됩니다. 입금이 완료 되어야 해당 주문번호의 status가 DONE 으로 변경된다는 사실이 다른 결제수단과의 차이점 입니다.
가상계좌 결제의 입금 처리 URL 설정
가상계좌에 고객이 입금을 하시게 되면
•
가상계좌 원천사(은행) → 토스페이먼츠 → 가맹점 순으로 입금이 되었다는 통보가 발생합니다.
즉 가상계좌 입금 통보는 토스페이먼츠 서버에서 가맹점 서버를 호출하는 방식으로 동작하므로, 가상계좌 입금 통보 URL 은 토스페이먼츠 서버에서 접속 가능한 public IP나 도메인을 사용하는 URL 이어야 합니다.
127.0.0.1, localhost, 그리고 내부망(10.x.x.x, 192.x.x.x, 172.x.x.x) IP 등 인터넷을 통해 접근이 불가능한 URL 은 토스페이먼츠 서버에서 호출이 불가능하므로 사용하실 수 없습니다.
만약 가맹점의 입금 통보를 받는 서버가 방화벽을 가져간다면 해당 방화벽에서 토스페이먼츠 NAT IP 로부터 가맹점 입금 통보 서버 쪽으로 inbound 방화벽을 허용해 주어야 하며, 그때 허용해주어야 하는 포트는 가맹점 입금 서버 URL 이 사용하는 포트입니다.
토스페이먼츠 NAT IP 리스트는 [https://docs.tosspayments.com/guides/apis/usage#ip-접근-제어-목록에-추가해주세요] 를 참고하시면 됩니다.
가상계좌 입금 통보 URL 은 상점의 개발자센터에서 설정하실 수 있습니다. 이 경우 모든 가상계좌 결제에 기본적으로 적용됩니다.
가상계좌 결제의 입금 처리
가맹점에서는 전달된 입금 통보에 대해 가맹점 서버가 정상적으로 입금에 대한 처리를 했다면 성공 응답(HTTP status code: 200)을 주어야 하고, 입금에 대한 처리를 실패하게 되면 성공 응답이 아닌 다른 응답 코드를 리턴하면 됩니다. 가맹점이 성공 응답을 리턴하지 않으면 거래 건의 입금 통보를 받지 못한 것으로 간주하여 거래 건의 상태에 대해 sync 를 맞추기 위해 재통보 프로세스가 진행이 됩니다. 정해진 규칙에 따라 최대 8회 [4^(n - 1)분 간격. e.g) 1, 4, 16, 64, … 16,384분] 까지 동일한 내용으로 재통보를 하게 되고 재통보에 대해서 가맹점이 성공 응답을 하면 재통보는 중단 됩니다. 재통보가 발생하는 경우 실제 입금 이벤트가 발생한 시점과 가맹점에서 통보를 받은 시점이 달라질 수 있으므로 이때는 입금 통보의 createAt 값을 참고해서 실제 이벤트가 발생한 시점을 확인해 주시기 바랍니다.
따라서 가상계좌 결제수단을 연동하실때에는 다른 결제수단과는 다르게 결제 연동을 통해 가상계좌 발급하는 부분 이외에, 입금통보를 처리하는 부분을 별도로 개발해 주셔야 합니다.
입금통보를 처리할 때 주의하실 점이 있습니다. 몇몇 은행(대표적으로 신한) 의 경우 특정 상황(고객계좌 문제, 이체 한도 초과 등) 으로 실제 입금이 되지 않았음에도, 입금 통보(status = DONE)가 발생하고 이후 짧게는 1~2초 후, 길게는 2분 이상까지도 취소 통보(status = WAITING_FOR_DEPOSIT) 가 발생하는 경우가 있습니다. 이 경우 실제로는 입금이 되지 않은 상황이므로, 물품배송, 서비스 제공 등을 중지하고 입금 전 상태로 만들어 주셔야 합니다. 고객님 입장에서는 그 가상계좌에 다시 입금이 가능합니다.
이 이슈는 원천사(은행) 에서 발생되는 것으로 토스페이먼츠에서 해결해 드릴 수 없습니다. 일반적으로 매우 드물게 발생하는 케이스이지만 제대로 처리하지 않으면 결제가 되지 않았는데 고객에게 서비스가 제공되어 가맹점에 손해가 발생될 수 있으므로 꼭 처리해 주시기 바랍니다.
만약 이렇게 처리하기 어려운 부분이 있으시다면 토스페이먼츠에서 제공하는 “2분 지연통보” 를 사용하실 수 있습니다. 해당 기능은 상점에 설정하는 것으로 이 기능을 사용하면 입금이 발생하고 2분 동안 토스페이먼츠에서 이벤트를 보관하고 있다가 그동안 취소 통보 가 발생하지 않을 때만 가맹점에 입금 통보(status = Done) 를 보내게 됩니다. 그러므로 위에 설명드린 입금 후 바로 취소 통보가 발생하는 경우에는 가맹점으로 입금 통보가 발생하지 않게 됩니다.
다만, 이 기능을 사용하게 되면 고객이 입금을 한 후 가맹점에 입금 처리가 될 때까지 무조건 2분의 지연이 발생하게 되므로, 고객 컴플레인이 발생할 수도 있습니다. 그래서 입금 처리가 실시간으로 되어야 하는 상품(포인트 충전, 게임아이템등) 의 경우는 이런 제약을 감안하시어 “2분 지연통보” 사용여부를 신중이 판단해 주시기 바랍니다. 2분 지연을 사용하더라도 2분이 지난후에 취소 통보가 발생할 가능성이 없는 것이 아니므로 별도로 취소 통보를 가맹점에서 받으시면 처리를 하실수 있도록 해주셔야 합니다.
가상계좌의 반납
가상계좌 발급 요청 시에 특정 시점 이후로는 더이상 해당 가상계좌에 입금이 불가하도록 하는 반납 시점을 발급 후 최대 30일까지 지정할 수 있습니다(별도로 지정하지 않으면 발급 후 7일 후가 됩니다).
가상계좌 반납 시점은 아래 두가지중 한가지를 사용하실수 있습니다. (동시에 사용은 불가합니다)
•
validHours 를 사용하여 발급 시점부터 특정 시간 후에 반납되게 하거나
•
dueDate 를 사용하여 정해진 특정 시간에 반납되게 할 수 있습니다.
두 가지 경우 모두 발급 시점을 기준으로 최대 30(720시간)일까지 설정이 가능합니다.
가상계좌가 반납 되었다고 해서 별도의 통보나 웹훅을 제공해 드리지는 않습니다. 입금이 되지 않은 채 가상계좌가 반납 되더라도 WAITING_FOR_DEPOSIT 상태에서 변경되지 않습니다. 결제 조회 시에 virtualAccount.dueDate 정보를 참고해서 반납 되었는지 알 수 있습니다.
만약 가맹점에서 발급한 가상계좌의 가맹점에서 발급한 가상계좌에 설정된 입금 마감 시간이 되기 전에 반납을 시켜야 할 필요가 있다면(고객이 더 이상 그 가상계좌에 입금을 하지 못하게 하려면), 입금이 되기 전 상태에서 취소 API[가이드링크] 를 호출해 주시면 해당 가상계좌는 즉시 반납 처리 되어 더 이상 입금이 되지 않습니다.
•
validHours 의 경우 일반적인 상점에서 사용하는 것으로 주문후 특정시간 내에 입금을 하지 않으면 주문이 성립되지 않도록 할때 사용하시면 되고
•
dueDate 의 경우는 티켓 예매등 주문시간과 무관하게 정해진 특정 시간까지만 입금을 받을 사용하실 수 있습니다. 또한 일반 커머스에서도 입금 가능시간을 주문 N일 뒤 자정까지로 하고 싶으실때 사용하시면 됩니다.
가상계좌의 종류
일반적으로 가상계좌는 2가지 종류가 있습니다.
두 가지 가상계좌는 상점의 설정에 따라 다르게 동작합니다.
•
일반형 가상계좌
◦
일반적인 가상계좌로 각 결제 시마다 입금 가능한 금액과 반납 시기를 정해서 발급하는 가상계좌입니다.
◦
고객이 선택한 은행으로 가상의 계좌번호가 랜덤하게 발급되고, 각 주문 별로 다른 가상계좌 번호가 발급됩니다.
◦
그래서 고객께서는 꼭 각 주문 시에 발급된 가상계좌 번호와 입금 금액을 확인하고 입금을 하셔야 합니다
•
고정형 가상계좌
◦
동일한 고객에서 동일한 가상계좌번호를 발급하고 싶을 때 사용하는 가상계좌입니다.
◦
특정 고객에서 유니크한 가상계좌를 부여하여 여러 주문에 대해 동일한 가상계좌를 발급하는 방식입니다.
◦
일반 가상계좌와 동일하게 요청하지만 추가적으로 accountKey 를 보내주셔야 합니다.
◦
이때 accountKey 는 일반적으로 사용자를 특정(주민번호, 외국인 번호등의 개인정보)할 수 없는 가맹점에서 별도로 관리하시는 정보를 사용해 주시기 바랍니다.
◦
만약 동일한 은행의 가상계좌를 요청하면서 동일한 accountKey 를 보내주시면 이전에 해당 accountKey 에 발급 되었던 동일한 가상계좌를 발급합니다.
◦
그래서 고객 입장에서는 입금 금액만 확인하면 되고, 주문 시마다 같은 가상계좌에 입금을 하면 되기 때문에 고객의 전용 가상계좌처럼 사용이 가능합니다.
◦
고정형 가상계좌의 특이점으로는 주문 후 아직 입금을 하지 않은 상태에서 동일 고객이 다른 주문을 요청해 기존과 동일한 가상계좌 번호를 추가로 발급받을 수 있습니다.
즉, A 주문 10000원 으로 고정형 가상계좌를 발급하고, 다시 B 주문 5000원으로 동일한 고정형 가상계좌 발급이 가능합니다.
◦
이 때, 입금을 10000원을 하게 되면 A 주문에 대해 입금 처리가 되고, 5000원을 입금하게 되면 B 주문이 입금 처리 됩니다. 추가적으로 두 주문의 합인 15000원을 입금하게 되면 A 와 B 주문이 모두 입금처리 됩니다. WoW
◦
만약 동일 금액(10000원)으로 2건의 가상계좌가 발급된 경우 10000원을 입금하게 되면 더 나중에 발급된 주문 정보가 먼저 입금처리 됩니다. (동일 금액에 대해 주문번호 처리 방식은 후입선출로 처리됩니다.)
◦
조금 더 복잡한 케이스의 사례를 예로 들어 보겠습니다.
고객이 동일한 가상계좌에 대해 3개 이상의 주문 요청을 하여 발급된 경우,
▪
각 1건의 주문에 해당 하는 금액이 입금되면 해당 주문 건이 입금처리가 됩니다.
▪
동일 금액으로 발급된 주문이 2개 이상인 경우 해당 금액이 입금되면 나중에 발급된 주문으로 입금처리 됩니다.
▪
발급된 모든 주문의 금액의 총합을 입금하는 경우 모든 주문이 입금 처리 되지만
▪
발급된 주문의 일부 금액의 합을 입금하는 것은 불가 합니다.
▪
예를 들어 1000원, 2000원, 4000원 으로 고정형 가상계좌가 발급이 되었다면,
•
1000, 2000, 4000, 7000원은 입금이 가능하지만,
•
부분합인 3000, 6000, 5000원 등은 입금 자체가 불가능 합니다.
가상계좌로 이체 시에 표시되는 가상계좌 예금주명
발급된 가상계좌로 고객이 입금하실 때 표시되는 예금주명과 입금 후 통장에 보이는 가상계좌 예금주명은 기본적으로 상점 이름을 사용하고 있습니다. 변경이 필요하신 경우 토스페이먼츠에 변경 요청을 하시거나 상점관리자에서 변경이 가능합니다. 추가적으로 가상계좌의 예금주명을 고객의 이름이나 상점 이름과 혼합해서 표시하고자 하는 경우가 있습니다.
예) 김토스_토스모터스
이때도 역시 토스페이먼츠에 설정을 요청하시고, 표시하고자 하는 이름을 입금자 명에 파라미터로 넣어주시면 됩니다. (통합 결제창과 API 각각 설명을 참고하시기 바랍니다.)
주의 : 단, 해당 설정과 다르게 은행 정책 상 은행별 이체 화면마다 모계좌 기관명인 토스페이먼츠 또는 헥토파이낸셜로 보여질 수 있으며 이는 당사에서 컨트롤 할 수 없는 부분임을 참고 부탁 드립니다.
가상계좌 거래 건의 취소
가상계좌에 고객이 입금하시기 전에는 입금이 된 금액이 없으므로 취소를 하더라도 고객에게 환불 되지는 않습니다. 가상계좌 입금 전에는 전체 취소만 가능하고, 전체 취소를 하게 되면 위에 설명한 대로 발급된 가상계좌가 더 이상 입금이 불가능한 상태로 변경됩니다.
가상계좌로 고객이 입금하신 후에 취소를 하는 경우, 토스페이먼츠나 가맹점은 고객이 어떤 계좌에서 가상계좌로 입금을 했는지 알 수가 없습니다. 그래서 다른 결제와는 다르게 전체취소나 부분취소시에 고객이 돈을 돌려 받을 은행 계좌 정보를 refundReceiveAccount 에 넣어서 요청해야 합니다.
즉 가상계좌로 결제를 받고 취소하는 경우 고객으로부터 환불계좌 정보를 입력 받아야 환불이 가능합니다. 이때 필요한 환불 계좌 정보는 은행명, 계좌번호, 예금주 명 이렇게 3가지 인데, 취소 API 호출시에 계좌 유효성 검사(해당 계좌의 예금주와 입력한 예금주가 일치하는지 여부) 를 진행해서 실제 예금주 이름과 다른경우 에러가 발생합니다.
그렇기 때문에 환불 계좌의 예금주 명을 정확하게 보내주셔야 합니다.
보통 일반 고객의 개인 계좌는 큰 이슈가 없으나 다음 2가지 경우 계좌유효성검사가 실패하는 경우가 많습니다.
•
법인 명의의 계좌는 예금주 명이 특이하게 되어 있는 경우가 많습니다. 예를 들어 홍길동(길동물산) 이나 법인명 으로 되어 있는 경우도 있어서 정확히 입력이 필요합니다.
•
외국인의 경우 예금주명에 영문이름인 경우가 많은데, 특히 이름과 성 사이에 공란이 있거나 반대로 없는 경우가 있습니다. (EX) “Tom Cruise” 또는 “TomCruise” 등) 그러므로 실제 계좌에 등록된 공란을 포함한 이름을 예금주 명에 입력해야 합니다.
가상계좌 취소 건의 경우 취소 요청을 하게 되면 D+1 일에 토스페이먼츠에서 은행에게 환불을 위한 입금요청을 하고 D+2 일에 은행에서 고객님의 계좌로 입금처리가 되어 총 2일이 소요 되게 됩니다.
가상계좌 취소 건에 대해 입금이 될 때는 상점 이름이 아니라 “토스페이먼츠” 이름으로 입금됩니다. 참고하시기 바랍니다.