자동결제는 다른 이름으로 빌링, 또는 정기결제로 불리는 결제 방식입니다. 카드 등록창에서 고객의 카드를 한 번만 등록하고 나면, 별도의 고객 인증 없이 간편하게 결제를 요청할 수 있습니다.
자동결제는 추가 계약 후 테스트 및 라이브 환경에서 사용할 수 있습니다. 추가 계약을 하고 싶다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.
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 페이지에서 확인할 수 있습니다.
초기화된 객체로 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') {
// 유효하지 않은 카드 코드에 대한 에러 처리
}
})
테스트 환경에서 본인인증 문자는 발송되지 않습니다. 본인인증창이 뜨면 인증번호로 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
값과 상관없이 항상 현재창에서 결제창으로 이동합니다.
결제수단 등록 요청이 성공하면 successUrl
로 이동합니다. URL에 포함된 쿼리 파라미터를 확인하고 빌링키 발급을 요청하세요.
결제수단 등록 요청이 실패하면 failUrl
로 이동합니다. 결제 실패 URL 리다이렉트를 살펴보세요.
자동결제 등록 성공 리다이렉트 URL에는 customerKey
, authKey
두 가지 쿼리 파라미터가 들어있습니다.
https://{ORIGIN}/success?customerKey=&authKey=
customerKey
: 고객 ID입니다.authKey
: 빌링키를 발급받을 때 사용하는 일회성 인증 키입니다. 최대 길이는 300자입니다.
리다이렉트 URL 쿼리 파라미터를 이용해 빌링키 발급 API를 호출할 수 있습니다.
requestBillingAuth()
메서드에 담아 보냈던 customerKey
값과 리다이렉트 URL에 있는 customerKey
값이 같은지 확인해보세요. 값이 같다면 빌링키를 발급받을 준비가 되었습니다.
카드 자동결제 빌링키 발급 요청 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": "개인"
}
}
빌링키와 고객을 특정하는 customerkey
를 매핑하여 서버에 저장하세요.
발급받은 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
에러가 발생합니다.
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": "카드"
}
응답 필드는 API 버전에 따라 조금씩 달라집니다. 돌아온 응답에 원하는 필드가 없다면 개발자센터에 설정된 API 버전을 확인한 뒤 필요한 버전으로 변경해보세요.