Version 2
새로 나온
자동결제(빌링) API로 연동하기
API만으로 구매자의 카드 정보를 등록하고 자동결제를 연동하는 서버 투 서버 방법을 알아보세요.
구매자의 카드를 처음 한 번 등록할 때 본인인증을 마치고 빌링키를 발급하면, 별도의 본인인증 없이 간편하게 빌링키로 계속 결제할 수 있습니다. API로 자동결제를 연동하면 본인인증은 직접 구현해야 합니다. 결제창 방식으로 연동하면 토스페이먼츠에서 휴대폰 본인인증을 제공합니다.
* 자동결제는 추가 리스크 검토 및 계약 후 사용할 수 있습니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.
API 키 준비하기
개발자센터의 API 키 메뉴에서 API 개별 연동 키 > 시크릿 키를 확인하세요.
토스페이먼츠와 전자결제 계약 전이어도 회원가입하면 나만의 테스트 상점 키를 확인하고 테스트 결제내역, 웹훅 등 기능을 사용할 수 있어요. 로그인한 상태라면 코드의 키 값이 테스트 상점 키입니다. 로그인하지 않아도 문서 테스트 키로 테스트 연동할 수 있어요.
토스페이먼츠와 전자결제를 완료했다면 개발자센터의 API 키 메뉴에서 자동결제(빌링)로 계약된 상점아이디(MID)를 선택한 다음에 시크릿 키를 확인하세요. 테스트 키와 라이브키의 차이점도 확인하고 연동을 시작하세요.
* 자동결제는 추가 리스크 검토 및 계약 후 사용할 수 있습니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.1. 빌링키 발급하기
자체 UI를 제작해서 구매자의 카드 번호, 카드 유효기간, 생년월일을 입력받고 본인인증을 받으세요. 이제 구매자의 카드 정보로 빌링키를 발급할 준비가 됐어요. 빌링키는 카드번호, 유효기간, CVC 등 결제 정보를 암호화한 값이에요. 구매자의 카드 정보 대신 빌링키를 사용해서 구독 결제 시점에 결제를 내는 원리입니다.
구매자의 카드 정보를 빌링키 발급 API의 요청 본문에 포함하세요. 카드 번호와 카드 유효기간은 필수 파라미터입니다. 토스페이먼츠와 계약할 때 비밀번호, 카드 소유자의 생년월일 정보도 필수 파라미터로 추가할 수도 있습니다.
또 다른 필수 파라미터는 customerKey인데요. customerKey는 내 상점에서 구매자를 특정하는 값이에요. 각 구매자에게 고유한 무작위 값을 발급해주세요.
시크릿 키와 :을 base64로 인코딩해서 Basic 인증 헤더를 아래와 같이 만들어주세요. :을 빠트리지 않도록 주의하세요. 비밀번호가 없다는 것을 알리기 위해 시크릿 키 뒤에 콜론을 추가합니다.
시크릿 키는 클라이언트, GitHub 등 외부에 노출되면 안 됩니다.
시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. :을 빠트리지 않도록 주의하세요.
아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.
자동결제 계약이 안 되어 있는 클라이언트 키로 연동하면 발생합니다. 자동결제 계약이 되어있는 클라이언트 키를 사용하거나 토스페이먼츠 구매자센터(1544-7772, support@tosspayments.com)로 문의해주세요.
인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문도 추가하세요. 앞 단계에서 리다이렉트 URL로 받은 authKey, customerKey 값을 카드 자동결제 빌링키 발급 요청 API의 요청 본문으로 보냅니다.
2. 빌링키 저장하기
API 호출 결과로 HTTP 200 OK를 받으면 빌링키 발급 성공입니다.
빌링키를 구매자를 특정하는 customerKey와 매핑해서 서버에 저장하세요. 한 번 발급된 빌링키는 다시 조회할 수 없습니다. 앞으로 해당 구매자의 billingKey, customerKey가 있으면 언제든 결제를 낼 수 있어요. 빌링키가 노출되어도 빌링키와 매핑된 customerKey를 모른다면 결제가 불가능합니다.
빌링키의 유효기간은 빌링키와 연결된 카드 유효기간과 같습니다. 발급된 빌링키를 삭제하는 기능은 제공하지 않습니다. 발급된 빌링키가 더 이상 필요하지 않으면 데이터베이스에서 삭제하고 사용하지 않으면 됩니다.
새로운 카드 정보로 빌링키를 다시 발급하세요. 별도로 빌링키를 갱신하는 과정은 없습니다.
3. 빌링키로 자동결제 실행하기
이제 발급받은 빌링키로로 원하는 결제 주기에 카드 자동결제 승인 API를 호출하세요. 토스페이먼츠에서는 자체적으로 스케줄링 기능을 제공하지 않아요. 따라서 가맹점에서 직접 스케줄링 기능을 구현해서 원하는 주기, 시점에 자동결제 승인 API를 실행해야 합니다. 스케줄링 예시는 구독 결제 서비스 구현하기 (2) 스케줄링 아티클에서 확인하세요.
발급한 billingKey를 카드 자동결제 승인 API의 Path 파라미터로 추가해주세요. 요청 본문에는 주문 정보와 함께 customerKey를 넣어주세요.
customerkey와 매핑되지 않은 billingKey를 사용하면 발생합니다.
다음 결제일에 구독을 취소한 구매자의 빌링키, 구매자키로 카드 자동결제 승인 API를 호출하지 않으면 됩니다.
카드 자동결제 승인 API를 호출할 때 amount 파라미터를 변경된 결제 금액으로 설정하면 됩니다.
카드 자동결제 승인 API를 호출하는 주기를 변경해주세요.
4. 결제 완료 후 응답 확인하기
API 호출 결과로 HTTP 200 OK를 받으면 결제 승인 성공입니다. 상태 코드와 함께 Payment 객체가 응답으로 돌아옵니다. 자동결제는 card 필드가 포함되어 있어야 합니다.
응답으로 받은 Payment 객체가 아래 예시와 다르다면 API 버전을 확인하세요. 개발자센터의 API 키 메뉴에서 설정된 API 버전을 확인하고 변경할 수 있어요. API 버전 업데이트 사항은 릴리즈 노트에서 확인할 수 있습니다.