카드 자동결제(Billing) 연동

카드 자동결제 등록창에서 고객의 카드를 결제수단으로 등록할 수 있습니다. 등록이 되고 나면 이후에는 별도의 인증 없이 가맹점의 결제 요청만으로 간편하게 결제할 수 있습니다.

카드 자동결제 흐름도

자동결제는 구독 서비스의 정기 결제, 사용량에 따른 후불 결제 등 가맹점이 원하는 시점에 자동으로 결제가 되는 모든 경우에 사용할 수 있습니다.

1 먼저, SDK를 준비하세요

스크립트를 삽입해서 SDK를 추가합니다.

<head>
<title>결제하기</title>
<script src="https://js.tosspayments.com/v1"></script>
</head>

클라이언트 키를 사용해 객체를 초기화합니다.

var clientKey = 'test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe'
var tossPayments = TossPayments(clientKey)

2 자동결제 등록창을 호출해요

초기화 된 객체를 이용해서 SDK에 포함된 메서드를 사용할 수 있습니다.

자동결제의 경우 원하는 때 바로 결제할 수 있도록 결제수단 등록을 먼저 해둬야 합니다. requestBillingAuth 메서드를 실행하면 카드 정보를 입력할 수 있는 결제창이 열립니다.

requestBillingAuth는 다음과 같이 사용합니다.

tossPayments.requestBillingAuth({ 결제수단 }, { 결제정보 })

메서드 호출 준비하기

첫번째 파라미터는 결제수단입니다. 결제수단으로 카드를 추가하세요.

현재 지원하는 자동결제의 결제수단은 '카드' 한가지입니다.

tossPayments.requestBillingAuth('카드', {
customerKey: '',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail'
})

두번째 파라미터는 결제정보입니다. 고객을 특정하는 customerKey와 리다이렉트(Redirect) 될 URL을 추가해보세요.

tossPayments.requestBillingAuth('카드', {
customerKey: '',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
})

결제정보 파라미터

  • customerKey 필수 · string

    가맹점에서 사용하는 사용자별 고유 ID입니다. 빌링키가 해당 사용자에 할당됩니다.

  • successUrl 필수 · string

    결제가 성공하고 나면 리다이렉트(Redirect)되는 URL입니다. 결제승인 처리에 필요한 값들이 쿼리 파라미터(Query Parameter)로 함께 전달됩니다. 반드시 오리진(origin)을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.

  • failUrl 필수 · string

    결제가 실패하면 리다이렉트되는 URL입니다. 에러코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진(origin)을 포함해야 합니다.

결제정보 파라미터는 결제수단에 따라 조금씩 달라집니다. 각 결제 연동 가이드에서 결제수단별 파라미터 구성을 확인해보세요.

자동결제 등록창 띄우기

결제수단 등록창 호출 준비를 마치고 requestBillingAuth메서드를 실행하면 결제수단 정보를 입력할 수 있는 창이 열립니다.

결제수단 정보를 입력하고 빌링키 요청 단계를 진행하세요.

3 빌링키를 발급받아요

리다이렉트 URL 확인하기

결제수단 등록 요청이 성공하거나 실패하면 위에서 설정한 successUrl, failUrl 로 이동합니다. URL에 포함된 쿼리 파라미터로 결제승인을 요청할 수 있습니다.

자동결제 등록 성공 리다이렉트 URL에는 customerKey, authKey 두가지 쿼리 파라미터가 들어있습니다.

https://{origin}/success?customerKey=&authKey=e_826EDB0730790E96F116FFF3799A65DE
  • customerKey: 가맹점에서 사용하는 사용자별 고유 ID입니다.
  • authKey: 빌링키를 얻을 때 사용하는 인증 키입니다.

돌아온 파라미터를 이용해 빌링키 발급 API를 호출할 수 있습니다.

customerKey 값이 같은지 확인하기

결제창을 열 때 requestBillingAuth메서드에 담아 보냈던 customerKey값과 리다이렉트 URL에 있는 customerKey값이 같은지 확인해보세요. 값이 같다면 이제 빌링키를 발급받을 준비가 되었습니다.

API 호출하기

빌링키 발급 API를 호출합니다. 리다이렉트 URL로 받은 값 중 authKey는 Path 파라미터로 추가하고, customerKey 값은 요청 본문으로 함께 보냅니다.

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/billing/authorizations/e_826EDB0730790E96F116FFF3799A65DE"))
    .header("Authorization", "Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"customerKey\":\"vhNvvy6TDiocH9S7VGvUj\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

빌링키 발급 결과 보기

빌링키 발급 API의 HTTP 상태 코드가 200이면 요청 성공입니다. 이제 응답 본문에 포함된 billingKey를 이용해 결제요청을 진행해봅니다.

응답
{
"mId": "tosspayments",
"customerKey": "",
"authenticatedAt": "2021-01-01T10:00:00+09:00",
"method": "카드",
"billingKey": "Z_t5vOvQxrj4499PeiJcjen28-V2RyqgYTwN44Rdzk0=",
"cardCompany": "현대",
"cardNumber": "433028******0916"
}

4 빌링키로 결제승인을 요청해보세요

발급받은 billingKey를 카드 자동결제 승인 API의 Path 파라미터로 추가합니다. 요청 본문에는 amount, orderId 와 같은 구매자의 주문정보와 함께 customerKey를 포함합니다.

$ curl https://api.tosspayments.com/v1/billing/Z_t5vOvQxrj4499PeiJcjen28-V2RyqgYTwN44Rdzk0=
-H 'Authorization: Basic dGVzdF9za19PeUwwcVo0RzFWT0xvYkI2S3d2cm9XYjJNUVlnOg==' \
-H 'Content-Type: application/json' \
-d '{
"amount": 4900,
"customerKey": "",
"orderId": "",
"customerEmail": "customer@email.com",
"customerName": "박토스",
"orderName": "토스 프라임 구독",
"taxFreeAmount": 0
}'

5 자동결제를 성공적으로 완료하셨네요! 🎉

API 호출 결과로 HTTP 상태 코드 200이 돌아오면 결제승인 성공입니다.

상태 코드와 함께 아래와 같은 응답 본문이 함께 돌아옵니다. 카드 결제에 대한 승인 응답이기 때문에 card 필드가 포함 되어 있어야 합니다.

응답
{
"mId": "tosspayments",
"version": "1.3",
"paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
"orderId": "",
"orderName": "토스 프라임 구독",
"currency": "KRW",
"method": "카드",
"totalAmount": 4900,
"balanceAmount": 4900,
"suppliedAmount": 4455,
"vat": 455,
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "현대",
"number": "433012******1234",
"installmentPlanMonths": 0,
"isInterestFree": false,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "BILLING",
"easyPay": null
}

응답 필드는 API 버전에 따라 조금씩 달라집니다. 돌아온 응답에 원하는 필드가 없다면 개발 정보 페이지에 설정된 API 응답 버전을 확인한 뒤 필요한 버전으로 변경해보세요.

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