V0.0.1
Release Note
v.0.0.1 - 최초버전
자동결제 버블 결제플러그인 사용법 가이드 입니다.
관련 문의는 토스페이먼츠 개발자 디스코드 채널을 통해 진행하고 있습니다.
해당 URL로 접속하셔서 디스코드에 로그인 하신후 #연동개발-문의 에 문의하시면 답변드리도록 하겠습니다.
플러그인 등록
플러그인 이름은 TossPayments-Billing-Basic 입니다.
버블 플러그인 탭에서 검색하신후 설치하시면 됩니다.
플러그인 설정의 UserName 에는 토스페이먼츠 상점의 secretkey를
API KEY 에는 clientkey 를 넣어주면 됩니다.
만약 상점 정보가 없으시다면(토스페이먼츠 PG를 사용하지 않는다면) 아래 값으로 테스트 해볼 수 있습니다.
secretKey : test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R
clientKey : test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq
카드 등록 페이지 생성
플러그인을 추가하셨으면 element 에 “billing window” 가 추가 되었을 겁니다.
이 element를 배치하시고, “카드 등록하기” 버튼을 하나 추가합니다.
“카드 결제” 버튼의 click workflow 를 추가합니다.
Step 1> Element Actions → payment window → set value a billing window 를 선택하시고
아래와 같이 카드 등록에 필요한 정보를 넣어주세요. 사용자를 인식할수 있는 customerkey 와 사용자 이름 이메일 등을 넣어줍니다.
Step 2> Element Actions → payment window → Click a billing window 를 선택합니다.
이제 preview 로 가서 “카드 등록하기 ” 버튼을 누르면 결제창이 뜨는지 확인합니다.
빌링키 요청 페이지 생성
빌링키 요청 페이지는 카드등록 페이지와 동일 URL 에 billing-success로 고정되어 있으므로 billing-success page 를 새로 만들어 줍니다.
생성된 billing-success page 에서 “Page is loaded” workflow를 추가하고
Step 1>에서 plugins → TossPayments Billing APIs - issue Billkey 를 선택합니다.
authKey, customerKey 정보를 넣어야 하는데, 이 정보를
“Get data from page URL” 을 선택한후 parameter name 에 authKey, customerKey 세 가지를 맞춰 설정해 주세요.
Step2 에서는 API 호출하신 내용을 받아 보시도록 설정하시면 됩니다.
API 의 결과(결제 결과)는 Element Actions → set state 등을 통해 Result of step 1 을 이용해서 값을 넘겨주면
해당 값을 다른 element 를 통해 UI 에 표시해 줄 수 있습니다.
응답 값중에서 billingKey 와 customerKey 는 꼭 Data 로 저장해 주시고 이후에 결제가 필요할때 이 정보를 이용해서 결제를 해주셔야 합니다.
카드 등록창 호출시 발생하는 에러 처리하기
결제창을 사용자가 닫은 경우에도 이 방식으로 처리가 가능합니다.
paymentWindow 를 추가하신후, Workflow 에서 이벤트를 listening 하실수 있습니다.
아래와 같이 payment window에 errors 이벤트가 있습니다.
해당 이벤트는 결제창에서 오류가 발생하는 경우 호출되는 이벤트로 이때 payment window 의 state에 code와 message 정보를 넘겨드리게 됩니다. 해당 값을 가져다가 원하시는 방식으로 표시해 주시면 됩니다.
빌링키 발급 API 호출시 발생하는 에러 처리하기
TossPayments Billing APIs - issue BillKet 에 Error 처리가 가능하도록 하였습니다.
결제 성공 여부를 확인하시려면 API 호출의 결과에서 returned_an_error 를 체크하시면 됩니다.
실패내용은 error body code 와 error body message 를 사용하시면 됩니다.
빌링키로 결제 하기
이제 발급된 빌링키로 결제를 해보겠습니다. 토스페이먼츠에서는 빌링키를 발급하고 이 빌링키로 결제를 할수 있는 방법만 제공합니다. 언제 얼마를 결제할지는 해당 시점에 결제 요청을 해주시면 되기 때문에, 정기결제를 한다면 버블에서는 backend workflow 의 recurring event 를 사용하셔야 합니다.
만약 자동 결제를 하는 것이라면 결제가 필요한 특정 이벤트의 workflow 에서 빌링키를 이용한 결제요청 API 를 이용해서 결제 요청을 해주시면 됩니다.
이 가이드에서는 간단하게 일반결제를 이용해서 빌링 키를 이용한 결제를 해보겠습니다.
“빌링 결제하기” 라는 버튼을 만들고 click 에 workflow 를 설정합니다.
Plugin 에서 Billing APIs - payment by Billkey 를 선택하고 필요한 정보들을 넣습니다.
여기에서 billKey와 customerKey 는 빌링키 발급시에 응답으로 받아서 저장한 값을 사용해야 합니다.
두번째 스텝에서는 step 1의 결과에서 필요한 값을 받아서 state 나 data에 저장하고 필요하면 고객에게 결제완료를 보내주면 됩니다.
