V0.0.4
Release Note
v.0.0.1 - 최초버전
v.0.0.2 - 1.6.0 버전 플러그인 업데이트
v.0.0.3 - 1.6.4 버전 플러그인 업데이트(브랜드페이 기능추가)
v.0.0.4 - 1.7.0 버전 플러그인 업데이트
결제위젯의 버블 결제플러그인 사용법 가이드 입니다.
관련 문의는 토스페이먼츠 개발자 디스코드 채널을 통해 진행하고 있습니다.
해당 URL로 접속하셔서 디스코드에 로그인 하신후 #연동개발-문의 에 문의하시면 답변드리도록 하겠습니다.
버블 결제위젯 플러그인을 통해서는 페이팔 및 기타 해외 간편 결제수단은 연동이 불가능합니다. 국내 결제수단 결제만 지원하므로 참고부탁드립니다.
플러그인 등록
플러그인 이름은 TossPayments-Widget-Basic 입니다.
버블 플러그인 탭에서 검색하신후 설치하시면 됩니다. 현재 최신 버전은 1.6.4 입니다.
플러그인 설정의 UserName 에는 토스페이먼츠 상점의 secretkey를 넣어주면 됩니다.
만약 상점 정보가 없으시다면(토스페이먼츠 PG를 사용하지 않는다면) 아래 값으로 테스트 해볼 수 있습니다.
secretKey : test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6
clientKey : test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm
결제 페이지 생성
플러그인을 추가하셨으면 element 에 “payment widget” 가 추가 되었을 겁니다.
이 element를 배치하시고, “위젯으로 결제” 버튼을 하나 추가합니다.
다만 Widget 은 고객이 선택하는 결제수단에 따라 layer의 높이가 동적으로 변경되므로 전체 페이지의 layout을 “column” 으로 처리하시는 것을 권장합니다.
“payment widget A” 의 Appearance 에 clientKey, customerKey, amount, variantKey, typeofcontent 를 설정합니다.
clientKey : 상점의 clientKey 를 넣어주시면 되고, 없으시다면
clientKey : test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm 를 사용하시면 됩니다.
customerKey : 사용자를 구분하는 key 값으로 상점에서 임의로 지정해주시면 됩니다.
amount : 결제할 결제금액입니다. 페이지내에서 변하지 않는 값을 넣어주셔야 합니다.
variantKey : 결제위젯 admin 에서 설정하신 varientKey 입니다.(특별히 설정한게 없으시다면 DEFAULT 로 넣으시기 바랍니다)
typeofcontent : 위젯이 사용되는 페이지에 type of content 를 사용한다면 체크해 주세요. 일반적으로 체크하지 않으시면 됩니다.
결제금액 업데이트
일부 케이스의 경우 페이지내에서 선택에 따라 결제위젯이 보이고 난 후에 결제금액이 변경되어야 하는 경우가 있습니다. 이경우 widget 에 amount 값을 변수로 설정하지 마시고 최소 결제금액인 100원으로 최초 설정한후 updateamount 를 이용해서 결제금액을 업데이트 해야 합니다.
결제금액이 변경되어야 하는 workflow 에서 Element Actions → payment widget → update amount a payment widget 을 선택한후 amount 값에 수정되어야 하는 결제금액을 넣어주시면 됩니다.
위젯으로 결제하기
“위젯으로 결제” 버튼의 click 에 workflow를 설정합니다.
Step 1> Element Actions → payment widget → setvalue a payment widget 를 선택하시고
아래와 같이 결제에 필요한 정보를 넣어주세요.
를 참고해 주시기 바랍니다.
Step 2> Element Actions → payment widget → requestpayments a payment widget 를 선택합니다.
이제 preview 로 가서 “결제하기” 버튼을 누르면 결제창이 뜨는지 확인합니다.
결제 승인 페이지 생성
결제승인 페이지는 결제 페이지와 동일 URL 에 widget-success 로 고정되어 있으므로 widget-success page 를 새로 만들어 줍니다.
생성된 widget-success page 에서 “Page is loaded” workflow를 추가하고
Step 1>에서 plugins → TossPayments Widget APIs - confirm payments 를 선택합니다.
paymentKey, orderId, amount 정보를 넣어야 하는데, 이 정보를
“Get data from page URL” 을 선택한후 parameter name 에 paymentKey, orderId, amount 세 가지를 맞춰 설정해 주세요.
Step2 에서는 API 호출하신 내용을 받아 보시도록 설정하시면 됩니다.
API 의 결과(결제 결과)는 Element Actions → set state 등을 통해 Result of step 1 을 이용해서 값을 넘겨주면
해당 값을 다른 element 를 통해 UI 에 표시해 줄 수 있습니다.
승인 API 호출시 발생하는 에러 처리하기
TossPayments Widget APIs - confirm payments 에 Error 처리가 가능하도록 하였습니다.
결제 성공 여부를 확인하시려면 API 호출의 결과에서 returned_an_error 를 체크하시면 됩니다.
실패내용은 raw body text 에 JSON 형태로 code 와 message 가 있어서 이걸 파싱해서 사용하시면 됩니다.
ex) {"code":"UNAUTHORIZED_KEY","message":"인증되지 않은 시크릿 키 혹은 클라이언트 키 입니다.","data":null}
결제위젯에서 현재 설정된 결제수단 확인하기
결제수단을 확인하기 위한 이벤트(버튼등) 에 workflow를 추가합니다.
Element Actions → payment widget → getselectedpayment a payment widget를 선택하세요.
해당 action이 발생한 후에 payment widget 의 state 에 현재 사용자가 선택한 결제 방식이 저장됩니다.
state 에서 정보를 가져와서 사용하시면됩니다.
getselectedpayment 가 실행된 순간에 선택된 정보가 state가 저장됩니다. 실시간으로 변경되지는 않습니다.
브랜드 페이 기능추가
플러그인 버전 1.6.4 에 브랜드페이 기능이 추가 되었습니다.
브랜드페이 기능을 사용하기 위해서는 실제 브랜드페이용 상점 ID(MID) 가 필요합니다. 계약관련 문의는 1544-7772 로 문의해 주시기 바랍니다.
브랜드페이 MID 가 있으시다면 우선 결제 위젯에 브랜드페이를 추가하는 작업이 필요합니다.
•
브랜드페이 기능을 사용하려면 버블에 Starter Plan 이상을 사용하셔야 합니다. backend workflow 기능이 필수입니다.
결제위젯에 브랜드페이 설정
토스페이먼츠 상점관리자에 접속하신후 좌측 결제위젯 → 결제 UI 설정을 선택하고 테스트 혹은 라이브 UI 추가하기를 선택합니다.
아래와 같은 화면에서 결제위젯에 표시하고자 하는 결제방식을 선택하면 됩니다. 일반 카드 결제와 브랜드페이를 사용한다면 첫번째, 두번째 체크박스를 선택하시면 됩니다.
다음을 누르면 MID 를 선택하는 화면이 보이고, 토스페이먼츠와 계약시 사용하신 국내 일반결제와 브랜드페이 MID 를 선택하고 다음을 누릅니다.
다음에 이 UI 를 지칭할 베리언트키를 입력합니다. 이 베리언트키는 버블 플러그인에서 해당 결제위젯 설정을 불러오기 위한 키값으로 사용됩니다. 여기서는 BRANDPAY 라고 넣어 봅니다.
설정하기를 누르면 아래와 같이 새로운 UI 가 추가 된것을 볼수 있습니다.
이제 연동한 결제위젯의 clientKey, secretKey 를 설정하고 variantKey 도 설정한 BRANDPAY 로 넣습니다.
REDIRECTURL 설정
브랜드페이 RedirectURL 을 구성하기 위해 backend workflow 를 추가합니다.
General 에 new API workflow 를 선택하고 이름을 AccessToken 이라고 입력합니다.
AccessToken workflow 에서 trigger workflow with : GET 으로 선택하고
Add new parameter 를 클릭하여 customerKey 와 code 라는 Key 2개를 입력해 줍니다.
Response Type 을 JSON Object 로 설정하시면 됩니다.
Step1 에 plugins → Brandpay- Get AccessToken 을 추가한 후, customerkey 에 customerKey, code 에 code 를 넣어주시면 됩니다.
Settings → API 에 가면 public API endpoints 에 workflow API root URL 이 있습니다.
https://xxxxxxx.bubbleapps.io/version-test/api/1.1/wf 형태일 것이고 이 뒤에 AccessToken 을 붙인
https://xxxxxxx.bubbleapps.io/version-test/api/1.1/wf/version-test/api/1.1/wf/AccessToken
를 redirectURL 로 사용할겁니다.
이제 토스페이먼츠 상점관리자에서 개발자 센터에 접속해 보시면 좌측에 브랜드페이 메뉴를 확인하실 수 있습니다. 브랜드페이 메뉴를 선택하고 브랜드페이용 상점 MID 를 선택하면 아래와 같이 redirectURL 을 입력하는 곳이 있습니다. 여기에 버블에서 생성한 redirectURL 을 넣어줍니다.
마지막으로 index 페이지에 추가한 결제위젯 플러그인에 설정한 variantKey 와 redirectURL 을 넣어주면 됩니다.
결제창 호출(requestPayment)시 발생하는 에러 처리하기
1.7.06 버전이상 플러그인 에서는 결제창 호출시에 발생하는 에러를 처리할 수 있습니다. 결제창을 사용자가 닫은 경우에도 이 방식으로 처리가 가능합니다.
paymentWidget 를 추가하신후, Workflow 에서 이벤트를 listening 하실수 있습니다.
아래와 같이 payment wiget에 catch 이벤트가 있습니다.
해당 이벤트는 결제창에서 오류가 발생하는 경우 호출되는 이벤트로 이때 payment widget 의 state에 code와 message 정보를 넘겨드리게 됩니다. 해당 값을 가져다가 원하시는 방식으로 표시해 주시면 됩니다.
