가상계좌 API

가상계좌 발급 API로 고객이 원하는 은행의 가상계좌를 발급할 수 있습니다. 가상계좌 발급 후에는 입금 결과를 전달받을 가상계좌 콜백 URL을 등록하세요. 발급된 계좌에 고객이 입금한 것을 확인하고 결제를 마무리 하세요.

API 사용하기에서 API 사용에 필요한 인증 정보를 구성해두세요.

1 가상계좌 발급 요청하기

고객이 입금을 원하는 은행 코드와 주문정보를 가상계좌 발급 요청 API 요청 본문으로 보냅니다. 응답으로 돌아온 가상계좌 정보와 함께 고객에게 입금 방법을 안내하세요.

일반 가상계좌 발급(기본)

기본 주문정보에 고객이 입금을 원하는 은행 코드를 bank에 추가해서 요청을 보냅니다. 아래 가상계좌 발급이 지원되는 은행 목록을 참고하세요.

요청

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/virtual-accounts"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"amount\":15000,\"orderId\":\"0GuD54jxc33jjn_EyieIq\",\"orderName\":\"토스 티셔츠 외 2건\",\"customerName\":\"박토스\",\"bank\":\"우리\",\"virtualAccountCallbackUrl\":\"https://www.mystore.com/event/virtaul-account\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

요청이 정상적으로 처리되면 응답에 virtualAccount 객체가 돌아옵니다. 요청할 때 보낸 은행 코드명과 발급된 계좌의 은행이 동일한지, 가상 계좌번호 정보가 올바르게 생성되었는지 확인해보세요.

응답

{
  "mId": "tosspayments",
  "version": "1.3",
  "paymentKey": "R9o5gEq4k6YZ1aOwX7K8m1g0QjYOP8yQxzvNPGenpDAlBdbM",
  "orderId": "a4CWyWY5m89PNh7xJwhk1",
  "orderName": "토스 티셔츠 외 2건",
  "currency": "KRW",
  "method": "가상계좌",
  // ...
  "virtualAccount": {
    "accountNumber": "X6505636518308",
    "accountType": "일반",
    "bank": "우리",
    "customerName": "박토스",
    "dueDate": "2021-02-05T21:05:09+09:00",
    "expired": false,
    "settlementStatus": "INCOMPLETED",
    "refundStatus": "NONE"
  }
  // ...
}

JSON

고정 가상계좌 발급

가상계좌는 고객이 한 번 입금하고 나면 다시 사용할 수 없는 일회성 계좌 발급이 기본입니다. 다만 같은 가상계좌에 여러 번 입금을 원하는 고객이 있는 경우 편의를 위해 이전에 발급한 가상계좌를 다시 발급할 수 있습니다. 이렇게 발급된 계좌를 고정 가상계좌라고 합니다.

고정 가상계좌를 발급받으려면 일반 가상계좌와 동일한 요청 본문에 두가지 파라미터를 추가해야 합니다. 먼저 계좌 타입인 accountType 의 값을 고정으로 설정하고, 고정 가상계좌를 발급받는 고객과 매칭되는 accountKey를 생성해서 추가합니다. 사용했던 accountKey 값을 가상계좌 발급 요청으로 보내면 고객에게 동일한 가상계좌를 다시 발급할 수 있습니다.

요청

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/virtual-accounts"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"amount\":15000,\"orderId\":\"ekktL6j9HuXJPvSRAJviX\",\"orderName\":\"토스 티셔츠 외 2건\",\"customerName\":\"김토스\",\"accountKey\":\"a123456\",\"accountType\":\"고정\",\"bank\":\"우리\",\"virtualAccountCallbackUrl\":\"https://www.mystore.com/event/virtaul-account\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

정상적으로 요청이 승인되면 일반 가상계좌 발급 요청에 대한 응답과 동일한 형태의 virtualAccount 객체가 돌아오고, accountType의 값은 고정으로 설정되어 있는 것을 확인할 수 있습니다.

가상계좌 발급이 지원되는 은행

가상계좌를 발급할 수 있는 은행은 아래와 같습니다. 추가되는 은행은 지속적으로 업데이트될 예정입니다.

한글 코드	영문 코드	은행 이름
`경남`	`KYONGNAMBANK`	경남은행
`광주`	`GWANGJUBANK`	광주은행
`국민`	`KOOKMIN`	KB국민은행
`기업`	`IBK`	IBK기업은행
`농협`	`NONGHYEOP`	NH농협은행
`대구`	`DAEGUBANK`	DGB대구은행
`부산`	`BUSANBANK`	부산은행
`새마을`	`SAEMAUL`	새마을금고
`수협`	`SUHYEOP`	Sh수협은행
`신한`	`SHINHAN`	신한은행
`우리`	`WOORI`	우리은행
`우체국`	`POST`	우체국예금보험
`전북`	`JEONBUKBANK`	전북은행
`케이`	`KBANK`	케이뱅크
`하나`	`HANA`	하나은행

2 입금 확인하기

가상계좌 콜백 URL이 필요한 이유

가상계좌를 이용한 결제는 고객이 입금할 수 있는 계좌를 제공하고 해당 계좌에 입금이 되면 결제가 완료되는 방식입니다. 따라서 요청 즉시 결제되는 다른 결제 방식과 달리, 발급된 계좌에 구매자가 입금한 것을 확인했을 때 결제 완료 처리를 할 수 있습니다.

이렇게 비동기적인 가상계좌의 결제 상태 변경을 확인하기 위해 콜백 URL을 설정하고, 콜백으로 전달받은 결제 상태를 확인하는 과정이 추가됩니다.

가상계좌 입금 알림 콜백 설정

입금이나 결제취소로 인해 결제 상태가 변경되면 토스페이먼츠 서버가 등록된 가맹점 콜백 URL을 호출합니다.

가상계좌 입금 알림 콜백 URL을 등록하는 방법은,

가상계좌 발급 API에 요청을 보낼 때 선택 파라미터에 virtualAccountCallbackUrl을 추가하거나,
토스페이먼츠 홈페이지 > 내 상점 > 개발 정보 페이지에서 URL을 설정하는 방법 두가지가 있습니다.

이때 파라미터로 추가하는 virtualAccountCallbackUrl은 개발 정보 페이지에서 설정한 콜백 URL보다 우선순위가 높습니다.

고객이 가상계좌에 결제금액을 입금하면 결제 상태가 아래와 같이 DONE으로 변경된 것을 확인할 수 있습니다.

{
  "eventType": "PAYMENT_STATUS_CHANGED",
  "data": {
    "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
    "status": "DONE",
    "orderId": "RNF7iYv1p6T5UG23su3yB"
  }
}

JSON

웹훅에 대한 더 자세한 내용은 웹훅 연동하기를 참고하세요.

가상계좌 발급요청 API를 자세히 알아보세요

가상계좌 발급요청 API를 직접 실행해보세요