VibeFox Flutterwave for WooCommerce — 도움말

요구 사항

WordPress: 5.8 이상.

WooCommerce: 7.0 이상이 설치되고 활성화되어 있어야 합니다. WooCommerce 없이는 플러그인을 활성화할 수 없습니다.

PHP: 8.0 이상. 이전 PHP 버전에서는 플러그인을 활성화할 수 없습니다.

Flutterwave 계정: Flutterwave 대시보드의 Settings, API keys에서 계정의 비밀 키를 가져와야 합니다. 테스트 모드는 FLWSECK_TEST-…, 운영 모드는 FLWSECK-…를 사용합니다. 비밀 키만 사용하며 공개 키와 암호화 키는 필요하지 않습니다. 원하는 비밀 해시로 웹훅도 설정해야 합니다(구성 참조).

통화: 주문은 항상 주문 통화로 청구됩니다. 플러그인은 국가나 통화를 제한하지 않습니다. 계정이 통화를 지원하지 않으면 Flutterwave가 오류를 표시합니다.

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서 작동합니다.

설치

1. WordPress에서 Plugins > Add New > Upload Plugin으로 이동하여 플러그인 ZIP 파일을 선택하고 Install Now를 클릭합니다. FTP로 wcp_flutterwave_payment 폴더를 /wp-content/plugins/에 업로드할 수도 있습니다.

2. Activate를 클릭합니다.

3. WooCommerce > Settings > Payments > Flutterwave > Manage에서 설정을 열거나 플러그인 페이지에서 플러그인 이름 아래의 Settings를 클릭합니다.

4. 페이지 상단 라이선스 영역에 VibeFox 라이선스 키를 입력하고 Activate를 클릭합니다.

5. 비밀 키를 입력하고 Flutterwave 대시보드에서 웹훅을 설정한 다음 동일한 비밀 해시를 플러그인에 입력합니다(구성 참조).

6. Enable/Disable를 켜고 테스트 모드에서 결제를 시험한 다음 Live mode를 선택합니다.

구성

모든 설정은 WooCommerce > Settings > Payments > Flutterwave 한 페이지에 있습니다. 입력란 위에 Live mode: real payments are accepted. 또는 Test mode: no real money is charged.가 표시됩니다. 현재 모드의 비밀 키가 비어 있거나, 운영 모드에서 운영 키 입력란에 테스트 키(FLWSECK_TEST-…)가 있거나, 테스트 모드에서 테스트 키 입력란에 운영 키(FLWSECK-…)가 있으면 경고합니다. 문제가 수정될 때까지 체크아웃에서 결제 방법이 숨겨집니다. 웹훅 비밀 해시가 설정되지 않은 경우에도 경고합니다. 이때 웹훅은 거부되며 고객이 쇼핑몰로 돌아올 때만 결제가 확인됩니다. 결제 방법 목록에서는 현재 모드에 비밀 키가 설정될 때까지 Flutterwave가 설정 필요로 표시되고, 테스트 모드에서는 테스트 모드 배지가 표시됩니다.

일반

Enable/Disable: Enable Flutterwave Payment는 결제 방법을 켜거나 끕니다. 기본값: off.

Title: 고객이 체크아웃에서 보는 결제 방법 제목입니다. 기본값: Flutterwave.

Description: 고객이 체크아웃에서 보는 텍스트입니다. 기본값: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

API 키

Flutterwave 대시보드의 Settings, API keys에서 비밀 키를 복사합니다. 테스트 모드와 운영 모드는 서로 다른 키를 사용합니다.

Live mode: Accept real payments (uncheck for test mode). 테스트 모드는 테스트 비밀 키를 사용하며 실제 금액을 청구하지 않습니다. 운영 모드는 운영 비밀 키를 사용합니다. 기본값: off(테스트 모드).

Test Secret Key: Flutterwave 테스트 비밀 키(FLWSECK_TEST-...).

Live Secret Key: Flutterwave 운영 비밀 키(FLWSECK-...).

웹훅

웹훅은 고객이 쇼핑몰로 돌아오지 않아도 결제를 확인합니다. Flutterwave 대시보드의 Settings, Webhooks에서 테스트 모드와 운영 모드 각각에 이 영역의 Webhook URL과 원하는 비밀 해시를 입력합니다. URL은 https://your-site/wc-api/flw_p_webhook/ 형식입니다. 플러그인은 다음 이벤트에 반응합니다.

다른 이벤트는 무시합니다.

Secret Hash: 웹훅의 비밀 해시입니다. Flutterwave 대시보드의 웹훅 설정 값과 일치해야 합니다. Flutterwave는 모든 웹훅과 함께 이 값을 보냅니다. 유효한 비밀 해시가 없는 웹훅은 거부됩니다. 웹훅이 없으면 고객이 쇼핑몰로 돌아올 때만 결제가 확인됩니다.

결제

Payment Options: Flutterwave 페이지에 표시할 결제 방법을 쉼표로 구분합니다. 예: card, banktransfer, ussd, mobilemoney. 계정에서 활성화된 모든 방법을 표시하려면 비워 둡니다. 저장할 때 목록이 정리됩니다.

Autocomplete Orders: Automatically mark orders as completed after successful payment. 활성화하면 결제 후 한 번의 상태 변경으로 주문을 처리 중 대신 완료됨으로 설정합니다. 기본값: off.

고급

Debug log: Log Flutterwave API events for debugging을 WooCommerce > Status > Logs에 기록하며 소스는 wcp_flutterwave_payment입니다. 오류는 항상 기록합니다. 키와 고객 데이터는 기록하지 않습니다. 기본값: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. 플러그인을 비활성화해도 아무것도 삭제되지 않습니다. 주문에 저장된 결제 데이터는 항상 유지됩니다. 기본값: off.

체크아웃

고객은 결제 방법(기본값 Flutterwave)을 선택하고 주문합니다. 테스트 모드에서는 체크아웃에 TEST MODE - no real payments will be processed.가 표시됩니다. 유효한 청구 이메일이 필요합니다. 플러그인은 주문 통화로 주문 총액에 대한 Flutterwave 결제를 생성하며 고객의 이메일, 전화번호, 이름과 쇼핑몰 사이트 이름 및 로고를 포함하여 고객을 Flutterwave 체크아웃 페이지로 보냅니다. 고객은 그곳에서 계정에 활성화된 방법(또는 Payment Options에 나열한 방법)으로 결제합니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. Flutterwave가 웹훅이나 고객 복귀 시 서버 측 확인을 통해 결제를 확인한 후에만 주문이 결제 완료로 표시됩니다. 은행 송금, USSD 또는 모바일 머니가 대기 중인 경우처럼 결제가 아직 확인되지 않았다면 주문 접수 페이지에 Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed.가 표시됩니다. 입금되었지만 결제 금액이 주문과 일치하지 않는 등의 이유로 플러그인이 검토를 위해 주문을 보류 중으로 설정했다면 페이지에 Your payment was received and your order is being reviewed. We will contact you if anything is needed.가 표시됩니다.

결제가 거절되면 고객은 체크아웃(또는 Pay for order 페이지)으로 돌아가며 Your payment was declined. You can try again or choose another payment method.가 표시됩니다. 고객이 Flutterwave 페이지에서 취소하면 체크아웃에서 생성한 주문은 취소되고 수동으로 생성한 주문은 미결제로 유지되며 Payment was cancelled. You can try again or choose another payment method. 메시지가 표시됩니다. 결제가 완료되지 않았다면 메시지는 The payment was not completed. You can try again or choose another payment method.입니다.

고객은 미결제 주문에 대해 다시 결제할 수 있습니다. 시도마다 고유한 참조가 있으며 이전 결제 링크를 나중에 결제해도 받습니다. Flutterwave가 결제를 시작할 수 없으면 고객에게 Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. 같은 짧은 메시지가 표시됩니다.

결제 방법은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. WooCommerce High-Performance Order Storage(HPOS)와 호환됩니다. 고객에게 표시되는 텍스트는 프랑스어로 번역되어 있습니다.

플러그인은 일회성 결제만 받습니다. 쇼핑몰 사이트 내 인라인 또는 모달 체크아웃, 저장된 카드, 구독, 분할 지급이나 결제 플랜은 지원하지 않습니다. 호스팅된 결제 링크는 Flutterwave API로 취소할 수 없으므로 주문의 이전 링크로도 결제할 수 있습니다.

주문 및 환불

주문 상태

Pending payment: 고객이 Flutterwave로 이동했지만 아직 결제하지 않았거나 결제가 Flutterwave에서 아직 대기 중입니다.

Processing or Completed: 결제가 확인되었습니다. Autocomplete Orders가 켜져 있으면 완료됨을 사용합니다(가상 다운로드 상품만 포함된 주문도 WooCommerce 기본 동작에 따라 완료됨이 됩니다). 주문 메모에는 금액, 결제 방법, Flutterwave 참조, 거래 및 모드가 표시됩니다. 주문의 거래 ID는 Flutterwave 참조입니다.

On hold after payment: 확인한 금액 또는 통화가 주문과 일치하지 않거나 주문이 취소된 후 결제가 도착했습니다. 메모에 이유가 설명됩니다. 주문을 이행하거나 결제를 환불하세요. 재전송된 웹훅이 환불되거나 취소된 주문을 다시 열지는 않습니다.

Failed: Flutterwave가 대기 중인 주문의 최근 결제 시도를 실패 또는 취소로 보고했습니다. 메모에 이유가 표시됩니다.

Cancelled: 고객이 체크아웃에서 주문한 후 Flutterwave 페이지에서 취소했거나, 쇼핑몰 관리자가 주문을 취소했거나, WooCommerce 재고 보류 시간이 만료되어 주문이 취소되었습니다.

이미 결제된 주문에 두 번째 결제가 들어오면 주문은 변경되지 않습니다. Flutterwave 대시보드에서 중복 결제를 환불하라는 메모가 추가됩니다.

환불

주문을 열고 Refund를 클릭한 다음 금액을 입력하고 Refund via Flutterwave를 클릭합니다. 전액 및 부분 환불을 지원합니다. 환불은 결제 당시 모드(테스트 또는 운영)의 비밀 키로 전송되므로 해당 키가 설정되어 있어야 합니다. Flutterwave가 환불을 거부하면 WooCommerce에 오류가 표시되고 환불은 기록되지 않습니다. 성공한 환불은 환불 ID와 상태(완료 또는 Flutterwave가 보고한 상태로 시작됨)와 함께 주문 메모에 추가됩니다.

Flutterwave 대시보드에서 처리한 환불은 WooCommerce와 동기화되지 않습니다. 필요하면 Refund via Flutterwave를 사용하지 않고 WooCommerce에서 수동 환불을 생성하세요.

라이선스 키

플러그인은 vibefox.net의 VibeFox 라이선스 키로 작동합니다. 라이선스 영역은 WooCommerce > Settings > Payments > Flutterwave 상단에 있습니다. License key에 키를 붙여 넣고 Activate를 클릭합니다. 이 영역에 라이선스 유효 기간과 도메인 등의 상태가 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하며, Remove key로 이 사이트에서 키를 제거합니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

키 하나는 도메인 하나에서 작동합니다. 사이트에서 키를 제거해도 해당 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하세요.

활성 키가 없으면 체크아웃에서 고객에게 Flutterwave가 표시되지 않습니다. 그래도 결제가 시작되면 고객에게 This payment method is not available. Please choose another one.이 표시됩니다. 로그인한 쇼핑몰 관리자는 (unlicensed — visible to admins only) 표시와 함께 계속 결제 방법을 볼 수 있으므로 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 페이지와 WooCommerce 페이지에 알림이 표시됩니다. 기존 주문은 영향을 받지 않습니다. 이미 시작된 결제는 계속 확인되고 환불도 작동합니다.

라이선스가 만료되어도 플러그인은 계속 작동하지만 업데이트와 지원을 받으려면 갱신해야 합니다. 상태는 백그라운드에서 자동으로 다시 확인됩니다.

문제 해결

체크아웃에 Flutterwave가 표시되지 않음: 라이선스가 활성 상태이고 Enable/Disable가 켜져 있으며 현재 모드의 비밀 키가 입력되어 모드와 일치하는지 확인하세요. 테스트 모드에는 테스트 키(FLWSECK_TEST-…), 운영 모드에는 운영 키(FLWSECK-…)를 사용합니다. 그렇지 않으면 설정 페이지에 경고가 표시됩니다.

결제되었지만 주문이 Pending payment 상태로 유지됨: 웹훅이 작동하지 않습니다. Flutterwave 대시보드에서 사용 중인 모드(테스트 또는 운영)의 웹훅 URL이 설정에 표시된 것과 정확히 일치하고 비밀 해시가 플러그인의 Secret Hash와 같은지 확인하세요. 대기 중인 은행 송금, USSD, 모바일 머니는 Flutterwave가 확인할 때까지 대기 상태로 유지됩니다. Debug log를 켜고 WooCommerce > Status > Logs에서 소스 wcp_flutterwave_payment를 확인하세요.

웹훅이 Invalid hash 또는 Secret hash not configured 응답을 반환함: Flutterwave 대시보드의 비밀 해시가 플러그인의 값과 다르거나 플러그인에 값이 없습니다. 두 곳에 같은 값을 입력하세요.

웹훅이 Verification failed 또는 Busy, retry later 응답을 반환함: 결제 확인을 위해 Flutterwave에 연결할 수 없거나, 거래가 아직 표시되지 않거나, 다른 요청이 주문을 업데이트하고 있었습니다. Flutterwave가 웹훅을 재시도합니다.

고객에게 Payment gateway is not properly configured 표시: 현재 모드의 비밀 키가 없거나 다른 모드의 키입니다.

고객에게 We could not match this payment to an order 표시: 반환 링크에 이 쇼핑몰에서 만들지 않은 참조가 포함되어 있습니다. 고객에게 청구되었다면 Flutterwave 대시보드에서 결제를 찾으세요.

Flutterwave 페이지에 오류 표시: Flutterwave 계정이 주문 통화나 선택한 결제 옵션을 지원하지 않을 수 있습니다.

결제 후 주문이 On hold 상태임: 주문 메모를 읽으세요. 확인한 금액 또는 통화가 주문과 일치하지 않거나 주문이 취소된 후 결제가 도착했습니다. 주문을 이행하거나 결제를 환불하세요.

모드 관련 메시지와 함께 환불 실패: 테스트 또는 운영 모드에서 결제되었지만 해당 모드의 비밀 키가 설정되지 않았습니다. 키를 입력하고 다시 시도하세요.

라이선스 영역에 오류 표시: 영역의 메시지를 따르세요. 예를 들어 키가 이미 다른 도메인에서 사용 중이면 vibefox.net 계정에서 슬롯을 해제하고 Check now를 클릭하세요. 사이트 주소가 바뀌었다면 Check now를 클릭하여 새 도메인에 키를 활성화하세요. 라이선스 서버에 연결할 수 없으면 플러그인은 마지막으로 알려진 상태로 계속 작동합니다.

개발자를 위한 플러그인 문서에는 flw_p_payment_request(Flutterwave에 보내는 데이터), flw_p_currency_decimals(통화 소수 자릿수), flw_p_icon(체크아웃 아이콘) 필터가 나열되어 있습니다.

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화한 다음 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 제거됩니다. 게이트웨이 설정과 로그는 Delete data on uninstall이 켜져 있었을 때만 제거됩니다. 그렇지 않으면 나중에 재설치할 수 있도록 유지됩니다. 주문에 저장된 Flutterwave 데이터는 항상 유지됩니다. 기존 주문의 결제 메모와 거래 ID도 유지됩니다.

Flutterwave는 해당 소유자의 상표입니다. 이 플러그인은 Flutterwave와 제휴 관계가 없으며 Flutterwave의 승인을 받지 않았습니다.