카드 자동 결제(Billing) 연동

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

카드 자동 결제 흐름도

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

1. 먼저, SDK를 준비하세요

SDK를 추가한 뒤 클라이언트 키를 사용해 객체를 초기화합니다.

<head>
<title>결제하기</title>
<script src="https://js.tosspayments.com/v1"></script>
</head>
<body>
<script> var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' var tossPayments = TossPayments(clientKey) // 클라이언트 키로 초기화하기 </script>
</body>

SDK 준비에 대한 더 자세한 설명은 연동 준비 페이지에서 확인할 수 있습니다.

2. 결제창을 띄워보세요 🚀

객체가 초기화 되었다면 이제 SDK에 포함된 메서드를 실행할 수 있습니다.

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

아래와 같이 tossPayments.requestBillingAuth(결제 수단, 결제 정보) 형식으로 파라미터를 넣고 실행하면 결제창이 열립니다.

tossPayments.requestBillingAuth('카드', {
// 결제 수단 파라미터
// 빌링키 발급 요청을 위한 파라미터
customerKey: '',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
})
JavaScript

requestBillingAuth 메서드의 첫 번째 파라미터는 결제 수단입니다. 결제 수단으로 카드를 추가하세요. 현재 토스페이먼츠에서 지원하는 자동 결제 결제 수단은 카드 한 가지이므로 결제 수단 파라미터에는 항상 카드가 들어갑니다.

두 번째 파라미터는 빌링키 발급 요청을 위한 정보입니다. 필수 파라미터인 고객 키(customerKey)와 결제 요청 결과에 따라 리다이렉트 될 URL(successUrl, failUrl)을 추가하세요. 고객 이름(customerName)과 같은 정보는 선택 파라미터로 추가할 수 있습니다.

카드 자동 결제 결제 수단 등록창 예시 이미지

위와 같이 자동 결제 등록창이 열렸다면 필요한 정보를 입력한 뒤 빌링키 발급을 요청하세요.

빌링키 발급 요청 파라미터

  • customerKey 필수 · string

    상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID입니다. 이 값에 빌링키가 연결됩니다. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @로 최소 2자 이상 최대 255자 이하여야 합니다.

  • successUrl 필수 · string

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

  • failUrl 필수 · string

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

  • customerName string

    고객의 이름입니다. 최소 1글자 이상 최대 10글자 이하여야 합니다.

  • customerEmail string

    고객의 이메일 주소입니다.

  • taxFreeAmount number
    전체 결제 금액 중 면세 금액입니다. 값이 `0`으로 돌아왔다면 전체 결제 금액이 과세 대상입니다.

    *일반 상점일 때는 모든 결제 금액이 과세에 해당하기 때문에 0이 돌아옵니다. 면세 상점, 복합 과세 상점일 때만 면세 금액이 돌아옵니다. 더 자세한 내용은 복합 과세 처리하기에서 살펴보세요.

  • windowTarget string

    브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.

    값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.

    * 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.

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

3. 빌링키를 발급받아요

리다이렉트 URL 확인하기

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

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

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

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

결제 요청에 실패했다면 결제 실패 URL 리다이렉트를 살펴보세요.

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/DvxHT-9cTEs8Pw6q_HoDs"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"customerKey\":\"FWfxPzQU3J2kCSmhVyksM\"}"))
    .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=",
"card": {
"company": "현대",
"number": "433028******0916",
"cardType": "신용",
"ownerType": "개인"
}
}
JSON

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": "2022-06-08",
"paymentKey": "",
"status": "DONE",
"transactionKey": "",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 프라임 구독",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "농협",
"number": "123456******7890",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://dashboard.tosspayments.com/sales-slip?transactionId=KAgfjGxIqVVXDxOiSW1wUnRWBS1dszn3DKcuhpm7mQlKP0iOdgPCKmwEdYglIHX&ref=PX",
"amount": 5000
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "BILLING",
"easyPay": null,
"country": "KR",
"failure": null,
"isPartialCancelable": true,
"receipt": {
"url": "https://dashboard.tosspayments.com/sales-slip?transactionId=KAgfjGxIqVVXDxOiSW1wUnRWBS1dszn3DKcuhpm7mQlKP0iOdgPCKmwEdYglIHX&ref=PX"
},
"currency": "KRW",
"totalAmount": 5000,
"balanceAmount": 5000,
"suppliedAmount": 3636,
"vat": 364,
"taxFreeAmount": 0,
"method": "카드"
}
JSON

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

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