자동결제(빌링) API로 연동하기

✅ 토스페이먼츠 API만으로 자동결제를 연동하고 구독 결제 서비스를 만들어보세요. (서버 투 서버)

✅ 구매자의 카드를 처음 한 번 등록할 때 본인인증을 마치고 빌링키를 발급하면, 별도의 인증 없이 간편하게 빌링키로 계속 결제할 수 있습니다.

✅ API로 자동결제를 연동하면 본인인증은 직접 구현해야 합니다. 결제창 방식으로 연동하면 토스페이먼츠에서 휴대폰 본인인증을 제공합니다.

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

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

큰 흐름은 다음과 같습니다.

• 빌링키 발급 API 요청 (Server): API로 빌링키를 발급하고 데이터베이스에 저장하세요. 빌링키 발급 전 본인인증은 직접 구현해야 합니다.
• 빌링 결제 승인 요청 (Server): API로 발급한 빌링키로 원하는 주기, 시점에 자동결제를 실행하세요. 스케줄링 기능은 직접 구현해야 합니다. 스케줄링 예제를 참고하세요.

API로 연동하면 UI는 직접 구현해야 합니다. 결제창 방식으로 연동하면 토스페이먼츠에서 카드 등록창과 본인인증 기능을 제공합니다.

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

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

인코딩된 값을 Basic 인증 헤더에 넣고 카드 번호, 카드 유효기간, 카드 소유자의 생년월일, 카드 비밀번호 등을 빌링키 발급 요청 API 본문에 포함하세요.

카드 번호와 카드 유효기간은 필수 파라미터입니다. 카드 정보는 빌링키를 발급할 때만 한 번 사용되고, 이후에는 카드 정보 대신 발급한 빌링키로 결제를 실행합니다. 토스페이먼츠와 계약할 때 요청하면 비밀번호, 카드 소유자의 생년월일 정보도 빌링키 발급을 위한 필수 파라미터로 추가할 수 있습니다.

• customerKey 필수 · string
  

  구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다.

• cardNumber 필수 · string
  

  카드 번호입니다. 최대 길이는 20자입니다.

  * 테스트 환경에서는 카드 번호의 앞 여섯 자리(BIN 번호)만 유효해도 자동결제가 등록됩니다. 라이브 환경에서는 전체 카드 번호가 유효해야 등록됩니다.

• cardExpirationYear 필수 · string
  

  카드 유효 연도입니다.

• cardExpirationMonth 필수 · string
  

  카드 유효 월입니다.

• customerIdentityNumber 필수 · string
  

  카드 소유자 정보입니다. 생년월일 6자리(YYMMDD) 혹은 사업자등록번호 10자리가 들어갑니다.

• cardPassword string
  

  카드 비밀번호 앞 두 자리입니다.

• customerName string
  

  구매자명입니다. 최대 길이는 100자입니다.

• customerEmail string
  

  구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.

• vbv object
  

  해외 카드 결제의 3DS 인증에 사용합니다. 3DS 인증 결과를 전송해야 되면 필수입니다.

• cavv string
  

  3D Secure 인증 세션의 인증 값입니다.

• xid string
  

  트랜잭션 ID입니다.

• eci string
  

  3DS 인증 결과의 코드 값입니다.

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

구매자를 특정하는 customerKey와 빌링키를 매핑해서 서버에 저장하세요. 한 번 발급된 빌링키는 다시 조회할 수 없습니다. 저장한 키값으로 자동결제를 요청해주세요.

빌링키의 유효기간은 빌링키와 연결된 카드 유효기간과 같습니다. 발급된 빌링키를 삭제하는 기능은 제공하지 않습니다. 발급된 빌링키가 더 이상 필요하지 않으면 데이터베이스에서 삭제하고 더 이상 사용하지 않으면 됩니다. 혹시 누군가가 빌링키 정보를 알고 있더라도 빌링키와 매핑된 customerKey를 모른다면 결제가 불가능합니다. 빌링키를 사용한 결제는 빌링키를 발급할 때 같이 전달된 customerKey와 매핑이 되어있기 때문에, 결제 요청을 할 때 빌링키와 customerKey가 같이 전달되어야 결제가 진행됩니다.

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

토스페이먼츠에서는 자체적으로 스케줄링 기능을 제공하지 않습니다. 따라서 직접 스케줄링 기능을 구현해서 원하는 주기, 시점에 결제를 실행해야 합니다.

만약 Node.js 애플리케이션에 스케줄링 로직을 추가하려면, node-cron과 같은 패키지를 사용할 수 있습니다. 이 패키지를 사용하면 스케쥴을 정의하고 그에 따라 특정 작업을 자동으로 실행할 수 있습니다. 각 언어나 프레임워크에서 제공하는 스케줄링 기능을 사용하세요.

먼저 node-cron 패키지를 설치해야 합니다. 프로젝트의 루트 디렉토리에서 다음 명령어를 실행하세요.

이제 node-cron을 사용하여 매월 1일에 자동결제를 진행하는 스케쥴러를 설정할 수 있습니다. 아래 코드는 기존 routes/index.js 파일에 스케쥴러를 추가하는 방법을 보여줍니다:

위 코드는 매월 1일에 billingKey`를 사용하여 자동결제를 진행하는 스케쥴러입니다. 이러한 방식으로 스케줄링 로직을 추가하면, 매월 1일마다 자동으로 지정된 결제가 진행됩니다. 실제 서비스에서는 에러 처리, 로깅, 데이터베이스와의 통신 등이 추가로 필요할 수 있습니다.

billingKey가 발급되는 동시에 자동결제 승인 API를 호출하면 카드 자동결제 등록과 결제가 한 번에 완료됩니다.

요청이 승인되면 빌링키를 발급할 때 등록했던 카드로 결제되고, card 객체가 포함된 응답이 돌아옵니다.

카드 자동결제 API를 자세히 알아보세요

카드 자동결제 API를 직접 실행해보세요