퀵계좌이체 자동결제(빌링) 연동하기

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

✅ 토스페이먼츠 결제창 SDK로 자동결제(빌링)를 연동할 수 있습니다.

✅ 자동결제는 정기 구독형 서비스에만 사용할 수 있어요. 비정기 결제 서비스에는 정책적으로 사용이 제한되니 유의하세요.

자동결제는 API 개별 연동 키로 연동하세요.

토스페이먼츠에 회원가입하기 전이라면, 다음 문서 테스트 키로 연동할 수 있어요. 토스페이먼츠에 회원가입했다면, 로그인 후 내 테스트 키로 결제를 연동하고 개발자센터에서 테스트 결제내역을 확인하세요.

퀵계좌이체 자동결제를 실행하려면 먼저 구매자의 계좌를 등록해야 됩니다.

SDK를 추가한 뒤 클라이언트 키를 사용해 객체를 초기화합니다. 초기화된 객체로 requestBillingAuth('계좌이체')를 실행하면 구매자의 계좌를 등록할 수 있는 퀵계좌이체창이 열려요. 아래 예제 코드를 실행해서 퀵계좌이체 등록창을 띄워보세요.

퀵계좌이체를 처음 사용하는 구매자라면 가입 이후에 계좌를 등록합니다. 퀵계좌이체를 이미 사용하고 있는 구매자는 로그인한 다음에 자동결제에 사용하고 싶은 계좌를 선택합니다.

계좌 등록 요청 결과를 확인할 차례입니다. 계좌 등록 요청이 성공하면 requestBillingAuth()의 파라미터로 설정했던 성공 리다이렉트 URL(successUrl)로 이동합니다. 성공 리다이렉트 URL 뒤에 customerKey, authKey 두 가지 쿼리 파라미터가 들어있습니다.

• customerKey: 상점에서 만든 구매자의 고유 ID입니다.
• authKey: 빌링키를 발급할 때 사용하는 일회성 인증 키입니다. 최대 길이는 300자입니다.

requestBillingAuth()의 파라미터로 설정했던 customerKey 값과 리다이렉트 URL에 있는 customerKey 값이 같은지 확인해보세요. 값이 같다면 쿼리 파라미터를 이용해 빌링키 발급 API를 호출해주세요.

계좌 등록 요청이 실패하면 다음과 같이 실패 리다이렉트 URL(failUrl)로 이동합니다. 에러 목록을 확인하세요.

이제 빌링키를 발급할 차례예요. 구매자가 등록한 계좌 정보는 저장할 수 없기 때문에 암호화해서 결제를 실행할 때 대신 사용합니다.

먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다. 시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. :을 빠트리지 않도록 주의하세요.

아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.

인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문도 추가하세요. 앞 단계에서 성공 리다이렉트 URL로 받은 authKey, customerKey 값을 자동결제 빌링키 발급 요청 API의 요청 본문으로 보냅니다.

API 호출 결과로 HTTP 200 OK를 받으면 빌링키 발급 성공입니다. 빌링키를 구매자를 특정하는 customerKey와 매핑해서 서버에 저장하세요. 한 번 발급된 빌링키는 다시 조회할 수 없습니다. 앞으로 해당 구매자의 billingKey, customerKey가 있으면 언제든 결제를 낼 수 있어요. 빌링키가 노출되어도 빌링키와 매핑된 customerKey를 모른다면 결제가 불가능합니다.

이제 발급받은 빌링키로 원하는 결제 주기에 자동결제 승인 API를 호출하세요. 토스페이먼츠에서는 자체적으로 스케줄링 기능을 제공하지 않아요. 따라서 가맹점에서 직접 스케줄링 기능을 구현해서 원하는 주기, 시점에 자동결제 승인 API를 실행해야 합니다. 스케줄링 예시는 구독 결제 서비스 구현하기 (2) 스케줄링 아티클에서 확인하세요.

발급한 billingKey를 자동결제 승인 API의 Path 파라미터로 추가해주세요. 요청 본문에는 주문 정보와 함께 customerKey를 넣어주세요.

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

응답으로 받은 Payment 객체가 아래 예시와 다르다면 API 버전을 확인하세요. 개발자센터의 API 키 메뉴에서 설정된 API 버전을 확인하고 변경할 수 있어요. API 버전 업데이트 사항은 릴리즈 노트에서 확인할 수 있습니다.

구매자가 만약에 퀵계좌이체 서비스에서 탈퇴하면 발급받은 빌링키는 더 이상 유효하지 않고 해당 빌링키로 자동결제를 승인할 수 없어요. 아래 웹훅을 연동해서 퀵계좌이체 탈퇴, 빌링키 삭제 알림을 실시간으로 받아보세요.

구매자가 퀵계좌이체 서비스에서 탈퇴하거나 자동결제 해지(빌링키 삭제) API가 호출하면 전송됩니다.

• eventType string
  

  웹훅 이벤트 타입입니다.

• createdAt string
  

  웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

• data string
  

  웹훅 이벤트 데이터입니다.

• billingKey string
  

  삭제된 빌링키입니다. 삭제된 빌링키로 더 이상 자동결제를 실행할 수 없습니다.