목차

가상계좌 API

가상계좌 발급 API로 고객이 원하는 은행의 가상계좌를 발급하고, 입금 결과를 전달받을 가상계좌 웹훅 URL을 등록하세요.

API를 사용하기 위해 필요한 키 정보와 인증 방식, 보안에 대한 정보는 API 사용하기에서 자세히 알아보세요.

1. 가상계좌 발급 API 요청 보내기

기본 주문 정보와 고객이 입금을 원하는 은행 코드를 bank에 추가해서 가상계좌 발급 요청 API 요청 본문으로 보냅니다.

가상계좌를 발급할 수 있는 은행 코드는 아래 목록을 참고하세요.

요청
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\":\"WmvMrROp7IKpKY89Cz4-E\",\"orderName\":\"토스 티셔츠 외 2건\",\"customerName\":\"박토스\",\"bank\":\"우리\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

응답으로 고객에게 발급된 가상계좌 정보를 담은 virtualAccount 객체가 돌아옵니다.

요청할 때 보낸 은행 코드명과 발급된 계좌의 은행과 동일한지, 가상 계좌번호가 올바르게 생성되었는지 확인한 뒤 고객에게 입금방법을 안내하세요.

응답
{

  "mId": "tosspayments",

  "version": "1.4",

  "paymentKey": "",

  "orderId": "",

  "orderName": "토스 티셔츠 외 2건",

  "currency": "KRW",

  "method": "가상계좌",

  "status": "WAITING_FOR_DEPOSIT",

  "requestedAt": "2022-01-01T20:12:46+09:00",

  "approvedAt": "2022-01-01T20:12:47+09:00",

  "useEscrow": false,

  "cultureExpense": false,

  "card": null,

  "virtualAccount": {

    "accountNumber": "X6505636518308",

    "accountType": "일반",

    "bank": "우리",

    "customerName": "박토스",

    "dueDate": "2022-01-15T21:05:09+09:00",

    "expired": false,

    "settlementStatus": "INCOMPLETED",

    "refundStatus": "NONE"

  },

  "transfer": null,

  "mobilePhone": null,

  "giftCertificate": null,

  "foreignEasyPay": null,

  "cashReceipt": null,

  "discount": null,

  "cancels": null,

  "secret": null,

  "type": "NORMAL",

  "easyPay": null,

  "country": "KR",

  "failure": null,

  "totalAmount": 15000,

  "balanceAmount": 15000,

  "suppliedAmount": 13636,

  "vat": 1364,

  "taxFreeAmount": 0

}
JSON

2. 가상계좌 웹훅 URL 등록하기

가상계좌 웹훅 URL을 등록하는 방법은 직접 파라미터로 넘기는 방법과 개발자센터에서 설정하는 방법 두 가지가 있습니다.

만약 웹훅 URL이 두 가지 방식으로 모두 설정되어 있다면, API 요청 파라미터로 직접 넘긴 웹훅 URL이 개발자센터에서 설정한 웹훅 URL보다 우선순위가 높습니다.

API 요청 파라미터로 넘기기

가상계좌 발급 API 요청을 보낼 때 아래와 같이 선택 파라미터로 virtualAccountCallbackUrl을 추가할 수 있습니다.

요청
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\":\"WmvMrROp7IKpKY89Cz4-E\",\"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());

개발자센터에서 설정하기

개발자센터의 웹훅 페이지에서 가상계좌 웹훅 URL을 설정할 수 있습니다.

다른 결제 방식과 달리 가상계좌 결제는 요청 즉시 결제가 완료되는 것이 아니라 발급된 계좌에 구매자가 입금한 것을 확인했을 때 결제 완료 처리를 할 수 있습니다. 따라서 비동기적으로 변경되는 가상계좌의 결제 상태를 확인하기 위해 웹훅 URL을 설정하는 과정이 필요합니다.

3. 입금 확인하기

고객이 가상계좌에 입금하면 아래와 같은 형태의 이벤트 본문이 웹훅 URL로 전달됩니다.

결제 상태를 나타내는 status 값이 DONE으로 변경된 것을 확인할 수 있습니다.

{

  "createdAt": "2022-01-01T20:15:32.374",

  "secret": "",

  "status": "DONE", // 입금 완료

  "orderId": ""

}
JSON

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

Case. 같은 가상계좌에 여러 번 입금하고 싶어하는 고객이 있을 때

같은 가상계좌에 여러 번 입금을 원하는 고객이 있을 때 가상계좌와 고객을 매칭시키는 방식으로 고정 가상계좌를 발급할 수 있습니다. 고정 가상계좌를 사용하는 상점으로 계약하면 사용할 수 있는 기능입니다.

고객과 매칭시켜 사용할 고정 가상계좌를 특정하는 accountKey 값을 추가하고 파라미터 accountType를 고정으로 설정해주세요. 이 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\":\"y9KaowgoOfzu894Iyq5QH\",\"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의 값이 고정으로 설정되어 있는지 확인해보세요.

응답
{

  "mId": "tosspayments",

  "version": "1.4",

  "paymentKey": "R9o5gEq4k6YZ1aOwX7K8m1g0QjYOP8yQxzvNPGenpDAlBdbM",

  "orderId": "a4CWyWY5m89PNh7xJwhk1",

  "orderName": "토스 티셔츠 외 2건",

  "currency": "KRW",

  "method": "가상계좌",

  "status": "WAITING_FOR_DEPOSIT",

  "requestedAt": "2022-01-01T20:12:46+09:00",

  "approvedAt": "2022-01-01T20:12:47+09:00",

  "useEscrow": false,

  "cultureExpense": false,

  "card": null,

  "virtualAccount": {

    "accountNumber": "X6505636518308",

    "accountType": "고정",

    "bank": "우리",

    "customerName": "박토스",

    "dueDate": "2021-02-05T21:05:09+09:00",

    "expired": false,

    "settlementStatus": "INCOMPLETED",

    "refundStatus": "NONE"

  },

  "transfer": null,

  "mobilePhone": null,

  "giftCertificate": null,

  "foreignEasyPay": null,

  "cashReceipt": null,

  "discount": null,

  "cancels": null,

  "secret": null,

  "type": "NORMAL",

  "easyPay": null,

  "country": "KR",

  "totalAmount": 15000,

  "balanceAmount": 15000,

  "suppliedAmount": 13636,

  "vat": 1364,

  "taxFreeAmount": 0

}
JSON

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

가상계좌를 발급할 수 있는 은행은 아래와 같습니다.

한글코드영문코드은행이름
경남KYONGNAMBANK경남은행
광주GWANGJUBANK광주은행
국민KOOKMINKB국민은행
기업IBKIBK기업은행
농협NONGHYEOPNH농협은행
대구DAEGUBANKDGB대구은행
부산BUSANBANK부산은행
새마을SAEMAUL새마을금고
수협SUHYEOPSh수협은행
신한SHINHAN신한은행
우리WOORI우리은행
우체국POST우체국예금보험
전북JEONBUKBANK전북은행
케이KBANK케이뱅크
하나HANA하나은행

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

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

내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
    자주 묻는 질문
  • 코드 샘플을 참고하세요
    TossPayments GitHub
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기