카드 등록 후 자동으로 결제하기 (빌링)

자동결제는 다른 이름으로 빌링, 또는 정기결제로 불리는 결제 방식입니다. 카드 등록창에서 고객의 카드를 한 번만 등록하고 나면, 별도의 고객 인증 없이 간편하게 결제를 요청할 수 있습니다.

자동결제는 추가 계약 후 테스트 및 라이브 환경에서 사용할 수 있습니다. 추가 계약을 하고 싶다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

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

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

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

더 자세한 SDK 설명은 결제창 SDK 페이지에서 확인할 수 있습니다.

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

초기화된 객체로 SDK 메서드를 사용할 수 있습니다. requestBillingAuth(결제수단, 결제 정보) 메서드를 실행하면 카드 정보를 입력할 수 있는 결제창이 열립니다. 자동결제를 하려면 원할 때 바로 결제할 수 있도록 카드 정보를 미리 등록해둬야 합니다.

첫 번째 파라미터는 결제수단입니다. 자동결제는 카드 결제수단만 지원합니다.

두 번째 파라미터는 결제 정보입니다. 고객 정보, 리다이렉트 URL, 결제창 프레임을 파라미터로 설정하세요.

tossPayments.requestBillingAuth('카드', { // 결제수단 파라미터
  // 빌링키 발급 요청을 위한 파라미터
  customerKey: '',
  successUrl: 'http://localhost:8080/success',
  failUrl: 'http://localhost:8080/fail',
})
.catch(function (error) {
  if (error.code === 'USER_CANCEL') {
    // 결제 고객이 결제창을 닫았을 때 에러 처리
  } else if (error.code === 'INVALID_CARD_COMPANY') {
    // 유효하지 않은 카드 코드에 대한 에러 처리
  }
})

JavaScript

테스트 환경에서 본인인증 문자는 발송되지 않습니다. 본인인증창이 뜨면 인증번호로 000000을 입력하세요.

메서드 실행에 성공하면 위와 같이 자동결제 등록창이 열립니다. 고객이 정보를 입력하면 빌링키 발급을 요청하세요.

메서드 실행에 실패하면 reject 된 에러는 Promise의 catch 블록에서 처리할 수 있습니다. 발생할 수 있는 에러 코드를 살펴보세요.

빌링키 발급 요청 파라미터

customerKey 필수 · string
고객 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 빌링키와 연결됩니다. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @로 이루어진 최소 2자 이상 최대 300자 이하의 문자열입니다.
successUrl 필수 · string
결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.
failUrl 필수 · string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
customerName string
고객의 이름입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다. 최대 길이는 100자입니다.
windowTarget string
브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.
값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.
* 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.

3. 빌링키를 발급받아요

결제수단 등록 요청이 성공하면 successUrl로 이동합니다. URL에 포함된 쿼리 파라미터를 확인하고 빌링키 발급을 요청하세요.

결제수단 등록 요청이 실패하면 failUrl로 이동합니다. 결제 실패 URL 리다이렉트를 살펴보세요.

리다이렉트 URL 확인하기

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

https://{ORIGIN}/success?customerKey=&authKey=

customerKey: 고객 ID입니다.
authKey: 빌링키를 발급받을 때 사용하는 일회성 인증 키입니다. 최대 길이는 300자입니다.

리다이렉트 URL 쿼리 파라미터를 이용해 빌링키 발급 API를 호출할 수 있습니다.

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

API 호출하기

카드 자동결제 빌링키 발급 요청 API를 호출합니다. authKey, customerKey 값을 요청 본문으로 보냅니다.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/billing/authorizations/issue \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"authKey":"z-pMXBcJX6wha3EOYFWX7","customerKey":"Lun2J7SeD-uLfjBhFrHhW"}'

빌링키 발급 결과 보기

API 호출 결과로 HTTP 200 OK를 받으면 빌링키 발급 성공입니다. 이제 응답 본문에 포함된 billingKey를 이용해 결제 승인을 요청합니다.

응답

{
  "mId": "tosspayments",
  "customerKey": "",
  "authenticatedAt": "2021-01-01T10:00:00+09:00",
  "method": "카드",
  "billingKey": "Z_t5vOvQxrj4499PeiJcjen28-V2RyqgYTwN44Rdzk0=",
  "card": {
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "43301234****123*",
    "cardType": "신용",
    "ownerType": "개인"
  }
}

JSON

빌링키와 고객을 특정하는 customerkey를 매핑하여 서버에 저장하세요.

4. 빌링키로 결제 승인을 요청하세요

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

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/billing/{billingKey} \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"customerKey":"Lun2J7SeD-uLfjBhFrHhW","amount":4900,"orderId":"ZpWO0VbEK91Wy9q3nRNQd","orderName":"토스 프라임 구독","customerEmail":"customer@email.com","customerName":"박토스","taxFreeAmount":0}'

반드시 customerkey와 일치하는 billingKey를 사용하세요. 만약 값이 일치하지 않으면 NOT_MATCHES_CUSTOMER_KEY 에러가 발생합니다.

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

API 호출 결과로 HTTP 200 OK를 받으면 결제 승인 성공입니다. 상태 코드와 함께 Payment 객체가 응답으로 돌아옵니다. 자동결제는 card 필드가 포함되어 있어야 합니다.

응답

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "",
  "status": "DONE",
  "lastTransactionKey": "",
  "orderId": "",
  "orderName": "토스 프라임 구독",
  "requestedAt": "2022-06-08T15:40:09+09:00",
  "approvedAt": "2022-06-08T15:40:49+09:00",
  "useEscrow": false,
  "cultureExpense": false,
  "card": {
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "43301234****123*",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "amount": 4900
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "cashReceipts": 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"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments//checkout"
  },
  "currency": "KRW",
  "totalAmount": 4900,
  "balanceAmount": 4900,
  "suppliedAmount": 4455,
  "vat": 455,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0,
  "method": "카드"
}

JSON

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