체크사항
PG 식별자 | tosspayments |
빌링키 발급 가능한 수단 | 카드 |
빌링키 발급 가능한 환경 | 모바일 웹/앱(리디렉션) PC(팝업) API |
지원 기능 | 빌링키 발급 발급된 빌링키로 재결제 스케쥴 등록/취소 결제취소 |
지원불가 기능 | 빌링키 발급과 동시에 결제 |
JS SDK 버전 | v1.2.0 |
MID Version | 토스페이먼츠로부터 MID발급시 API version은 반드시 1.4 이어야 합니다. |
설정 방법
토스페이먼츠 정기결제(신모듈)는 아임포트 관리자콘솔 내 PG설정 후 반드시 아임포트 고객지원팀으로 이용요청을 주셔야 합니다.
•
1. 아임포트 관리자콘솔에서 회원가입
•
https://admin.iamport.kr 이메일 계정으로 회원가입 진행
2-1. 테스트 모드 설정
1) 결제창 방식
•
◦
PG상점아이디 (MID) : tvivarepublica2
◦
시크릿 키 : test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R
◦
클라이언트 키 : test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq
2) API 방식
•
◦
PG상점아이디 (MID) : tvivarepublica2
◦
시크릿 키 : test_sk_N5OWRapdA8dnpqZGAXVo1zEqZKLP
2-2. 실 모드 설정
1) 결제창 방식
•
◦
PG상점아이디 (MID) : 토스페이먼츠로부터 받은 상점아이디를 입력합니다.
◦
시크릿 키 : 토스페이먼츠로부터 받은 시크릿 키를 입력합니다.
◦
클라이언트 키 : 토스페이먼츠로부터 받은 클라이언트키를 입력합니다.
2) API 방식
•
◦
PG상점아이디 (MID) : 토스페이먼츠로부터 받은 상점아이디를 입력합니다.
◦
시크릿 키 : 토스페이먼츠로부터 받은 시크릿 키를 입력합니다.
3. 아임포트로 이용 설정요청하기 (테스트 & 실 모드 모두!)
PG설정을 마치셨다면 아임포트로 이용설정을 요청해주세요!
(예시)
토스페이먼츠 정기결제의 테스트모드 설정을 요청드려요!
- 아임포트 계정 : abc@abc.com
토스페이먼츠 정기결제의 테스트모드 설정을 요청드려요!
- 아임포트 계정 : 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