Search

토스페이먼츠(신 모듈) 정기결제 실운영모드 설정방법

Tags

체크사항

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

설정 방법

[실 모드 PG설정 진행순서]

1.
아임포트 관리자콘솔 > 로그인 > 내 ‘토스페이먼츠/정기결제’ 선택 후 신청서 제출
2.
토스페이먼츠 홈페이지 > 호스팅사 “아임포트(정기결제)” 선택 후 신청
3.
테스트모드 연동으로 카드사 심사까지 마친 뒤, 실제 상점정보 발급 (토스페이먼츠 → 가맹점)
정기결제_결제창 방식 PG모듈 설정
아임포트 관리자 콘솔 > 결제연동 > 테스트/실 연동관리 > 결제대행사 설정 및 추가 “실연동 / 토스페이먼츠/ 토스페이먼츠” > 결제채널 이름, 실상점정보 세팅 후 우측하단에 ‘저장’ 버튼 클릭
결제채널 이름
상점정보만으로는 채널(PG)의 성격을 파악하기 어려워 채널(PG)의 이름을 설정하는 용도로 구분하기 위한 필수설정 값으로 임의값로 설정이 가능합니다. 단, 숫자, 공백, 글자, _, - 만 가능)
정기결제_API 방식 PG모듈 설정
아임포트 관리자 콘솔 > 결제연동 > 테스트/실 연동관리 > 결제대행사 설정 및 추가 “실연동 / 토스페이먼츠/ 토스페이먼츠 API ” > 결제채널 이름, 실상점정보 세팅 후 우측하단에 ‘저장’ 버튼 클릭
결제채널 이름
상점정보만으로는 채널(PG)의 성격을 파악하기 어려워 채널(PG)의 이름을 설정하는 용도로 구분하기 위한 필수설정 값으로 임의값로 설정이 가능합니다. 단, 숫자, 공백, 글자, _, - 만 가능)
4.
토스페이먼츠_신모듈_API 설정하기
토스페이먼츠 상점관리자 로그인 > 개발자센터 > 내 개발정보 > 테스트/라이브 각각 설정 > API 버전 “2022-07-27” 설정

유의사항

1. 빌링키 발급

신규 파라미터 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: 'user_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
{ ...중략 card_code: '361', customer_uid: 'cuid_1', customer_id: 'uid_1, }
JavaScript
추가적으로 기술지원이 필요하신 경우 아임포트 기술지원팀 (support@iamport.kr ) 으로 문의 주시기 바랍니다.