카드 자동결제(Billing) API
카드 자동결제는 고객의 결제수단 정보를 저장해두고 가맹점이 원하는 시점에 결제하는 방법입니다. 자동결제를 연동하면 고객은 결제할 때마다 결제수단 정보를 매번 입력할 필요가 없고, 가맹점에서는 원하는 때에 해당 키 값을 사용해서 바로 결제할 수 있습니다.
API 사용하기에서 API 사용에 필요한 인증 정보를 구성해두세요.
1 빌링키 발급받기
빌링키 발급 API를 사용해서 고객의 카드 정보를 등록할 수 있습니다. 카드 번호, 카드 유효기간, 카드 소유자의 생년월일, 카드 비밀번호(선택)를 요청 본문에 포함하세요. 카드 정보는 빌링키를 발급할 때 한 번 사용되고, 이후에는 발급받은 빌링키를 자동결제의 결제수단으로 사용합니다.
customerKey도 요청 본문에 포함해야 합니다. customerKey는 가맹점에서 고객을 특정하는 값으로, 빌링키가 발급되면 이 값에 연결됩니다.
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.tosspayments.com/v1/billing/authorizations/card"))
.header("Authorization", "Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("{\"cardNumber\":\"4330123412341234\",\"cardExpirationYear\":\"24\",\"cardExpirationMonth\":\"07\",\"cardPassword\":\"12\",\"customerBirthday\":\"881212\",\"customerKey\":\"aENcQAtPdYbTjGhtQnNVj\"}"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());정상적으로 요청이 승인되면 billingKey를 포함하는 응답이 돌아옵니다.
2 결제승인 요청하기
이제 빌링키를 사용해서 결제승인을 요청해봅니다.
발급받은 billingKey를 카드 자동결제 승인요청 API의 Path 파라미터로 추가합니다. 요청 본문에는 주문정보와 함께 customerKey 를 포함합니다.
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.tosspayments.com/v1/billing/{billingKey}"))
.header("Authorization", "Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("{\"customerKey\":\"aENcQAtPdYbTjGhtQnNVj\",\"amount\":15000,\"orderId\":\"eR-TJvsVdvdMlSAgUFMsR\",\"orderName\":\"토스 티셔츠 외 2건\"}"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());정상적으로 요청이 승인되면 빌링키를 발급받을 때 등록했던 카드로 결제됩니다. 결제수단이 카드이기 때문에 응답은 카드 결제의 응답과 동일하게 card 필드를 포함한 형태로 돌아옵니다.
카드 등록과 첫번째 결제 같이 하기
billingKey가 발급되는 동시에 자동결제 승인 요청 API를 호출하면 카드 자동결제 등록과 결제가 한 번에 완료됩니다.
자동결제는 구독 서비스의 정기 결제, 사용량에 따른 후불 결제 등 가맹점이 원하는 시점에 자동으로 결제가 되는 모든 경우에 사용할 수 있습니다.