체크사항
PG 식별자 | tosspayments |
빌링키 발급 가능한 수단 | 카드 |
빌링키 발급 가능한 환경 | 모바일 웹/앱(리디렉션) PC(팝업) API |
지원 기능 | 빌링키 발급 발급된 빌링키로 재결제 스케쥴 등록/취소 결제취소 |
지원불가 기능 | 빌링키 발급과 동시에 결제 |
JS SDK 버전 | v1.2.0 |
MID Version | 토스페이먼츠로부터 MID발급시 API version은 반드시 1.4 이어야 합니다. |
테스트환경 인증번호 | 000000 입력
(테스트환경에서는 인증문자가 발송되지 않습니다. 000000 을 입력해주세요) |
설정 방법
[실 모드 PG설정 진행순서]
1.
포트원 관리자콘솔 > 로그인 > 내 ‘토스페이먼츠/정기결제’ 선택 후 신청서 제출
2.
토스페이먼츠 홈페이지 > 호스팅사 “포트원(정기결제)” 선택 후 신청
3.
4.
토스페이먼츠_신모듈_API 설정하기
•
정기결제_’결제창’ 방식 PG모듈 설정
포트원 관리자 콘솔 > 결제연동 > 테스트/실 연동관리 > 결제대행사 설정 및 추가 “실연동 / 토스페이먼츠/ 토스페이먼츠” > 결제채널 이름, 실상점정보 세팅 후 우측하단에 ‘저장’ 버튼 클릭
※ 결제채널 이름
상점정보만으로는 채널(PG)의 성격을 파악하기 어려워 채널(PG)의 이름을 설정하는 용도로 구분하기 위한 필수설정 값으로 임의값로 설정이 가능합니다.
단, 숫자, 공백, 글자, _, - 만 가능)
정기결제_’API’ 방식 PG모듈 설정
포트원 관리자 콘솔 > 결제연동 > 테스트/실 연동관리 > 결제대행사 설정 및 추가 “실연동 / 토스페이먼츠/ 토스페이먼츠 API ” > 결제채널 이름, 실상점정보 세팅 후 우측하단에 ‘저장’ 버튼 클릭
※ 결제채널 이름
상점정보만으로는 채널(PG)의 성격을 파악하기 어려워 채널(PG)의 이름을 설정하는 용도로 구분하기 위한 필수설정 값으로 임의값로 설정이 가능합니다.
단, 숫자, 공백, 글자, _, - 만 가능)
유의사항
1. 빌링키 발급
신규 파라미터 customer_id 추가
•
토스페이먼츠 - 신모듈은 PG사 결제창 방식(IMP.request_pay 함수 호출)과 API 방식 모두로 빌링키 발급이 가능하며 그 방법(참고: 정기결제 연동하기)에 있어 다른 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
복사
2. 결제 연동-참고 매뉴얼
<포트원_v1 연동 가이드>
<포트원_v2 연동 가이드>
추가적으로 기술지원이 필요하신 경우 포트원 기술지원팀 (support@portone.io)으로 문의 주시기 바랍니다.
