Search
Duplicate

토스페이먼츠 정기결제

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

체크사항

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

설정 방법

토스페이먼츠 정기결제(신모듈)는 아임포트 관리자콘솔 내 PG설정 후 반드시 아임포트 고객지원팀으로 이용요청을 주셔야 합니다.
아임포트 고객지원팀 문의처
메일 : cs@iamport.kr
유선통화 : 1670-5176
채널톡 : ‘여기’ 클릭

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

https://admin.iamport.kr 이메일 계정으로 회원가입 진행

2-1. 테스트 모드 설정

1) 결제창 방식

아임포트 관리자 콘솔 > 결제연동 > 테스트 연동관리 > 결제대행사 설정 토스페이먼츠 - 토스페이먼츠 > 자동으로 입력된 상점정보 우측하단에 ‘저장’ 버튼 클릭
PG상점아이디 (MID) : tvivarepublica2
시크릿 키 : test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R
클라이언트 키 : test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq

2) API 방식

아임포트 관리자 콘솔 > 결제연동 > 테스트 연동관리 > 결제대행사 설정 토스페이먼츠 - 토스페이먼츠API > 자동으로 입력된 상점정보 우측하단에 ‘저장’ 버튼 클릭
PG상점아이디 (MID) : tvivarepublica2
시크릿 키 : test_sk_N5OWRapdA8dnpqZGAXVo1zEqZKLP

2-2. 실 모드 설정

1) 결제창 방식

아임포트 관리자 콘솔 > 결제연동 > 실 연동관리 > 결제대행사 설정 토스페이먼츠 - 토스페이먼츠 > 상점정보 입력
PG상점아이디 (MID) : 토스페이먼츠로부터 받은 상점아이디를 입력합니다.
시크릿 키 : 토스페이먼츠로부터 받은 시크릿 키를 입력합니다.
클라이언트 키 : 토스페이먼츠로부터 받은 클라이언트키를 입력합니다.

2) API 방식

아임포트 관리자 콘솔 > 결제연동 > 실 연동관리 > 결제대행사 설정 토스페이먼츠 - 토스페이먼츠API > 상점정보 입력
PG상점아이디 (MID) : 토스페이먼츠로부터 받은 상점아이디를 입력합니다.
시크릿 키 : 토스페이먼츠로부터 받은 시크릿 키를 입력합니다.

3. 아임포트로 이용 설정요청하기 (테스트 & 실 모드 모두!)

PG설정을 마치셨다면 아임포트로 이용설정을 요청해주세요!
(예시) 토스페이먼츠 정기결제의 테스트모드 설정을 요청드려요! - 아임포트 계정 : abc@abc.com
토스페이먼츠 정기결제의 실 모드 설정을 요청드려요! - 아임포트 계정 : abc@abc.com

유의사항

빌링키 발급

신규 파라미터 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