가상계좌 발급 API로 고객이 원하는 은행의 가상계좌를 발급하고, 입금 결과를 전달받을 가상계좌 웹훅 URL을 등록하세요.
API를 사용하기 위해 필요한 키 정보와 인증 방식, 보안에 대한 정보는 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
}
가상계좌 웹훅 URL을 등록하는 방법은 직접 파라미터로 넘기는 방법과 개발자센터에서 설정하는 방법 두 가지가 있습니다.
만약 웹훅 URL이 두 가지 방식으로 모두 설정되어 있다면, API 요청 파라미터로 직접 넘긴 웹훅 URL이 개발자센터에서 설정한 웹훅 URL보다 우선순위가 높습니다.
가상계좌 발급 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을 설정하는 과정이 필요합니다.
고객이 가상계좌에 입금하면 아래와 같은 형태의 이벤트 본문이 웹훅 URL로 전달됩니다.
결제 상태를 나타내는 status
값이 DONE
으로 변경된 것을 확인할 수 있습니다.
{
"createdAt": "2022-01-01T20:15:32.374",
"secret": "",
"status": "DONE", // 입금 완료
"orderId": ""
}
웹훅에 대한 더 자세한 내용은 웹훅 연동하기를 참고하세요.
같은 가상계좌에 여러 번 입금을 원하는 고객이 있을 때 가상계좌와 고객을 매칭시키는 방식으로 고정 가상계좌를 발급할 수 있습니다. 고정 가상계좌를 사용하는 상점으로 계약하면 사용할 수 있는 기능입니다.
고객과 매칭시켜 사용할 고정 가상계좌를 특정하는 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
}
가상계좌를 발급할 수 있는 은행은 아래와 같습니다.
한글코드 | 영문코드 | 은행이름 |
---|---|---|
경남 | KYONGNAMBANK | 경남은행 |
광주 | GWANGJUBANK | 광주은행 |
국민 | KOOKMIN | KB국민은행 |
기업 | IBK | IBK기업은행 |
농협 | NONGHYEOP | NH농협은행 |
대구 | DAEGUBANK | DGB대구은행 |
부산 | BUSANBANK | 부산은행 |
새마을 | SAEMAUL | 새마을금고 |
수협 | SUHYEOP | Sh수협은행 |
신한 | SHINHAN | 신한은행 |
우리 | WOORI | 우리은행 |
우체국 | POST | 우체국예금보험 |
전북 | JEONBUKBANK | 전북은행 |
케이 | KBANK | 케이뱅크 |
하나 | HANA | 하나은행 |