VibeFox PayFast for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0~9.x.

PHP: 8.0 이상. 이전 버전의 PHP에서는 모듈 설치가 거부됩니다.

통화: 남아프리카공화국 랜드(ZAR). PayFast는 랜드로만 정산하므로 장바구니는 ZAR이어야 합니다. 쇼핑몰에 아직 통화가 없다면 International > Localization > Currencies에서 추가하세요. 최소 주문 금액은 R5.00입니다.

PayFast 계정: PayFast 대시보드의 Settings > Developer Settings에서 확인할 수 있는 PayFast 계정의 Merchant ID와 Merchant Key. 패스프레이즈 사용을 강력히 권장합니다. PayFast에 패스프레이즈를 설정했다면 같은 패스프레이즈를 모듈에도 입력해야 합니다. 테스트에는 PayFast 샌드박스 자격 증명이 필요합니다.

접근 가능한 쇼핑몰: 결제 알림 URL은 기본 인증(basic auth)이나 방화벽 차단 없이 인터넷에서 접근할 수 있어야 합니다.

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

설치

1. 관리자 페이지에서 Modules > Module Manager로 이동하여 Upload a module을 클릭하세요. 모듈의 ZIP 파일을 선택하세요.

2. 업로드가 끝나면 Configure를 클릭하세요. 나중에 모듈 목록에서 VibeFox PayFast Pay Gateway를 찾아 Configure를 클릭해도 됩니다.

3. Configure 페이지 상단의 라이선스 블록에 있는 License key에 VibeFox 라이선스 키를 입력하고 Activate를 클릭하세요(라이선스 키 참조).

4. Merchant ID, Merchant Key, 패스프레이즈를 입력하세요. 테스트할 때는 Test mode를 켜 둔 상태에서 샌드박스 자격 증명을 입력하세요.

5. Enable/Disable을 켜고 Save를 클릭하세요. 테스트 결제를 한 뒤 실제 결제를 받으려면 Test mode를 끄세요.

설치 시 모듈은 두 가지 주문 상태를 만듭니다: Awaiting PayFast payment와 PayFast payment on hold. PrestaShop은 모든 통화, 국가, 고객 그룹에 새 결제 모듈을 제공합니다. Payment > Preferences에서 이를 제한할 수 있으며, 이때 랜드에 대해 모듈이 계속 허용되는지 확인하세요.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 Save 버튼이 있습니다. 필드 위에서 페이지는 현재 모드의 자격 증명이 비어 있을 때(이 경우 PayFast는 체크아웃에서 숨겨집니다), 기본 쇼핑몰 통화가 ZAR이 아닐 때, 라이브 모드에서 공개 샌드박스 Merchant ID 10000100을 사용할 때, 패스프레이즈가 설정되지 않았을 때 경고합니다. 테스트 모드가 켜져 있고 모듈이 활성화된 동안에는 테스트 모드가 켜져 있습니다. 주문은 PayFast 샌드박스에서 결제되며 실제 금액은 청구되지 않습니다. 라고 표시됩니다. 빈 Title은 결제 수단의 제목을 입력하세요. 메시지와 함께 거부됩니다.

PayFast

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

Title: 체크아웃에서 고객에게 표시되는 결제 수단 이름입니다. 주문에 저장되는 결제 수단 이름이기도 합니다. 기본값: PayFast. 필수.

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

PayFast 계정(라이브)

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

Merchant ID: 라이브 PayFast Merchant ID입니다.

Merchant Key: 라이브 PayFast Merchant Key입니다. 모든 결제 양식과 함께 PayFast로 전송되므로 일반 텍스트 필드입니다.

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

샌드박스(테스트 모드)

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

Test mode: Use the PayFast sandbox and the sandbox credentials below. 켜져 있는 동안 고객은 결제 수단 아래에서 테스트 모드: 결제는 PayFast 샌드박스로 전송되며 실제 금액은 청구되지 않습니다. 를 보게 됩니다. 기본값: 켜짐.

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

Sandbox Merchant Key: 샌드박스 계정의 Merchant Key입니다.

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

저장된 패스프레이즈는 다시 표시되지 않습니다. 필드는 비어 있고 Saved — leave empty to keep it.를 표시합니다. 변경하려는 경우에만 새 값을 입력하세요.

Clear saved passphrases: Passphrase 또는 Sandbox Passphrase를 체크하고 Save를 클릭하면 삭제됩니다. 빈 필드는 저장된 값을 유지합니다.

결제 알림(ITN)

Notification URL: PayFast는 여기에 표시된 URL로 서버 간 알림을 보내 모든 결제를 확인합니다. 친숙한 URL을 사용하면 https://your-shop/module/wcp_payfast_pay/itn과 같은 형태이며, 기본 언어의 언어 코드가 포함될 수도 있습니다. 주소는 모든 결제와 함께 전송되므로 PayFast에서 따로 설정할 것은 없지만, 인터넷에서 접근 가능해야 합니다. 주문은 이렇게 검증된 알림으로만 생성됩니다. 고객이 쇼핑몰로 돌아오는 것만으로는 주문이 생성되거나 결제되지 않습니다.

Source check: 라이브 알림은 PayFast 서버에서 온 것만 허용합니다. 주소는 PayFast의 DNS 레코드(6시간 캐시)와 PayFast가 문서화한 주소 범위에서 가져옵니다. 쇼핑몰이 방문자 주소를 숨기는 프록시나 CDN 뒤에 있는 경우에만 끄세요. 서명과 서버 확인은 항상 검사합니다. 샌드박스 알림은 주소로 검사하지 않습니다. 기본값: 켜짐.

고급

Debug log: 결제 단계를 모듈 폴더의 logs/payfast_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류와 경고는 스위치가 꺼져 있어도 항상 기록됩니다. 패스프레이즈나 고객 정보는 기록되지 않습니다. 기본값: 꺼짐.

Log: 로그의 크기와 최근 항목을 보여 줍니다. Clear log를 클릭하면 비워집니다.

Uninstall: Delete the gateway settings when the module is uninstalled(설정, 캐시된 PayFast 주소, 로그). PayFast 결제 기록, 주문, 주문 상태는 항상 보존됩니다. 기본값: 꺼짐.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 PayFast)을 선택하고 확인합니다. 주문해 주셔서 감사합니다. 결제를 완료하기 위해 PayFast로 이동합니다. 라는 페이지가 서명된 결제 양식을 PayFast로 자동 전송합니다. 브라우저가 자동으로 넘어가지 않으면 고객은 Pay with PayFast를 클릭합니다. Cancel을 누르면 체크아웃으로 돌아갑니다. 양식에는 ZAR 기준의 장바구니 합계, 장바구니 번호가 들어간 Cart #, 고객의 이름과 이메일, 결제 참조 번호(장바구니 번호와 시도 번호), 그리고 해당 시도의 무작위 토큰이 담깁니다. 이 시점에는 아직 주문이 없습니다. 새로운 시도마다 새로운 참조 번호와 토큰이 부여됩니다.

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

같은 장바구니의 알림은 한 번에 하나씩 처리됩니다. 같은 장바구니의 다른 알림이 처리 중이면 PayFast는 오류 응답을 받고 알림을 다시 보냅니다. 알림 URL은 쇼핑몰이 유지 보수 모드에 있는 동안에도 작동하며, 쇼핑몰의 국가 제한에 막히지 않습니다.

고객이 돌아왔을 때 주문이 존재하면 표준 주문 확인 페이지가 표시됩니다. PayFast가 결제를 대기 중으로 보고했다면 PayFast가 결제를 확인하고 있습니다. 확인되는 즉시 이메일로 알려 드리며, 다시 결제하실 필요는 없습니다. 라고 표시됩니다. 주문이 보류 상태이면 결제 내용을 검토 중입니다. 추가로 필요한 것이 있으면 연락드리겠습니다. 라고 표시됩니다. 대기 중이던 결제가 나중에 실패했다면 PayFast 결제가 완료되지 않았습니다. 이 주문에 대해 문의해 주세요. 라고 표시됩니다. 알림이 아직 도착하지 않았다면 Payment confirmation 페이지가 표시되어, PayFast가 결제를 확인하고 있으며 PayFast가 확인하는 즉시 주문이 생성된다고 알려 줍니다. 이때 Check again 및 Back to checkout 버튼이 제공됩니다.

고객이 PayFast 페이지에서 취소하면 PayFast 결제가 취소되었습니다. 다시 시도하거나 다른 결제 수단을 선택할 수 있습니다. 라는 메시지와 함께 체크아웃으로 돌아갑니다. PayFast가 결제를 실패로 보고했다면 메시지는 결제가 완료되지 않았습니다. 다시 시도하거나 다른 결제 수단을 선택할 수 있습니다. 입니다. 장바구니는 유지되며 다시 결제할 수 있습니다.

현재 모드의 자격 증명이 없을 때, 장바구니 통화가 ZAR이 아니거나 모듈에서 허용되지 않을 때, 또는 합계가 R5.00 미만일 때는 결제 수단이 숨겨집니다. 그럼에도 고객이 결제 단계에 도달하면 짧은 안내 메시지가 표시됩니다. 예를 들어 PayFast는 R5.00 이상의 결제를 받습니다. 다른 결제 수단을 선택해 주세요. 라고 표시됩니다.

이 모듈은 ZAR 단건 결제만 받습니다. 주문 페이지에서의 환불, 구독, 저장된(토큰화된) 카드, 분할 결제는 지원하지 않습니다.

주문

주문 상태

No order yet: 고객이 PayFast로 이동했지만 결제 알림이 아직 도착하지 않았거나, PayFast가 결제를 실패로 보고한 상태입니다. 장바구니만 존재합니다.

Payment accepted: PayFast가 결제를 확인했습니다. 결제는 PayFast 결제 ID를 거래 ID로 하여 기록되고, 메모에 결제 ID가 표시됩니다. 샌드박스 결제에는 실제 금액이 청구되지 않았다는 메모가 붙습니다.

Awaiting PayFast payment: PayFast가 결제를 대기 중으로 보고했습니다. PayFast가 결제를 완료하면 주문이 Payment accepted로 바뀝니다.

Payment error: 대기 중이던 결제가 실패했습니다. PayFast가 나중에 완료하면 주문은 Payment accepted가 됩니다.

PayFast payment on hold: 결제된 금액이 장바구니 합계와 다르거나, 장바구니가 ZAR이 아닌 경우입니다. 또는 취소된 주문이나 결제 수단이 더 이상 PayFast가 아닌 주문에 대한 결제가 도착했거나, 게이트웨이가 라이브 모드인 동안 샌드박스 결제가 도착한 경우입니다. PayFast가 받은 금액은 주문에 기록되며(샌드박스 결제는 제외), 메모에 그 이유가 설명됩니다. 주문과 PayFast 대시보드를 확인한 뒤 주문을 Payment accepted로 설정하거나, 주문을 취소하고 PayFast에서 결제를 환불하세요.

같은 결제에 대한 반복 알림은 아무것도 바꾸지 않습니다. 늦게 도착한 실패 또는 대기 알림은 결제 완료된 주문을 절대 바꾸지 않습니다. 이미 결제된 주문에 다른 결제 완료 알림이 도착하면, 메모에서 중복 결제를 PayFast에서 환불하라고 안내합니다. 환불된 주문에 대한 결제는 메모만 추가합니다.

PayFast 결제 블록

주문 페이지에는 PayFast payment 블록이 표시되며, 여기에는 결제 참조 번호(m_payment_id), PayFast 결제 ID, 환경(라이브 또는 샌드박스), 상태, ZAR 기준의 총액·수수료·순액, 그리고 모듈의 메모가 나타납니다. 보류 중인 주문에는 결제를 검토하라는 알림이 표시됩니다.

환불

주문 페이지에서의 환불은 지원하지 않습니다. PayFast 대시보드에서 결제를 환불한 다음, PrestaShop에서 주문을 수동으로 업데이트하세요.

라이선스 키

이 모듈은 vibefox.net에서 받은 VibeFox 라이선스 키로 동작합니다. 모듈의 Configure 페이지 위쪽, 설정 위에 있는 라이선스 블록 License — VibeFox PayFast Pay Gateway가 Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure의 첫 번째 블록입니다. 키를 License key에 입력하고 Activate를 클릭하세요. 그러면 이 블록에 키가 마스킹되어 표시되고, 상태(예: 라이선스 유효 기간 날짜와 도메인)와 함께 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key 버튼이 나타납니다. 그 아래에는 Product: presta-payment-payfast 줄과 vibefox.net 계정을 여는 Manage licenses and domains in your account 링크가 있습니다. 모듈의 Configure 권한이 있는 직원만 키를 변경할 수 있습니다. 블록의 텍스트는 백오피스 언어를 따릅니다(영어와 러시아어 포함).

키가 승인되지 않으면 블록에 이유가 표시됩니다. 예: Key not found, This key belongs to another product, Domain limit reached, 또는 날짜와 함께 License expired on. 쇼핑몰 주소가 바뀐 뒤나 계정에서 도메인 슬롯을 해제한 뒤에는 Check now를 클릭하세요. 라이선스 서버에 연결할 수 없으면 모듈은 마지막으로 확인된 상태로 계속 작동합니다.

키 하나는 도메인 하나에서 작동합니다. 메인 쇼핑몰의 도메인에 대해서이며, 멀티스토어 구성에서도 마찬가지입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하세요.

활성 키가 없으면 체크아웃에서 PayFast가 고객에게 표시되지 않습니다. 그래도 결제가 시작되면 고객에게 This payment method is not available. Please choose another one. 메시지가 보입니다. PrestaShop 스토어프런트는 백오피스에 로그인되어 있다는 것을 알지 못하므로, 결제 수단은 관리자에게도 숨겨집니다. 키를 구매하기 전에 모듈을 설정할 수는 있지만, 체크아웃에서 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 표시됩니다. 기존 주문은 영향을 받지 않으며, 이미 시작된 결제는 계속 확인됩니다.

라이선스가 만료되어도 모듈은 계속 작동하지만, 업데이트와 지원에는 갱신이 필요합니다. 백오피스에서 작업하는 동안 상태는 자동으로 다시 확인됩니다. 키를 입력한 뒤 처음 14일 동안에는 하루에 한 번, 그 후에는 주에 한 번입니다. cron 작업은 필요하지 않습니다. 모듈을 제거하거나 초기화하면 라이선스 키와 라이선스 상태는 항상 삭제됩니다.

문제 해결

체크아웃에 PayFast가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드의 Merchant ID와 Merchant Key가 입력되어 있는지, 장바구니가 ZAR인지, 주문 합계가 최소 R5.00인지 확인하세요. 설정 페이지는 무언가 빠져 있으면 경고를 표시합니다. Payment > Preferences에서 랜드, 고객의 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인하세요.

결제는 완료됐지만 주문이 생성되지 않음: PayFast가 결제 알림을 전달하지 못했거나 알림이 거부되었습니다. 모듈 페이지의 Log 필드를 확인하세요. 오류와 거부된 알림은 항상 기록되며, Debug log를 켜면 모든 단계가 추가로 기록됩니다. 일반적인 원인은 다음과 같습니다. 쇼핑몰이 인터넷에서 접근할 수 없음(기본 인증, 방화벽), PayFast와 모듈의 패스프레이즈가 다름, 또는 라이브 모드에서 프록시나 CDN 뒤에 있어 출처 검사에 걸림. 이 경우 Source check를 끄세요.

알림 응답이 Invalid signature임: 모듈의 패스프레이즈가 결제가 이루어진 모드에 대해 PayFast에 설정된 패스프레이즈와 다릅니다.

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

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

알림 응답이 Order not found임: 이 쇼핑몰에서 결제 참조 번호를 알 수 없습니다. 아무것도 변경되지 않습니다.

알림 응답이 Confirmation unavailable, Busy 또는 Temporary error임: 서버 확인을 위해 PayFast에 연결할 수 없었거나, 같은 장바구니의 다른 알림이 같은 순간 처리 중이었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화된 경우). PayFast는 알림을 다시 시도합니다. 로그에 이유가 표시됩니다.

알림 응답이 Not configured임: 결제를 시작한 모드의 자격 증명이 없습니다. 테스트 결제라면 샌드박스 자격 증명처럼 다시 입력하세요.

고객에게 PayFast는 남아프리카공화국 랜드(ZAR) 결제만 받습니다 메시지가 보임: 장바구니가 다른 통화로 되어 있습니다. 고객이 랜드로 결제하거나 다른 결제 수단을 선택하도록 안내하세요.

주문이 PayFast payment on hold 상태임: PayFast payment 블록의 메모(주문 상태 참조)와 PayFast 대시보드를 확인한 다음, 주문을 승인하거나 결제를 환불하세요.

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

개발자용: actionPayfastPPaymentData 훅은 서명 전에 결제 양식의 필드를 변경할 수 있습니다. 가맹점 자격 증명, URL, 결제 참조 번호, 금액, 토큰은 이 훅으로 변경할 수 없습니다.

제거

Modules > Module Manager로 이동한 다음 VibeFox PayFast Pay Gateway 옆의 메뉴를 열고 Uninstall을 선택하세요. 이 모듈의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Delete the gateway settings when the module is uninstalled가 켜져 있으면 게이트웨이 설정, 캐시된 PayFast 주소, 로그가 삭제됩니다. 꺼져 있으면 나중에 다시 설치할 수 있도록 모든 설정이 보존됩니다. PayFast 결제 기록, 주문, 주문 상태 Awaiting PayFast payment와 PayFast payment on hold는 항상 보존됩니다. 기존 주문은 결제 메모와 거래 ID를 그대로 유지합니다.

PayFast는 해당 소유자의 상표입니다. 이 모듈은 PayFast와 제휴하거나 PayFast의 승인을 받은 것이 아닙니다.