VibeFox PayFast for WooCommerce — 도움말

요구 사항

WordPress: 6.2 이상.

WooCommerce: 8.0 이상, 설치 및 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인이 활성화되지 않습니다.

PHP: 8.0 이상.

통화: 남아프리카공화국 랜드(ZAR), WooCommerce > Settings > General에서 설정합니다. PayFast는 랜드로만 정산합니다. 최소 주문 금액은 R5.00입니다.

PayFast 계정: PayFast 대시보드의 Settings > Developer Settings에서 확인할 수 있는 계정의 가맹점 ID(Merchant ID)와 가맹점 키(Merchant Key). 패스프레이즈 설정을 강력히 권장하며, PayFast에서 패스프레이즈를 설정했다면 같은 패스프레이즈를 플러그인에도 입력해야 합니다. 테스트에는 PayFast 샌드박스 자격 증명이 필요합니다.

접근 가능한 사이트: 결제 알림 URL은 인터넷에서 접근할 수 있어야 하며, 유지 보수 모드, 기본 인증 또는 방화벽 차단이 없어야 합니다.

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

설치

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

2. Activate를 클릭합니다.

3. WooCommerce > Settings > General에서 쇼핑몰 통화를 남아프리카공화국 랜드로 설정합니다.

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

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

6. 가맹점 ID, 가맹점 키, 패스프레이즈를 입력합니다. 테스트하려면 Test mode를 켠 상태로 두고 샌드박스 자격 증명을 입력합니다.

7. Enable/Disable을 켜고 저장합니다. 테스트 결제를 진행한 다음, 실제 결제를 받으려면 테스트 모드를 끕니다.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > PayFast. 필드 위에서 페이지는 현재 모드의 자격 증명이 비어 있을 때(이 경우 체크아웃에서 PayFast가 숨겨짐), 쇼핑몰 통화가 ZAR이 아닐 때, 라이브 모드가 공용 샌드박스 가맹점 ID 10000100을 사용할 때, 패스프레이즈가 설정되지 않았을 때 경고합니다. 테스트 모드가 켜져 있는 동안에는 Test mode is on: orders are paid in the PayFast sandbox, no real money is charged. 가 표시됩니다. 결제 수단 목록에서는 현재 모드의 가맹점 ID와 가맹점 키를 입력할 때까지 PayFast가 설정 필요 상태로 표시됩니다.

일반

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

Title: 고객이 체크아웃에서 보는 결제 수단 이름. 기본값: PayFast.

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트. 기본값: Pay securely by card, Instant EFT and other methods on the PayFast payment page.

PayFast 계정(라이브)

가맹점 ID와 가맹점 키는 PayFast 대시보드의 Settings > Developer Settings에서 확인할 수 있습니다. 거기서 패스프레이즈를 설정했다면 정확히 같은 값을 여기에 입력하세요.

Merchant ID: 라이브용 PayFast 가맹점 ID입니다.

Merchant Key: 라이브용 PayFast 가맹점 키입니다. 모든 결제 양식과 함께 PayFast로 전송됩니다.

Passphrase: PayFast의 Settings > Developer Settings에 있는 솔트 패스프레이즈입니다. 결제와 알림에 서명하므로 강력히 권장합니다.

샌드박스(테스트 모드)

테스트 모드에서는 결제가 PayFast 샌드박스로 전송되며 실제 금액은 청구되지 않습니다. PayFast 샌드박스에 로그인하면 샌드박스 자격 증명이 표시됩니다(공개 테스트 가맹점은 10000100 / 46f0cd694581a입니다).

Test mode: Use the PayFast sandbox and the sandbox credentials below. 체크아웃에서 고객은 TEST MODE: payments go to the PayFast sandbox, no real money is charged.를 봅니다. 기본값: 켬.

Sandbox Merchant ID: 샌드박스 계정의 가맹점 ID입니다.

Sandbox Merchant Key: 샌드박스 계정의 가맹점 키입니다.

Sandbox Passphrase: 샌드박스 계정에 패스프레이즈가 설정된 경우에만 입력합니다.

테스트 모드에서 버전 1.0에서 업데이트하는 경우, 기존 자격 증명이 샌드박스 필드로 복사됩니다. 테스트 모드를 끄기 전에 라이브 자격 증명을 확인하세요.

결제 알림(ITN)

PayFast는 모든 결제를 이 섹션에 표시된 URL로 보내는 서버 간 알림으로 확인합니다. 형식은 다음과 같습니다: https://your-site/wc-api/payfast_pay/. 이 주소는 모든 결제와 함께 전송되므로 PayFast에서 따로 설정할 것은 없지만, 인터넷에서 접근 가능해야 합니다.

출처 확인: Accept live notifications only from PayFast servers. 주소는 PayFast의 DNS 레코드에서 가져옵니다. 사이트가 방문자 주소를 숨기는 프록시나 CDN 뒤에 있는 경우에만 끄세요. 서명과 서버 확인은 항상 수행됩니다. 샌드박스 알림은 주소로 확인하지 않습니다. 기본값: 켬.

고급

Debug log: Log payment steps는 각 단계를 WooCommerce > Status > Logs에 기록합니다. 소스는 wcp_payfast_pay입니다. 오류는 항상 기록됩니다. 패스프레이즈나 고객 세부 정보는 기록되지 않습니다. 기본값: 끔.

Uninstall: Delete the gateway settings and logs when the plugin is deleted. 기본값: 끔.

체크아웃

고객은 결제 수단(기본값 PayFast)을 선택하고 주문합니다. 고객은 주문의 Pay for order 페이지로 이동하며, 여기에는 Thank you for your order. You are being redirected to PayFast to complete the payment.가 표시되고, 서명된 결제 양식이 PayFast로 자동 전송됩니다. 브라우저가 자동으로 넘어가지 않으면 고객은 Pay with PayFast를 클릭합니다. Cancel order는 주문을 취소합니다. 이 양식에는 ZAR로 표시된 주문 합계, Order #와 주문 번호, 고객의 이름과 이메일, 주문 키가 포함됩니다. 페이지를 열 때마다 다시 생성되므로, 고객은 PayFast에서 돌아온 뒤에도 다시 열 수 있습니다.

PayFast 페이지에서 고객은 카드, Instant EFT 또는 PayFast 계정의 다른 방법으로 결제합니다. 그런 다음 PayFast가 쇼핑몰로 결제 알림(ITN)을 보냅니다. 주문은 알림이 모든 검사를 통과한 경우에만 결제 완료로 표시됩니다.

고객이 주문 접수 페이지로 돌아와도 주문은 변경되지 않습니다. 알림이 도착하기 전까지 페이지에는 PayFast is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again.가 표시됩니다. 주문이 보류 상태이면 Your payment is being reviewed. We will contact you if anything else is needed.가 표시됩니다.

고객이 PayFast 페이지에서 취소하면 주문은 WooCommerce의 표준 방식으로 취소됩니다. 고객이 결제하지 않고 떠나면 주문은 결제되지 않은 상태로 남으며, Pay for order 페이지에서 다시 결제할 수 있습니다.

이 결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. 현재 모드의 자격 증명이 없거나, 쇼핑몰 또는 주문 통화가 ZAR이 아니거나, 합계가 R5.00 미만이면 숨겨집니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다.

이 플러그인은 ZAR 단건 결제만 받습니다. WooCommerce에서의 환불, 구독, 저장된(토큰화된) 카드, 사전 주문 및 분할 결제는 지원하지 않습니다.

주문

주문 상태

Pending payment: 고객이 PayFast로 이동했지만 결제 알림이 아직 도착하지 않았습니다.

Processing: PayFast가 결제를 확인했습니다. 결제 후 WooCommerce의 표준 상태이며, 다운로드 가능한 가상 상품만 있는 주문은 완료됨이 됩니다. 주문 메모에는 PayFast 결제 ID가 표시되며, 이 ID는 주문의 거래 ID이기도 합니다. 샌드박스 결제에는 실제 금액이 청구되지 않았다는 메모가 붙습니다. PayFast 수수료와 순 금액은 주문에 저장됩니다.

On hold: PayFast가 결제를 대기 중으로 보고했습니다. 또는 결제된 금액이 주문 합계와 다르거나 주문 통화가 ZAR이 아닙니다. 또는 이미 취소된 주문에 대해 결제가 도착했습니다. 주문 메모에 이유가 설명되어 있습니다. 주문과 PayFast 대시보드를 확인한 뒤, 발송하거나 PayFast에서 결제를 환불하세요.

Failed: 주문이 결제되지 않은 상태에서 PayFast가 결제를 실패로 보고했습니다. 고객은 다시 결제할 수 있습니다.

Cancelled: 고객이 PayFast 페이지에서 취소했거나, 사용자가 주문을 취소했거나, WooCommerce 재고 보류 시간 초과로 취소되었습니다.

같은 결제에 대한 반복 알림은 아무것도 변경하지 않습니다. 이미 결제된 주문에 다른 완료된 결제가 도착하면, 메모에서 중복 결제를 PayFast에서 환불하라고 안내합니다. 환불된 주문에 대한 결제는 메모만 추가합니다. 게이트웨이가 라이브 모드인 동안 받은 샌드박스 결제는 메모를 추가하지만 주문을 결제 완료로 표시하지 않습니다.

환불

WooCommerce에서의 환불은 지원하지 않습니다. PayFast 대시보드에서 결제를 환불한 다음, WooCommerce에서 수동 환불을 만드세요.

라이선스 키

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

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

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

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

문제 해결

체크아웃에 PayFast가 표시되지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드의 가맹점 ID와 가맹점 키가 입력되어 있는지, 쇼핑몰 통화가 ZAR인지, 주문 합계가 R5.00 이상인지 확인하세요. 무언가 빠져 있으면 설정 페이지에 경고가 표시됩니다.

결제는 완료되었지만 주문이 결제 대기 상태로 남아 있음: PayFast가 결제 알림을 전달하지 못했거나 알림이 거부되었습니다. Debug log를 켜고 WooCommerce > Status > Logs에서 소스 wcp_payfast_pay를 확인하세요. 일반적인 원인은 다음과 같습니다. 사이트가 인터넷에서 접근할 수 없음(유지 보수 모드, 기본 인증, 방화벽), PayFast와 플러그인의 패스프레이즈가 다름, 또는 라이브 모드에서 프록시나 CDN 뒤에 있을 때의 출처 확인. 이 경우 Source check를 끄세요.

알림 응답이 Invalid signature임: 플러그인의 패스프레이즈가 이 모드에 대해 PayFast에 설정된 것과 다릅니다.

알림 응답이 Invalid source임: 알림이 PayFast 주소에서 오지 않았거나, 프록시나 CDN이 실제 주소를 숨기고 있습니다. 사이트가 프록시나 CDN 뒤에 있다면 Source check를 끄세요.

알림 응답이 Merchant mismatch 또는 Order mismatch임: 결제가 다른 PayFast 계정으로 이루어졌거나 이 주문에 속하지 않습니다. 아무것도 변경되지 않습니다.

알림 응답이 Confirmation unavailable 또는 Busy임: 서버 확인을 위해 PayFast에 연결할 수 없었거나, 같은 주문에 대한 다른 알림이 같은 시점에 처리되고 있었습니다. PayFast가 알림을 다시 보냅니다.

알림 응답이 Not configured임: 주문이 결제된 모드의 자격 증명이 없습니다.

고객에게 PayFast accepts payments from R5.00이 표시됨: 주문 합계가 PayFast 최소 금액보다 낮습니다.

주문이 On hold 상태임: PayFast가 주문과 일치하지 않는 결제를 확인했습니다(금액이 다르거나 통화가 ZAR이 아님). 또는 이미 취소된 주문에 대해 결제가 도착했습니다. 주문 메모와 PayFast 대시보드를 확인하세요.

샌드박스 결제로 주문이 결제 완료되지 않음: 게이트웨이가 라이브 모드입니다. 라이브 모드에서는 샌드박스 결제가 주문을 결제 완료 처리하지 않으며, 주문의 메모에 그 내용이 표시됩니다.

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

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화한 다음 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정, 플러그인의 다른 옵션, 캐시된 PayFast 주소, 로그는 Delete the gateway settings and logs when the plugin is deleted가 켜져 있을 때만 삭제됩니다. 그렇지 않으면 나중에 다시 설치할 수 있도록 유지됩니다. 기존 주문은 결제 메모와 거래 ID를 그대로 유지합니다.

PayFast는 해당 소유자의 상표입니다. 이 플러그인은 PayFast와 제휴하거나 PayFast의 승인을 받지 않았습니다.