VibeFox Ozow for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: 8.0 이상. 모듈은 이전 버전의 PHP에서는 설치되지 않습니다.

통화: 남아프리카 랜드(ZAR). 결제 수단은 ZAR 장바구니에만 표시됩니다. Ozow는 센트 단위의 정수로 청구하므로, 통화는 소수점 2자리를 사용해야 합니다.

Ozow 계정: Ozow 가맹점 계정과 Ozow 사이트의 Site Code 및 Private Key. Ozow 가맹점 대시보드에서 확인할 수 있습니다. API Key는 선택 사항이지만 권장합니다. Ozow는 테스트 결제와 실제 결제에 같은 Site Code와 키를 사용합니다.

접근 가능한 사이트: Ozow 알림이 도착하도록 쇼핑몰은 인터넷에서 접근할 수 있어야 하며, 비밀번호 보호나 Ozow를 차단하는 방화벽이 없어야 합니다. 쇼핑몰이 유지 보수 모드에 있을 때에도 알림은 수락됩니다.

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

설치

1. 백오피스에서 Modules > Module Manager로 이동하여 Upload a module을 클릭합니다. 모듈의 ZIP 파일을 선택합니다.

2. 업로드가 끝나면 Configure를 클릭하거나, 나중에 모듈 목록에서 VibeFox Ozow Pay를 찾아 Configure를 클릭합니다.

3. Configure 페이지 상단의 라이선스 블록에 있는 License key 입력란에 VibeFox 라이선스 키를 붙여 넣고 Activate를 클릭합니다(라이선스 키 참조).

4. Ozow 가맹점 대시보드에서 가져온 Site Code와 Private Key를 입력하고, 가능하면 API Key도 입력합니다.

5. Enable/Disable을 켜고 Save를 클릭합니다. Test mode를 켠 상태로 테스트 결제를 진행한 뒤, 실제 결제를 받으려면 테스트 모드를 끕니다.

설치 시 모듈은 두 가지 주문 상태를 만듭니다: Awaiting Ozow payment와 Ozow payment on hold. PrestaShop은 모든 통화, 국가, 고객 그룹에 대해 새 결제 모듈을 제공합니다. Payment > Preferences에서 이를 제한할 수 있습니다. 그곳에서 이 모듈에 대해 ZAR이 허용되어야 합니다. 나중에 활성화한 국가도 그곳에서 이 모듈에 체크해야 합니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Ozow Pay > Configure. Save 버튼이 있는 각 섹션은 페이지 전체를 저장합니다. 입력란 위에서 페이지는 Site Code 또는 Private Key가 없을 때(이 경우 Ozow는 체크아웃에서 숨겨집니다), 쇼핑몰 기본 통화가 ZAR이 아닐 때, 통화의 소수점 자릿수가 2를 초과할 때(International > Localization > Currencies에서 2로 설정하십시오)를 경고하고, 테스트 모드가 켜져 있는 동안 Test mode is on: no real payments are accepted. Do not ship orders paid in test mode.를 표시합니다.

Ozow

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

Title: 고객이 체크아웃에서 보는 결제 수단 이름입니다. 주문에 저장되는 결제 수단 이름이기도 합니다. 기본값: Instant EFT (Ozow).

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment. 테스트 모드에서는 그 아래에 TEST MODE: no money will be charged. 줄이 추가됩니다(설명이 비어 있지 않은 경우에만).

Ozow 인증 정보

Ozow 가맹점 대시보드(Merchant details / Sites)에서 Site Code, Private Key, API Key를 복사합니다. 이 섹션에는 hub.ozow.com의 Ozow 연동 문서 링크가 있습니다.

Site Code: 결제를 받는 Ozow 사이트의 Site Code입니다. 다른 Site Code에 대한 응답은 거부됩니다.

Private Key: 모든 결제 요청에 서명하고 모든 Ozow 응답을 검증합니다. 비공개로 유지하십시오. 이것이 없으면 결제 수단이 숨겨지고 Ozow 응답은 전혀 수락되지 않습니다.

API Key (recommended): 선택 사항입니다. API Key를 입력하면, 성공한 모든 결제는 주문이 결제 완료로 표시되기 전에 Ozow GetTransaction API로도 확인됩니다. API는 이 장바구니에 대해 같은 금액, 통화, Site Code로 결제가 완료되었다고 보고해야 합니다.

저장된 키는 다시 표시되지 않습니다. 입력란은 비어 있으며 Saved — leave empty to keep it.를 표시합니다. 변경하려는 경우에만 새 값을 입력하십시오.

Clear saved secrets: Private Key 또는 API Key를 체크하고 저장하면 저장된 키가 삭제됩니다. 입력란이 비어 있으면 저장된 값이 유지됩니다.

Test mode: Ozow는 테스트에도 같은 Site Code와 키를 사용합니다. 결제는 IsTest=true로 생성되며 실제 금액은 이동하지 않습니다. 테스트 모드에서 결제된 주문에는 주문 메시지가 붙습니다. 이런 주문은 배송하지 마십시오. 실제 결제를 받으려면 테스트 모드를 끄십시오. 실제 운영 모드에서는 테스트 결제가 주문을 결제 완료로 만들지 않습니다. 기본값: on.

결제 알림

알림, 성공, 취소, 오류 URL은 결제할 때마다 Ozow에 전송되므로, Ozow 사이트가 고정 URL로 설정되어 있지 않다면 Ozow 대시보드에서 설정할 것은 없습니다. 이 섹션은 4개의 URL을 모두 보여 줍니다: Notification URL, Success URL, Cancel URL, Error URL. 이들은 쇼핑몰의 모듈 링크(컨트롤러 notify와 return)입니다. Ozow 사이트가 고정 URL을 사용한다면, 설정에 표시된 그대로 정확히 복사하십시오.

고급

Debug log: 결제 요청과 Ozow 응답을 모듈 폴더의 logs/ozow_p_debug.log.php에 기록합니다(웹에서는 읽을 수 없습니다). 오류와 경고는 항상 기록됩니다. 키, 해시, 토큰, 고객 데이터는 결코 기록되지 않습니다. 기본값: off.

Log: 로그의 현재 크기와 끝부분을 보여 주며, Clear log 버튼이 있습니다.

Delete data on uninstall: 모듈을 제거할 때 이 모듈의 설정과 로그를 삭제합니다(주문에 저장된 Ozow 데이터는 유지됩니다). 기본값: off.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 Instant EFT (Ozow))을 선택하고 주문을 확인합니다. 모듈은 ZAR로 된 장바구니 합계에 대한 서명된 요청과 함께 고객을 Ozow가 호스팅하는 결제 페이지로 보냅니다. 은행 명세서상의 참조 문구는 Cart와 장바구니 번호입니다(라틴 문자, 숫자, 공백, 하이픈 최대 20자). 고객의 이름은 Ozow에 전달됩니다. 이 시점에는 아직 주문이 없습니다. Ozow 페이지에서 고객은 남아프리카 은행을 선택하고 뱅킹 앱에서 결제를 승인합니다.

그 후 Ozow는 쇼핑몰에 알리고 고객을 돌려보냅니다. 두 경로 모두 같은 서명된 응답을 담고 있으며 같은 방식으로 처리되므로, 하나가 유실되어도 주문은 생성됩니다. 주문은 Ozow가 확인한 후에만 결제 완료로 표시됩니다: 해시는 귀하의 Private Key로 검증되어야 하고, Site Code는 귀하의 것이어야 하며, 응답은 이 장바구니의 이번 결제 시도에 속해야 하고, 금액과 통화는 장바구니와 일치해야 합니다. API Key를 사용하면 결제는 GetTransaction API로도 확인됩니다.

결제가 성공하면 고객은 표준 주문 확인 페이지를 봅니다. Ozow나 은행이 아직 결제를 검토 중이면 페이지에 We are waiting for Ozow to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again.가 표시됩니다. 주문이 보류 상태이면 Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed.가 표시됩니다. 검토 중이던 결제가 나중에 실패하거나 미결제 주문이 취소되면 Your Ozow payment was not completed. Please contact us about this order.가 표시됩니다. 고객이 돌아왔을 때 Ozow가 아직 결제를 확인하지 않았다면, 페이지에 대기 문구와 Check again 및 Back to checkout 버튼이 표시됩니다.

고객이 Ozow 페이지에서 취소하거나 결제가 실패하면 주문은 생성되지 않습니다. 고객은 같은 장바구니 상태로 체크아웃에 돌아가며 The Ozow payment was cancelled. You can try again or choose another payment method. 또는 The Ozow payment was not completed. You can try again or choose another payment method.를 보게 됩니다.

장바구니가 ZAR이 아니면 고객은 Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.를 보게 됩니다.

이 모듈은 ZAR 단건 결제만 받습니다. PrestaShop에서의 환불, 구독, 저장된 은행 계정이나 토큰화, 백오피스에서의 결제 링크 발송 기능은 없습니다.

주문 및 환불

주문 상태

아직 주문 없음: 고객이 Ozow로 이동했지만 결제하지 않았거나, 취소했거나, Ozow가 아직 결제를 확인하지 않은 상태입니다. 장바구니만 존재합니다.

Payment accepted: 결제가 확인되었습니다. 주문 메시지에는 금액과 Ozow 거래 ID, 그리고 결제가 GetTransaction API로 확인되었는지 여부가 표시됩니다. 주문 결제의 거래 ID는 Ozow TransactionId입니다. 테스트 결제는 TEST MODE — no money was received, do not ship this order. 메시지를 받습니다.

Awaiting Ozow payment: Ozow 또는 은행이 결제를 검토 중입니다. Ozow가 최종 상태를 보내면 주문이 업데이트됩니다.

Ozow payment on hold: 주문 메시지에 이유가 표시됩니다: 결제된 금액 또는 통화가 장바구니와 다름, 이미 취소된 주문에 대해 결제가 도착함, 또는 API Key를 사용하는 경우 GetTransaction API가 아직 결제를 확인하지 못했거나 결제와 모순됨. Ozow 대시보드에서 결제를 확인하고 주문 상태를 변경하십시오. API가 응답하지 못했다면, 다음 Ozow 알림이 주문을 완료합니다.

결제 오류: 검토 중이던 결제가 취소, 중단 또는 실패했습니다. 그 결제에 대해 나중에 도착한 성공 Ozow 응답은 여전히 주문을 결제 완료로 표시합니다.

이미 결제 완료된 주문은 되돌려지지 않으며, 취소되었거나 환불된 주문은 다시 열리지 않습니다. 이미 결제된 주문에 두 번째 결제가 도착하면, 메시지에서 중복 금액을 Ozow 대시보드에서 환불하라고 안내합니다. 다른 이유로(예: 직접 설정하여) 주문이 보류 상태라면, 나중에 도착한 결제는 메시지만 추가하며, 주문을 Payment accepted로 설정하는 것은 귀하가 직접 해야 합니다.

Ozow 결제 블록

주문 페이지에는 거래 참조와 시도, Ozow 거래 ID, 상태, 요청 금액, Ozow가 보고한 금액, Ozow 메시지, 그리고 테스트 결제의 경우 TEST MODE 표시가 있는 Ozow payment 블록이 나타납니다.

환불

PrestaShop에서의 환불은 지원하지 않습니다. Ozow 가맹점 대시보드에서 결제를 환불한 다음, PrestaShop에 환불 내역을 수동으로 기록하십시오.

라이선스 키

이 모듈은 vibefox.net에서 발급받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록 License — VibeFox Ozow Pay는 Modules > Module Manager > VibeFox Ozow Pay > Configure 페이지에서 설정 위쪽에 있는 첫 번째 블록입니다. 키를 License key에 붙여 넣고 Activate를 클릭하십시오. 그러면 블록에 마스킹된 키, 상태(예: 라이선스 유효 기간 종료일과 도메인), 그리고 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key 버튼이 표시됩니다. 그 아래에는 Product: presta-payment-ozow 줄과 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 계정에서 슬롯을 해제하십시오.

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

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

문제 해결

체크아웃에 Ozow가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, Site Code와 Private Key가 입력되어 있는지, 장바구니 통화가 ZAR인지 확인하십시오. Payment > Preferences에서 이 모듈이 ZAR, 고객의 국가, 고객의 그룹에 대해 허용되어 있는지 확인하십시오. 설정 페이지는 무언가 빠져 있으면 경고를 표시합니다.

결제는 완료되었지만 주문이 생성되지 않음: Ozow 알림이 쇼핑몰에 도달하지 못했고 고객도 돌아오지 않았습니다. 쇼핑몰이 인터넷에서 접근 가능한지 확인하십시오(Ozow를 차단하는 비밀번호 보호나 방화벽이 없어야 합니다). Ozow 사이트가 고정 URL로 설정되어 있다면, 그 URL이 Payment notifications에 표시된 것과 정확히 같은지 확인하십시오. Debug log를 켜고 Configure 페이지에서 로그를 확인하십시오.

알림 응답이 Invalid hash: 설정의 Private Key가 응답을 보낸 Ozow 사이트의 것이 아닙니다. Ozow 가맹점 대시보드에서 다시 복사하십시오. 아무것도 변경되지 않습니다.

알림 응답이 Unknown site: 응답이 다른 Ozow 사이트에서 왔습니다. Site Code를 확인하십시오.

알림 응답이 Order mismatch 또는 Order not found: 이 응답은 이 쇼핑몰에서 시작된 결제에 속하지 않습니다. 아무것도 변경되지 않습니다.

알림 응답이 Gateway not configured: Site Code 또는 Private Key가 없습니다. 입력하십시오. Ozow가 다시 시도할 수 있습니다.

알림 응답이 Payment not confirmed yet: 응답을 아직 적용할 수 없습니다. API Key를 사용하는 경우 GetTransaction API가 결제를 확인하지 못했습니다(주문은 보류 상태이며 다음 알림이 완료합니다. 계속 보류 상태라면 API Key와 Ozow 대시보드의 결제를 확인하십시오). 같은 장바구니에 대한 고객의 복귀가 같은 순간에 처리되고 있었거나, 주문을 생성할 수 없었을 때에도 이 응답이 옵니다. 로그를 확인하십시오.

테스트 결제가 주문을 결제 완료로 만들지 않음: 모듈이 실제 운영 모드입니다. 실제 운영 모드에서 테스트 결제는 주문을 결제 완료로 만들지 않습니다. 주문 메시지나 로그에 이 내용이 표시됩니다.

결제 후 주문이 Ozow payment on hold 상태: 주문 메시지를 읽고 Ozow 대시보드에서 결제를 확인한 다음, 주문을 Payment accepted로 설정하거나 Ozow에서 결제를 환불하십시오.

제거

Modules > Module Manager로 이동하여 VibeFox Ozow Pay 옆의 메뉴를 열고 Uninstall을 선택합니다. 이 모듈의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Delete data on uninstall이 켜져 있으면 모듈 설정과 로그가 삭제됩니다. 꺼져 있으면 나중에 다시 설치할 수 있도록 모든 설정이 유지됩니다. Ozow 결제 기록과 주문 상태 Awaiting Ozow payment 및 Ozow payment on hold는 항상 유지되므로, 재설치 후에도 오래된 주문에 대한 늦은 알림을 계속 인식합니다. 기존 주문은 결제 메시지와 거래 ID를 그대로 보관합니다.

Ozow는 해당 소유자의 상표입니다. 이 모듈은 Ozow와 제휴하지 않았으며 Ozow의 승인을 받지 않았습니다.