Search
Duplicate

토스페이먼츠_정기결제(신 모듈)

결제수단
정기결제
해외결제
속성

체크사항

PG 식별자
tosspayments
빌링키 발급 가능한 수단
카드
빌링키 발급 가능한 환경
모바일 웹/앱(리디렉션) PC(팝업) API
지원 기능
빌링키 발급 발급된 빌링키로 재결제 스케쥴 등록/취소 결제취소
지원불가 기능
빌링키 발급과 동시에 결제
JS SDK 버전
v1.2.0
MID Version
토스페이먼츠로부터 MID발급시 API version은 반드시 1.4 이어야 합니다.

설정 방법

1. 포트원 관리자콘솔에서 회원가입

포트원 관리자콘솔 이메일 계정으로 회원가입 진행

2-1. 테스트 모드 설정

1) 결제창 방식 & API 방식 (동일)

포트원 관리자 콘솔 > 결제연동 > 테스트 연동관리 > 결제대행사 설정 토스페이먼츠 - 토스페이먼츠 > 토스페이먼츠 정기결제 테스트 설정하기(클릭) > 자동으로 key가 입력된 상태 + 저장

2-2. 실 모드 설정

1) 결제창 방식 & API 방식 (동일)

포트원 관리자 콘솔 > 결제연동 > 테스트 연동관리 > 결제대행사 설정 토스페이먼츠 - 토스페이먼츠 > 토스페이먼츠 정기결제 테스트 설정하기(클릭) > 자동으로 key가 입력된 상태 + 저장
채널속성 : 결제 로 체크합니다.
결제채널이름 : 채널을 구분하기 위한 명칭을 설정합니다.
PG상점아이디 (MID) : 토스페이먼츠로부터 받은 상점아이디를 입력합니다.
시크릿 키 : 토스페이먼츠로부터 받은 시크릿 키를 입력합니다.
클라이언트 키 : 토스페이먼츠로부터 받은 클라이언트키를 입력합니다.

3. 토스페이먼츠_신모듈_API 설정하기

토스페이먼츠 상점관리자 로그인 > 개발자센터 > 내 개발정보 > 테스트/라이브 각각 설정 > API 버전 “2022-07-27” 설정

유의사항

빌링키 발급

신규 파라미터 customer_id 추가

토스페이먼츠 - 신모듈은 PG사 결제창 방식(IMP.requets_pay 함수 호출)API 방식 모두로 빌링키 발급이 가능하며 그 방법(참고: 정기결제 연동하기 > STEP1. 카드 등록 및 빌링키 발급받기)에 있어 다른 PG사와 큰 차이가 없습니다. 다만, 추가적으로 제공하는 파라미터가 있는데 바로 구매자 식별자customer_id입니다.
customer_id가 왜 생긴걸까요? 현재 아임포트로 빌링키 발급 요청시, 결제 수단을 식별할 수 있는 customer_uid값을 필수로 보내야합니다. 이 값은 말 그대로 결제 수단을 식별하기 때문에 아래와 같은 개념으로 동작합니다.
구매자
결제수단
customer_uid
빌링키
최아임
현대카드
cuid_1
billkey_1
신한카드
cuid_2
billkey_2
김포트
신한카드
cuid_3
billkey_3
우리카드
cuid_4
billkey_4
즉, 구매자 : 결제수단 = 1 : N 그리고 결제수단 : customer_uid : 빌링키 = 1 : 1 : 1 입니다.
하지만 아임포트는 구매자에 대한 정보는 갖고 있지 않기 때문에 해당 결제 수단(= customer_uid = 빌링키)이 어떤 구매자와 매핑되는지 알 수 없고 이는 오롯이 가맹점에서 관리해주셔야 합니다.
이로 인하여 토스페이먼츠 - 신모듈은 구매자와 결제수단을 매핑할 수 있도록 구매자를 식별할 수 있는 customer_id 값을 빌링키 발급시 받고 있습니다.
그럼 어떻게 지정해야 할까요?
빌링키 발급시 customer_id 라는 파라메터를 함께 지정하여 보내주셔야 합니다.
단, customer_id는 optional이기 때문에 보내지 않아도 동작은 하지만 보내지 않으면 (아임포트가 빌링키 발급 요청시마다 customer_id에 uuid값을 채번하기 때문에) 구매자와 결제수단은 매칭되지 않으니 유념하시기 바랍니다.
결제창 방식 빌링키 발급 요청
IMP.request_pay({ ...중략 pg: 'tosspayments', amount: 0, // 어떤 값을 보내도 무시 되고 아임포트 DB엔 0으로 기록 됨 customer_uid: 'cuid_1', customer_id: 'uid_1', }, function(response) { ...중략 });
JavaScript
API 방식 빌링키 발급 요청
axios.post( `/subscribe/customers/cuid_1`, { ...중략 pg: 'tosspayments', amount: 0, // 어떤 값을 보내도 무시 되고 아임포트 DB엔 0으로 기록 됨 customer_id: 'uid_1', } ).then(() => { ...중략 }).catch(() => { ...중략 });
JavaScript
응답 파라미터에 customer_id 추가
앞서 안내드린 바와 같이 빌링키 발급시 customer_id 파라미터가 추가됨 에따라, 빌링키 발급 ( POST /subscribe/customers/{customer_uid}) 및 발급 된 빌링키 조회(GET /subscribe/customers/{customer_uid})시 응답되는 데이터에 아래와 같이 customer_id값이 추가됩니다.
GET /subscribe/customers/cuid_1
GET /subscribe/customers/cuid_1 { ...중략 card_code: '361', customer_uid: 'cuid_1', customer_id: 'uid_1', }
JavaScript