VibeFox eWAY for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

쇼핑몰 통화: AUD, NZD, SGD, HKD 또는 MYR. 그 외의 장바구니 통화에서는 체크아웃 시 이 결제 수단이 표시되지 않습니다. 결제는 장바구니 통화로 이루어집니다.

eWAY 계정: Rapid API 접근 권한이 있는 eWAY 가맹점 계정과 그 Rapid API 키 및 비밀번호가 필요합니다. 이는 MyeWAY의 Settings, API Key에서 확인할 수 있습니다. 테스트를 위해서는 자체 키와 비밀번호가 있는 eWAY 샌드박스 계정이 필요합니다. 샌드박스 키와 운영 키는 서로 다릅니다. eWAY에서 별도로 설정할 것은 없습니다. 반환 URL은 모든 결제와 함께 전송됩니다.

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

설치

1. 관리자 페이지에서 Modules > Module Manager로 이동한 후 Upload a module을 클릭합니다. 모듈의 ZIP 파일을 선택하십시오.

2. 업로드가 완료되면 Configure를 클릭하십시오. 나중에 찾으려면 모듈 목록에서 VibeFox eWAY Payment Gateway를 찾아 Configure를 클릭하십시오.

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

4. 샌드박스 API 키와 비밀번호를 입력하고, Sandbox Mode는 켜진 상태로 두고, Enable/Disable을 켠 다음, Save를 클릭하고 테스트 주문을 하십시오.

5. 운영 API 키와 비밀번호를 입력하고, Sandbox Mode를 끈 다음, Save를 클릭하십시오.

6. 선택 사항으로, Configure 페이지에 표시된 cron URL을 서버의 cron 작업에 추가하십시오(설정 항목 참조).

설치 시 모듈은 주문 상태 eWAY payment on hold를 만듭니다. PrestaShop은 모든 통화, 국가 및 고객 그룹에 대해 새로운 결제 모듈을 제공합니다. Payment > Preferences에서 이를 제한할 수 있습니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure. 각 섹션에는 별도의 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. 입력란 위에는 현재 모드를 나타내는 배지가 표시됩니다: SANDBOX — payments go to the eWAY sandbox, no real money is charged. 또는 LIVE — real payments are taken with the live API key. 현재 모드의 API 키 또는 비밀번호가 없으면(이 경우 체크아웃에서 결제 수단이 표시되지 않습니다), 그리고 쇼핑몰의 기본 통화가 eWAY에서 지원되지 않으면 페이지에서 경고합니다.

eWAY

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

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

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

API 자격 증명

Rapid API 키와 비밀번호는 MyeWAY의 Settings, API Key에 있습니다. eWAY는 운영 키와 샌드박스 키에 대한 안내를 제공하며, 이 섹션에 링크가 있습니다. 샌드박스와 운영은 서로 다른 키를 사용합니다.

Sandbox Mode: 결제는 샌드박스 키와 비밀번호를 사용하여 eWAY 샌드박스로 전송됩니다. 실제 금액은 청구되지 않습니다. 기본값: 켬. 운영 키로 실제 결제를 받으려면 끄십시오. 켜져 있는 동안 고객에게는 결제 수단 아래에 Test mode: no real payment is taken.이 표시됩니다.

Live API Key: eWAY 운영 계정의 Rapid API 키입니다.

Live API Password: eWAY 운영 계정의 Rapid API 비밀번호입니다.

Sandbox API Key: eWAY 샌드박스(파트너/개발자) 계정의 Rapid API 키입니다.

Sandbox API Password: eWAY 샌드박스 계정의 Rapid API 비밀번호입니다.

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

Clear saved credentials: 키 또는 비밀번호를 체크한 후 Save를 클릭하면 삭제됩니다. 입력란이 비어 있으면 저장된 값이 유지됩니다.

Return URL / re-checks: eWAY에서 webhook이나 반환 URL을 설정할 필요는 없습니다. 반환 URL은 모든 결제와 함께 전송되기 때문입니다. 이 항목에는 선택 사항인 cron URL이 표시됩니다. 서버의 cron 작업(예: 15분마다)에서 호출하십시오. 고객이 결제한 뒤 쇼핑몰로 돌아오기 전에 브라우저를 닫으면, 약 1시간 후 결제를 eWAY에 조회하여 주문을 생성합니다. eWAY에 연결할 수 없는 경우 확인은 최대 3회까지 반복됩니다. 이 URL은 비공개로 유지하십시오. 토큰이 포함되어 있으며, 잘못된 토큰으로 호출하면 Forbidden 응답이 반환됩니다.

주문

Order Status on Success: eWAY가 결제를 확인한 후의 주문 상태입니다.

주문과 일치하지 않는 승인 금액 또는 통화는 항상 eWAY payment on hold로 처리됩니다.

고급

Debug log: API 호출과 결제 결과를 모듈 폴더의 logs/eway_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 카드 정보, 키, 비밀번호, 고객 이메일, 접근 코드는 기록되지 않습니다. 오류는 항상 기록됩니다. 기본값: 끔.

Log: 로그의 크기와 최근 항목을 표시합니다. Clear log를 클릭하면 로그를 비울 수 있습니다.

Delete all plugin data on uninstall: 켜져 있으면 모듈을 제거할 때 게이트웨이 설정과 로그가 삭제됩니다. 주문의 eWAY 결제 데이터와 eWAY payment on hold 주문 상태는 항상 유지됩니다. 기본값: 끔.

체크아웃

결제 단계에서 고객은 결제 수단(기본값은 Credit Card (eWAY))을 선택하고 확인합니다. 모듈은 장바구니 통화로 장바구니 총액에 대한 결제 페이지를 eWAY에 요청하며, 청구 참조 번호로 PS-와 장바구니 번호를 포함하고, 고객의 청구지 주소와 이메일도 함께 전달합니다. 그런 다음 고객을 eWAY Responsive Shared Page로 이동시킵니다. 고객은 그곳에서 카드로 결제합니다. 금액은 즉시 청구됩니다. 이 시점에는 아직 주문이 존재하지 않습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 모듈은 브라우저를 신뢰하지 않습니다. 이 장바구니에 대해 생성된 결제 페이지의 결과를 서버 간 통신으로 eWAY에 요청합니다. 주문은 eWAY가 확인하고 승인된 금액과 통화가 장바구니와 일치한 후에만 결제 완료로 표시됩니다. 그런 다음 주문이 생성되고, 고객은 Your payment with eWAY has been received.가 표시된 표준 주문 확인 페이지를 보게 됩니다. 보류 중인 주문의 경우 페이지에 Your payment was received and is being reviewed by the store. We will contact you if anything is needed.가 표시됩니다.

그 시점에 eWAY에 조회할 수 없으면, Payment confirmation 페이지에 We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again.가 표시되며, Check again 버튼과 Back to checkout 버튼이 함께 나타납니다. 고객이 다시 확인하거나 cron URL이 실행되면 주문이 생성됩니다.

결제가 거절되면, 고객은 사유와 함께 체크아웃으로 돌아갑니다. 예: Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. 고객이 eWAY 페이지에서 Cancel을 클릭하면, 모듈은 먼저 eWAY에 아무 금액도 결제되지 않았는지 확인합니다(예: 다른 탭에서 결제된 경우 포함). 그런 다음 고객에게 You cancelled the payment on the eWAY page. Your order has not been paid — you can try again.가 표시됩니다. 결제가 완료되지 않았다면 메시지는 The payment was not completed. Please try again.입니다. 어떤 경우에도 장바구니는 유지됩니다.

고객은 다시 시도할 수 있습니다. 새 결제 페이지를 만들기 전에, 해당 장바구니의 이전 페이지를 eWAY에서 확인합니다. 이미 결제된 상태라면 두 번째 결제 대신 주문이 생성됩니다. eWAY가 결제 페이지를 만들 수 없으면, 고객은 체크아웃에 머무르며 Payment error: Unable to connect to eWAY. Please try again. 또는 eWAY could not start the payment와 같은 짧은 메시지와 eWAY 오류 코드를 보게 됩니다.

Shared Page의 경우 eWAY는 서버 간 알림을 보내지 않습니다. 결과는 고객이 돌아왔을 때와 cron URL을 통해 확인됩니다. 모듈은 귀하의 사이트에 카드 입력란이 없으며, 카드 저장이나 구독, 승인 후 캡처를 지원하지 않습니다. 또한 Beagle 사기 점수는 평가하지 않습니다(eWAY의 사기 방지 규칙으로 차단된 거래는 eWAY가 직접 거절합니다).

주문 및 환불

주문 상태

No order yet: 고객은 eWAY로 이동했지만 결제하지 않았거나, 취소했거나, 결제가 거절되었거나, 아직 결과를 가져올 수 없는 상태입니다. 장바구니만 존재합니다.

Payment accepted or Delivered: 결제가 승인되었습니다. 상태는 Order Status on Success를 따릅니다. 결제는 eWAY 거래 ID와 함께 기록되며, 메모에는 거래 ID, 승인 코드, 응답, 모드(샌드박스 또는 운영)가 표시됩니다.

eWAY payment on hold: eWAY가 장바구니와 다른 금액이나 통화를 승인한 경우(예: Approved for partial amount, 또는 고객이 결제 페이지를 연 후 장바구니가 변경된 경우), 고객이 eWAY 페이지에서 취소한 후에 결제가 승인된 경우, 또는 주문이 취소된 후에 결제가 승인된 경우입니다. 결제는 eWAY가 실제로 청구한 금액으로 기록되며, 메모에 그 이유가 설명됩니다. 주문을 확인한 후 처리하거나 결제를 환불하십시오.

Refunded: 모듈을 통해 결제가 전액 환불되었습니다.

이미 결제가 완료된 장바구니에 대해 두 번째 결제가 승인되더라도 주문은 변경되지 않습니다. 메모에서 MyeWAY에서 중복 결제를 환불하라고 안내합니다. 다른 청구 참조 번호에 대해 승인된 결제는 절대 주문에 적용되지 않습니다.

eWAY 결제 블록

주문 페이지에는 eWAY payment 블록이 표시되며, 거래 ID, 승인 코드, eWAY 응답, 상태, 모드와 청구 참조 번호, 결제 금액 및 환불 금액, 샌드박스 결제용 Sandbox 배지, 환불 내역, 주문의 eWAY notes가 포함됩니다.

환불

eWAY payment 블록에서 금액을 입력하고(아직 환불되지 않은 금액이 자동으로 채워집니다), 필요하면 사유를 입력한 다음 Refund via eWAY를 클릭하십시오. 확인 질문 Refund this amount through eWAY? This cannot be undone.에 응답하십시오. 전액 환불과 부분 환불을 지원합니다. 주문을 편집할 수 있는 권한이 필요합니다. Modules 페이지에 대한 접근 권한은 필요하지 않습니다. 환불은 eWAY가 청구한 금액과 통화로 이루어집니다. 따라서 부분 금액 승인 후에는 주문 총액이 아니라 고객이 실제로 결제한 금액까지 환불할 수 있습니다. 환불은 결제가 이루어진 환경(샌드박스 또는 운영)으로 전송되므로, 해당 환경의 API 키와 비밀번호가 설정되어 있어야 합니다. eWAY가 환불을 거절하면 블록에 eWAY refund failed:와 eWAY 코드가 표시되며, 환불은 기록되지 않습니다. 환불이 성공하면 환불 내역과 메모에 eWAY 환불 거래 ID가 추가됩니다. 전액 환불 시 주문은 Refunded가 됩니다. 부분 환불은 상태를 변경하지 않습니다. 환불은 eWAY가 결제를 승인한 후에 가능합니다.

모듈은 신용 전표(credit slip)를 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 eWAY를 통해 금액을 돌려보내지 않습니다. MyeWAY에서 처리한 환불은 PrestaShop과 동기화되지 않습니다. 필요한 경우 주문을 수동으로 업데이트하십시오.

라이선스 키

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

키가 허용되지 않으면 블록에 그 이유가 표시됩니다. 예를 들어 Key not found, This key belongs to another product, Domain limit reached 또는 날짜와 함께 License expired on이 나타날 수 있습니다. 쇼핑몰 주소를 변경한 후, 또는 계정에서 도메인 슬롯을 비운 후에 Check now를 클릭하십시오. 라이선스 서버에 연결할 수 없는 경우 모듈은 마지막으로 확인된 상태로 계속 작동합니다.

키 하나는 도메인 하나에서만 작동합니다. 기본 쇼핑몰의 도메인이며, 멀티스토어 설정에서도 마찬가지입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하십시오.

활성 키가 없으면 체크아웃에서 고객에게 eWAY가 표시되지 않습니다. 그래도 결제가 시작되면 고객에게 이 결제 수단은 사용할 수 없습니다. 다른 결제 수단을 선택하십시오.가 표시됩니다. PrestaShop 스토어프런트는 백오피스에 로그인한 사실을 알지 못하므로, 결제 수단은 관리자에게도 숨겨집니다. 키를 구매하기 전에 모듈을 설정할 수는 있지만, 체크아웃에서 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 표시됩니다. 기존 주문에는 영향이 없습니다. 이미 시작된 결제는 계속 확인되며, 환불도 정상적으로 작동합니다.

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

문제 해결

eWAY does not appear at checkout: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드의 API 키와 비밀번호가 설정되어 있는지(샌드박스 모드에서는 샌드박스 필드, 운영 모드에서는 운영 필드), 그리고 장바구니 통화가 AUD, NZD, SGD, HKD 또는 MYR인지 확인하십시오. 자격 증명이 없으면 설정 페이지에 경고가 표시됩니다. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객의 그룹에 대해 모듈이 허용되어 있는지 확인하십시오.

The payment went through, but no order was created: 고객이 eWAY에서 돌아오지 않았거나, 그 시점에 eWAY에 조회할 수 없었습니다. eWAY는 Shared Page에 대한 알림을 보내지 않습니다. Return URL / re-checks의 cron URL을 설정하십시오. 그러면 약 1시간 후 결제를 가져옵니다. MyeWAY에서 거래를 확인하고, 모듈 페이지의 Log 항목을 살펴보십시오.

The customer sees This payment method is temporarily unavailable: 현재 모드의 API 키 또는 비밀번호가 없거나 eWAY가 이를 거부했습니다. 현재 모드의 자격 증명을 확인하십시오.

The customer sees eWAY could not start the payment: eWAY가 오류 코드를 반환했습니다. 코드는 메시지에 표시됩니다. 대부분 청구 정보가 잘못되어 있습니다.

The customer sees We could not match this payment to an order: 반환 링크가 이 쇼핑몰의 장바구니에 속하지 않거나, eWAY가 다른 청구 참조 번호에 대한 결제를 승인했습니다. 고객이 청구되었다면 MyeWAY에서 결제를 찾으십시오.

The customer sees We could not check the status of your previous payment attempt: 같은 장바구니를 다른 요청이 처리 중이었습니다. 고객은 잠시 후 다시 시도할 수 있습니다.

Order is eWAY payment on hold after payment: eWAY payment 블록의 eWAY notes를 읽고(주문 상태 항목 참조), 주문을 처리하거나 결제를 환불하십시오.

Refund fails with a message about the sandbox or live mode: 주문이 해당 환경에서 결제되었으나, 그 환경의 API 키와 비밀번호가 설정되어 있지 않습니다. 입력한 후 다시 시도하십시오.

Refund fails with at most … can be refunded: 금액이 eWAY가 청구한 금액에서 이미 환불된 금액을 뺀 값을 초과합니다.

개발자용: 모듈의 README에는 actionWcpEwaySupportedCurrencies 훅이 나와 있습니다. eWAY 계정에서 추가 통화가 활성화된 경우 사용하십시오.

제거

Modules > Module Manager로 이동하여 VibeFox eWAY Payment Gateway 옆의 메뉴를 연 후 Uninstall을 선택하십시오. 이 모듈의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Delete all plugin data on uninstall이 켜져 있으면 게이트웨이 설정과 로그가 삭제됩니다. 꺼져 있으면 나중에 다시 설치할 수 있도록 모든 설정이 유지됩니다. 주문의 eWAY 결제 데이터와 eWAY payment on hold 주문 상태는 항상 유지되므로, 이전에 결제된 주문은 다시 설치한 후에도 환불할 수 있습니다. 기존 주문은 결제 메모와 거래 ID를 그대로 유지합니다.

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