VibeFox Moyasar for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

WooCommerce: 8.0 이상이며, 설치되어 활성화되어 있어야 합니다. 이전 버전의 WooCommerce를 사용하면 플러그인이 알림을 표시하고 로드되지 않습니다.

PHP: 8.0 이상.

통화: 쇼핑몰 또는 주문의 통화는 SAR, AED, USD, EUR, KWD, BHD 또는 OMR이어야 합니다. 그 외의 통화에서는 체크아웃에서 해당 결제 수단이 표시되지 않습니다.

Moyasar 계정: Moyasar 계정의 비밀 API 키(테스트용 및 실서비스용)가 필요합니다. 비밀 키만 사용됩니다. 결제는 Moyasar 페이지에서 이루어지므로 공개 키(publishable key)는 필요하지 않습니다. Moyasar Dashboard에서 웹훅을 설정하는 것을 권장합니다(설정 항목 참고).

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서 사용할 수 있습니다.

설치

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

2. Activate를 클릭합니다.

3. 설정을 엽니다: WooCommerce > Settings > Payments > Moyasar > Manage. 또는 플러그인 페이지에서 플러그인 이름 아래의 Settings를 클릭합니다.

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

5. Moyasar 비밀 키를 붙여 넣고 저장합니다. 설정에 표시된 URL과 공유 비밀 값으로 Moyasar Dashboard에서 웹훅을 설정합니다(설정 항목 참고).

6. Enable/Disable을 켭니다. 테스트 모드에서 테스트 주문을 한 후 Test mode 체크 표시를 해제합니다.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Moyasar. 페이지 제목에는 TEST MODE 또는 LIVE 배지가 표시됩니다. 입력란 위에서 현재 모드에 비밀 키가 없거나(이 경우 체크아웃에서 결제 수단이 숨겨짐) 쇼핑몰 통화를 지원하지 않으면 페이지가 경고하며, 테스트 모드가 켜져 있는 동안에는 Test mode is active: payments are simulated, no money is charged.를 표시합니다. 결제 수단 목록에서는 현재 모드에 비밀 키가 입력될 때까지 Moyasar가 설정 필요 상태로 표시됩니다. 저장할 때 플러그인은 공개 키, 다른 모드의 키 또는 공백이 포함된 키를 거부하고, 이전 값을 유지하며 그 이유를 표시합니다. 게이트웨이가 활성화되어 있지만 현재 모드의 비밀 키가 비어 있으면 이를 경고합니다.

일반

Enable/Disable: Enable Moyasar는 결제 수단을 켜거나 끕니다. 기본값: 끔.

Title: 고객이 체크아웃에서 보는 결제 수단 이름입니다. 기본값: Pay with Moyasar.

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. 테스트 모드에서는 체크아웃에 (Test mode: no real payment is made.)가 추가됩니다.

API 키

비밀 키는 Moyasar Dashboard > Settings > API Keys에서 복사합니다. 테스트 키와 실서비스 키는 별도입니다. 테스트 모드는 테스트 키만, 실서비스 모드는 실서비스 키만 사용합니다.

Test mode: Enable test mode는 테스트용 비밀 키를 사용합니다. 결제는 시뮬레이션되며 실제 청구는 이루어지지 않습니다. 기본값: 켬. 실제 결제를 받으려면 끄고 실서비스 비밀 키를 사용하십시오.

Test secret key: 테스트 모드의 비밀 키입니다. sk_test_로 시작합니다.

Live secret key: 실서비스 모드의 비밀 키입니다. sk_live_로 시작합니다.

결제 알림(웹훅)

웹훅은 권장 사항이며 필수는 아닙니다. 주문은 고객이 쇼핑몰로 돌아왔을 때와, 인보이스가 결제되면 Moyasar가 쇼핑몰로 자동 전송하는 인보이스 알림을 통해서도 확인됩니다. 웹훅은 돌아오기 전에 브라우저를 닫은 고객까지 포함하며, Moyasar Dashboard에서 이루어진 환불도 알려 줍니다. Moyasar Dashboard > Settings > Webhooks에서 이 섹션의 URL과 공유 비밀 값을 사용해 웹훅을 추가하십시오. HTTP 메서드는 POST입니다.

Webhook URL: 읽기 전용으로 표시되며 Copy 버튼이 있습니다. 형식은 다음과 같습니다: https://your-site/wp-json/moyasar_p/v1/webhook. HTTP 메서드: POST.

Webhook shared secret: Moyasar 웹훅의 Shared secret과 같은 값을 입력합니다. 비워 둔 채 저장하면 무작위 비밀 값이 생성되며, 그 다음 Show를 클릭해 Moyasar에 복사합니다. 올바른 공유 비밀 값이 없는 웹훅은 거부됩니다.

웹훅에 대해 다음 이벤트를 선택하십시오:

웹훅이나 알림은 그 자체로 신뢰되지 않습니다. 플러그인은 각 항목에 대해 주문 모드의 비밀 키로 Moyasar API에서 인보이스를 조회하고, 그 인보이스가 이 주문을 위해 생성되었는지 확인합니다. 같은 Moyasar 계정의 다른 연동에서 이루어진 결제는 무시됩니다.

주문

Status after payment: 결제가 확인된 후 설정될 주문 상태입니다. 상태는 즉시 설정되며 별도의 상태 변경이 한 번 더 일어나지 않습니다.

고급

Debug log: Log API calls and notifications는 상세 내용을 WooCommerce > Status > Logs에 기록합니다. 소스는 wcp_moyasar_payment_gateway입니다. 오류는 항상 기록됩니다. API 키, 카드 정보, 고객 정보는 기록되지 않습니다. 기본값: 끔.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. 주문에 저장된 결제 정보(Moyasar 인보이스 및 결제 ID)는 보존되므로 환불을 계속 추적할 수 있습니다. 기본값: 끔.

체크아웃

고객은 결제 수단(기본값은 Pay with Moyasar)을 선택하고 주문합니다. 플러그인은 주문 금액에 대해 주문 통화로 Moyasar 인보이스를 생성하고, 고객을 결제 페이지로 보냅니다. 고객은 그곳에서 Moyasar 계정에서 활성화된 모든 방식(예: mada, Visa, Mastercard, Apple Pay, STC Pay)으로 결제합니다. 인보이스에는 Order, 주문 번호, 쇼핑몰 사이트 이름이 표시됩니다.

주문은 Moyasar가 확인한 후에만 결제 완료로 표시됩니다. 플러그인은 Moyasar API에서 인보이스를 조회하여 결제가 완료되었는지, 이 주문에 속하는지, 주문 금액과 통화가 정확히 일치하는지 확인합니다. 결제 후 고객은 쇼핑몰의 주문 접수 페이지로 돌아갑니다. 고객이 결제하지 않고 돌아온 경우(예: 결제 페이지의 뒤로 가기 버튼 사용), 체크아웃 또는 Pay for order 페이지로 돌아가며 다음 메시지 중 하나를 보게 됩니다: The payment at Moyasar was not completed. You can try again or choose another payment method., Your Moyasar payment was declined or has expired. Please try again or choose another payment method., 또는 결제를 아직 확인할 수 없는 경우 We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again.

고객은 결제되지 않은 주문을 다시 결제할 수 있습니다. 주문의 열려 있는 결제 페이지가 여전히 같은 금액과 통화를 가지고 있으면 그 페이지를 재사용합니다. 주문 금액이 변경된 경우 이전 결제 페이지는 취소되고 새 페이지가 생성되므로, 이전 페이지로는 더 이상 결제할 수 없습니다. 이전 인보이스가 이미 결제되었다면 새 결제를 만드는 대신 주문이 확인됩니다.

Moyasar가 결제를 시작할 수 없는 경우 고객에게는 The Moyasar payment service is not responding. Please try again in a few minutes.와 같은 짧은 메시지가 표시되며, 다른 결제 수단을 선택할 수 있습니다. 세부 내용은 로그에 기록됩니다.

이 결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다.

이 플러그인은 Moyasar 페이지에서의 일회성 결제만 지원합니다. 자체 체크아웃에는 카드 입력 양식이 없고, 저장된 카드나 토큰화, WooCommerce Subscriptions, 별도의 승인 및 매입(capture)도 지원하지 않습니다.

주문 및 환불

주문 상태

Pending payment: 인보이스는 생성되었지만 고객이 아직 결제하지 않았습니다. 주문 메모에는 인보이스 ID, 금액, 모드가 표시됩니다.

Processing, Completed or On hold: 결제가 확인되었습니다. 상태는 Status after payment 설정을 따릅니다. 주문 메모에는 결제가 확인된 방식(웹훅, 인보이스 알림, 고객의 복귀 또는 체크아웃), 인보이스 ID, 결제 ID, 결제 수단이 표시됩니다. 거래 ID는 Moyasar 결제 ID입니다.

결제 후 On hold: Moyasar가 주문 합계와 다른 금액 또는 통화를 보고했거나(이 경우 주문은 결제 완료로 표시되지 않음), 주문이 취소된 후에 인보이스가 결제되었습니다. 주문 메모에 이유가 설명되어 있습니다. Moyasar Dashboard에서 결제를 확인한 후 주문을 처리하거나 결제를 환불하십시오.

결제 전 On hold: Moyasar가 결제를 검토 중입니다. Moyasar가 결정하면 주문이 업데이트됩니다.

Failed: 결제되지 않은 주문의 최신 인보이스가 실패했거나, 만료되었거나, 취소되었습니다. 고객은 다시 결제를 시도할 수 있습니다.

Cancelled: 고객, 귀하 또는 WooCommerce 재고 보류 시간 초과로 주문이 취소되었습니다. 주문의 열린 Moyasar 인보이스도 함께 취소되므로 더 이상 결제할 수 없습니다.

결제, 취소 또는 환불된 주문은 이후의 이벤트로 변경되지 않습니다. 이미 결제된 주문의 두 번째 인보이스가 결제되면(예: 두 개의 브라우저 탭에서) 주문은 다시 변경되지 않습니다. 메모는 중복 결제를 Moyasar Dashboard에서 환불하도록 요청합니다.

환불

주문을 열고 Refund를 클릭한 후 금액을 입력하고 Refund via Pay with Moyasar를 클릭합니다(이 버튼은 결제 수단 제목을 사용합니다). Moyasar 결제가 있는 주문에는 전액 및 부분 환불이 지원됩니다. 2시간 이내에 이루어진 카드 결제의 전액 환불은 취소(void, 정산 전 취소)로 전송되며, 그 외에는 환불로 처리됩니다. 환불은 결제가 이루어진 모드(테스트 또는 실서비스)의 비밀 키를 사용하므로 해당 키가 설정되어 있어야 합니다. 환불하기 전에 플러그인은 Moyasar에서 결제의 통화, 상태, 아직 환불 가능한 금액을 확인합니다. Moyasar가 환불을 받아들이지 않으면 WooCommerce에 오류가 표시되며 환불은 기록되지 않습니다. 환불 또는 취소가 성공하면 주문 메모에 추가됩니다.

Moyasar Dashboard에서 이루어진 환불과 취소는 웹훅을 통해 전달됩니다. Moyasar가 WooCommerce보다 많은 환불 금액을 표시하면 주문에 메모가 추가됩니다. 이들은 자동으로 WooCommerce 환불로 기록되지 않습니다. 필요하면 Refund via Pay with Moyasar를 사용하지 않고 WooCommerce에서 수동 환불을 생성하십시오.

라이선스 키

이 플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Payments > Moyasar 페이지 상단에 있습니다. License key에 키를 붙여 넣고 Activate를 클릭합니다. 블록에는 상태(예: 라이선스가 유효한 날짜)와 도메인이 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하며, Remove key로 이 사이트에서 키를 제거합니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

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

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

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

문제 해결

체크아웃에 Moyasar가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 비밀 키가 있는지(테스트 모드는 Test secret key, 실서비스 모드는 Live secret key), 쇼핑몰 또는 주문 통화가 SAR, AED, USD, EUR, KWD, BHD 또는 OMR인지 확인하십시오. 키가 없거나 통화가 지원되지 않으면 설정 페이지에 경고가 표시됩니다.

결제는 완료되었지만 주문이 Pending payment 상태로 남아 있음: 확인 정보가 쇼핑몰에 도달하지 않았습니다. 웹훅을 설정하십시오. Moyasar Dashboard에서 웹훅이 있는지, 그 URL이 설정의 Webhook URL과 정확히 같은지, 메서드가 POST인지, 네 가지 이벤트가 모두 선택되었는지, 공유 비밀 값이 Webhook shared secret과 같은지 확인하십시오. 고객이 쇼핑몰로 돌아오거나 같은 주문을 다시 결제하려고 할 때도 주문이 확인됩니다.

웹훅이 Unauthorized로 응답함: Moyasar의 공유 비밀 값이 Webhook shared secret과 다릅니다. Show를 클릭해 값을 복사한 후 Moyasar의 웹훅에 붙여 넣으십시오.

웹훅이 Webhook secret not configured로 응답함: 공유 비밀 값과 함께 설정이 아직 저장되지 않았습니다. 설정을 저장해 값을 생성한 후 Moyasar에 복사하십시오.

웹훅이 Key not configured로 응답함: 주문이 비밀 키가 비어 있는 모드(테스트 또는 실서비스)에서 결제되었습니다. 해당 키를 입력하십시오.

웹훅이 Verification failed 또는 Try again later로 응답함: Moyasar API에서 인보이스를 읽지 못했거나, 같은 시점에 다른 요청이 주문을 업데이트하고 있었습니다. Moyasar가 웹훅을 다시 시도합니다.

키와 관련된 저장 시 오류: 공개 키(pk_...) 또는 다른 모드의 키가 붙여 넣어졌습니다. 이전 값이 유지되었습니다. 테스트 키는 sk_test_, 실서비스 키는 sk_live_로 시작합니다.

고객이 주문할 때 오류를 봄: Debug log를 켜고 WooCommerce > Status > Logs에서 소스 wcp_moyasar_payment_gateway를 확인하십시오. This payment method is temporarily unavailable. Please choose another payment method or contact us.는 보통 잘못되었거나 없는 비밀 키를 뜻합니다. A payment for this order has already been received and is being reviewed. Please contact us instead of paying again.는 해당 주문에 검토가 필요한 결제된 인보이스가 이미 있다는 뜻입니다.

주문이 On hold after payment 상태임: 주문 메모를 읽으십시오. 결제된 금액 또는 통화가 주문과 달랐거나, 주문이 취소된 후 결제가 들어왔습니다. 주문을 처리하거나 결제를 환불하십시오.

환불이 실패함: 메시지를 읽으십시오. 결제가 다른 모드에서 이루어졌다면 그 모드의 비밀 키를 입력하십시오. 금액이 Moyasar에서 아직 환불 가능한 금액보다 크다면, 예를 들어 Moyasar Dashboard에서 결제의 일부가 이미 환불된 것입니다. Moyasar가 환불된 금액을 확인하지 않았다면, 다시 시도하기 전에 Moyasar Dashboard에서 결제를 확인하십시오.

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

제거

플러그인을 비활성화해도 모든 데이터는 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화한 후 삭제하십시오. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정과 로그는 Clean uninstall이 켜져 있었던 경우에만 삭제됩니다. 그렇지 않으면 나중에 다시 설치할 때를 위해 보존됩니다. 기존 주문은 결제 메모와 거래 ID를 유지합니다.

Moyasar는 각 소유자의 상표입니다. 이 플러그인은 Moyasar와 제휴하지 않으며 Moyasar의 승인을 받지 않았습니다.