한 줄 요약
버블에서 페이액션과 연동해 무통장 입금을 등록하는 플러그인입니다.
후원 받은 커피는 더 많은 플러그인을 만드는 원동력이 됩니다.
Intro
1. Why?
국내에서 결제 관리가 필요할 때, 토스 페이먼츠 외 다른 선택지가 필요한 분들이 있으리라 생각해 구현했습니다. 페이액션은 무통장 입금 관리 서비스로, 인터넷뱅킹에서 SMS통지서비스만 신청하고 손쉽게 연동할 수 있습니다.
2. ChangeLog
1.0.0
•
[POST] order : 주문
•
[POST] order : 주문-매칭제외
Core
1. Instruction
버블과 페이액션을 완벽히 연동하기 위해선 (1) 페이액션에서 API 기능을 제공하는 플랜과 (2) 버블에서 Backend API를 제공하는 플랜을 사용해야 합니다.
매칭 완료 웹훅 기능은 플러그인에서 사용하지 않고, 별도 세팅을 하셔야 합니다. 세팅 방식은 해당 페이지의 [튜토리얼] 섹션에 정리했습니다.
2. Related Docu
플러그인 페이지
데모 링크
에디터 링크
3. API Call
a. payaction_order : 주문
무통장 입금 주문건을 생성하고, 페이액션에게 전달합니다.
Input
field | type | Required | 설명 |
apiKey | str | | 발급 받은 apiKey를 입력해주세요. |
secretKey | str | | 발급 받은 secretKey를 입력해주세요 |
mall_id | str | | 상점 번호를 입력해주세요 |
order_number | str | | 주문 번호를 입력해주세요. |
order_amount | number | | 주문 금액을 입력해주세요. |
order_date | date | | 주문일시를 입력해주세요,
*Dates 속성 ISO_8601 Format
YYYY-MM-DDTHH:MM:SS+09:00 |
billing_name | str | | 입금자명을 입력해주세요.
해당 입금자명으로 자동 매칭 시, 매칭 여부를 판단합니다. |
orderer_name | str | | 주문자명을 입력해주세요. |
orderer_phone_number | str | | 주문자 전화번호를 입력해주세요. |
orderer_email | str | | 주문자 이메일을 입력해주세요 |
return
field | type | 설명 |
body status | str | 결과 상태를 반환합니다. (ex. Fail, success) |
body message | str | 결과값을 반환합니다. |
error status_code | number | 에러 코드를 반환합니다. (ex. 200) |
error status_message | str | 에러 메시지를 반환합니다. |
error_body | str | 에러 메시지의 원본(raw)을 반환합니다. |
retunred_an_error | boolean | 에러의 존재 유무를 반환합니다. |
b. payaction_order : 주문-매칭제외
특정 주문건의 매칭을 제외합니다.
Input
field | type | Required | 설명 |
apiKey | str | | 발급 받은 apiKey를 입력해주세요. |
secretKey | str | | 발급 받은 secretKey를 입력해주세요 |
mall_id | str | | 상점 번호를 입력해주세요 |
order_number | str | | 주문 번호를 입력해주세요. |
return
field | type | 설명 |
body status | str | 결과 상태를 반환합니다. (ex. Fail, success) |
body message | str | 결과값을 반환합니다. |
error status_code | number | 에러 코드를 반환합니다. (ex. 200) |
error status_message | str | 에러 메시지를 반환합니다. |
error_body | str | 에러 메시지의 원본(raw)을 반환합니다. |
retunred_an_error | boolean | 에러의 존재 유무를 반환합니다. |
Tutorial
1. 버블에서 무통장 입금건 등록하기
해당 플러그인을 사용하기 위해서 아래 조건이 필요합니다.
페이액션에 상점 및 계좌 연동
페이액션에서 API 발급 및 등록
페이액션에 상점 및 계좌 연동
해당 부분은 페이액션에 회원가입을 진행하고, 상점을 개설한 후에 페이액션의 가이드를 따라서 완료하시면 됩니다.
참고로 연동할 상점의 URL은 현재 버블에서 배포한 서비스의 URL을 입력하시면 됩니다. 만약 커스텀 URL을 사용하고 계시다면, 커스텀 URL을 입력해야 합니다.
페이액션에서 API 발급 및 등록
상점 및 계좌 연동 후, 페이액션의 대시보드에서 [API 설정]에 들어옵니다. 여기서 API를 발급 받아야 합니다. 참고로 API 기능은 프로 플랜(24.04.07 기준)에서만 제공합니다. 여기서 보이는 [API Key], [Secret Key], [상점id]값을 플러그인에서 활용할 겁니다.
무통장 입금건 등록하기
버블 에디터로 이동하고, 플러그인 설정 페이지에서 방금 확인한 값을 모두 입력합니다.
유저의 주문 요청 로직을 처리하는 워크플로우에서 [payaction - order : 주문] 액션 이벤트를 생성하고 값을 입력합니다. [order_number]는 주문의 id 값과 같은 역할을 하므로, 버블에서 order table의 id 필드 값을 그대로 활용하는 게 좋습니다.
field | type | Required | 설명 |
apiKey | str | | 발급 받은 apiKey를 입력해주세요. |
secretKey | str | | 발급 받은 secretKey를 입력해주세요 |
mall_id | str | | 상점 번호를 입력해주세요 |
order_number | str | | 주문 번호를 입력해주세요. |
order_amount | number | | 주문 금액을 입력해주세요. |
order_date | date | | 주문일시를 입력해주세요,
*Dates 속성 ISO_8601 Format
YYYY-MM-DDTHH:MM:SS+09:00 |
billing_name | str | | 입금자명을 입력해주세요.
해당 입금자명으로 자동 매칭 시, 매칭 여부를 판단합니다. |
orderer_name | str | | 주문자명을 입력해주세요. |
orderer_phone_number | str | | 주문자 전화번호를 입력해주세요. |
orderer_email | str | | 주문자 이메일을 입력해주세요 |
해당 액션 이벤트가 실행되면, 페이액션의 대시보드에서 아래와 같이 등록됩니다.
2. 버블에서 매칭 완료 확인하기
페이액션에서는 웹훅 기능을 통해 입금이 완료됐는지를 알려줍니다. 다만 플러그인에서 웹훅 URL을 별도로 설정할 수 없기에 해당 부분은 버블 에디터에서 직접 구현하셔야 합니다.
웹훅 URL 등록하기
에디터에서 [Setting] > [API]로 이동하고, [Enable workflow API and backend workflows]를 활성화합니다.
그러면 페이지 네비게이션에서 [Backend workflows] 선택란이 생성됩니다. 여기서 웹훅을 등록할 겁니다.
새로운 API를 생성하고, API 이름을 입력합니다. 이제 해당 API의 URL을 웹훅으로 사용할 겁니다.
API의 URL은 아래처럼 구성됩니다.
•
Dev : https://{serviceURL}/version-test/api/{Ver}/wf/{API workflow name}
•
Live : https://{ServiceURL}/api/{Ver}/wf/{API workflow name}
페이액션에서 위의 사용하고자 한 URL을 입력합니다.
웹훅 동작 시, 액션 이벤트 설정하기
이제 매칭이 완료될 때마다, 버블에서 작동시킬 로직을 만들면 됩니다. 앞서 만든 백엔드 API에서 아래와 같이 설정을 진행합니다. 그래야 웹훅에서 전달 받은 데이터를 확인할 수 있습니다.
field | type | 설명 |
mall_id | str | 상점 번호를 받아옵니다. |
order_number | str | 주문 번호를 받아옵니다. |
order_status | str | 주문 상태를 받아옵니다. |
processing_date | date | 처리일시를 받아옵니다.
*Dates 속성 ISO_8601 Format
YYYY-MM-DDTHH:MM:SS+09:00 |
그리고 워크플로우의 액션 이벤트로 관련된 주문 데이터를 처리하는 로직을 등록하면 됩니다.
후원 받은 커피는 더 많은 플러그인과 자료를 만드는 원동력이 됩니다.
