VibeFox ECPay for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

통화: 신대만달러(TWD). ECPay는 TWD로만 결제를 받으므로, 결제 방법은 고객의 장바구니가 TWD일 때만 표시됩니다. 쇼핑몰에 TWD가 없다면 International > Localization > Currencies에서 추가하십시오. ECPay는 소수점을 받지 않으므로 금액은 정수 TWD로 전송됩니다. 장바구니 합계는 가장 가까운 달러 단위로 반올림됩니다. 반올림을 피하려면 TWD 가격에 소수점 0자리를 사용하십시오.

ECPay 계정: 실결제에는 ECPay 가맹점 계정의 MerchantID, HashKey, HashIV가 필요합니다. 이는 ECPay 가맹점 백오피스(vendor.ecpay.com.tw)에서 확인할 수 있습니다. 테스트에는 ECPay 계정이 필요하지 않습니다.

사이트 접근: ECPay가 결제 알림을 보낼 수 있도록, 쇼핑몰은 HTTP/HTTPS 80/443 포트를 통해 인터넷에서 접근 가능해야 합니다. 사이트 앞단의 방화벽이나 기본 인증은 알림을 차단합니다.

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

설치

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

2. 업로드가 끝나면 Configure를 클릭하거나, 나중에 모듈 목록에서 VibeFox ECPay Payment Gateway를 찾아 Configure를 클릭하십시오.

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

4. Enable/Disable을 켜고, 결제 방법을 선택하고, 첫 테스트를 위해 Test Mode를 켜 둡니다. Save를 클릭하십시오.

5. 실결제를 하려면 Merchant ID, Hash Key, Hash IV(설정 항목 참조)를 입력하고, Test Mode를 끈 뒤 Save를 클릭하십시오.

설치 시 모듈은 두 개의 주문 상태 Awaiting ECPay payment와 ECPay payment on hold를 생성합니다. PrestaShop은 모든 통화, 국가, 고객 그룹에 대해 새 결제 모듈을 제공합니다. 이는 Payment > Preferences에서 제한할 수 있으며, 모듈에 대해 TWD는 허용된 상태로 유지되어야 합니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 필드 위에서 페이지는, 쇼핑몰에 TWD 통화가 없으면 오류를(이 경우 체크아웃에 ECPay가 표시되지 않음), 기본 통화가 TWD가 아니면 경고를(이 경우 TWD로 결제하는 고객에게만 ECPay가 표시됨) 보여 줍니다. 실운영 모드에서 MerchantID, HashKey, HashIV가 없으면 오류를 표시합니다. 테스트 모드가 켜져 있는 동안에는, 결제가 공개 테스트 가맹점 3002607을 사용하는 ECPay 샌드박스로 전송되며 실제 금액은 청구되지 않는다는 점, 그리고 공개 샌드박스 키를 아는 누구든 테스트 주문을 확정할 수 있다는 점을 경고합니다. 따라서 실제 주문을 받기 전에 테스트 모드를 반드시 끄십시오.

ECPay (綠界)

Enable/Disable: Enable ECPay Payment는 결제 방법을 켜거나 끕니다. 기본값: 꺼짐.

Title: 고객이 체크아웃에서 보는 결제 방법 이름입니다. 주문에 저장되는 결제 방법 이름이기도 합니다. 기본값: ECPay (綠界). 필수: 비워 두면 페이지를 저장할 수 없습니다.

Description: 체크아웃에서 결제 방법 아래에 표시되는 문구입니다. 기본값: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).

ECPay 계정

ECPay 가맹점 백오피스(vendor.ecpay.com.tw)의 System development management > System integration settings(系統開發管理 > 系統介接設定)에서 MerchantID, HashKey, HashIV를 확인하십시오.

Test Mode: 공개 ECPay 테스트 가맹점 3002607을 사용하여 결제를 ECPay 샌드박스(payment-stage.ecpay.com.tw)로 보냅니다. 실제 금액은 청구되지 않습니다. 아래의 인증 정보는 테스트 모드가 꺼져 있을 때만 사용됩니다. 기본값: 켜짐. 켜져 있는 동안 고객은 결제 방법 아래에서 TEST MODE — ECPay sandbox, no real money is charged.를 보게 됩니다.

Merchant ID: ECPay Merchant ID(실운영). 테스트 모드에서는 무시됩니다.

Hash Key: ECPay Hash Key(실운영). 테스트 모드에서는 무시됩니다.

Hash IV: ECPay Hash IV(실운영). 테스트 모드에서는 무시됩니다.

붙여넣은 인증 정보에 공백이나 줄바꿈이 있으면 모든 서명이 깨지므로, 저장할 때 자동으로 제거되며 페이지에 이를 알려 줍니다. 저장된 Hash Key와 Hash IV는 다시 표시되지 않습니다. 필드는 비어 있고 Saved — leave empty to keep it.가 표시됩니다. 값을 바꾸고 싶을 때만 새 값을 입력하십시오.

Clear saved secrets: Hash Key 또는 Hash IV에 체크하고 Save를 클릭하면 삭제됩니다. 빈 필드는 저장된 값을 유지합니다.

결제 옵션

Enabled Payment Methods: 고객에게 제공되는 결제 방법입니다. 둘 이상이면 고객이 체크아웃에서 선택합니다. ATM, CVS, 바코드 주문은 고객이 결제할 때까지 Awaiting ECPay payment 상태로 남습니다. 최소 한 가지 방법을 선택해야 하며, 하나도 선택하지 않으면 Credit Card가 활성화되고 페이지에 이를 알려 줍니다. 기본값: Credit Card.

Credit Card: ECPay 페이지에서 카드로 결제합니다.

ATM (Virtual Account): 고객은 가상 은행 계좌를 받고 송금합니다.

CVS (Convenience Store): 고객은 편의점에서 결제할 수 있는 결제 코드를 받습니다.

Barcode: 고객은 편의점 바코드를 받습니다.

Default Payment Method: 미리 선택되는 결제 방법입니다. 활성화된 결제 방법 중 하나여야 하며, 그렇지 않으면 활성화된 첫 번째 결제 방법이 사용됩니다. 기본값: Credit Card.

Order Prefix: ECPay 거래 번호(MerchantTradeNo)의 접두사이며, 최대 5자의 영문자 또는 숫자입니다. 저장할 때 다른 문자는 메시지와 함께 제거됩니다. 여러 쇼핑몰이 하나의 ECPay 계정을 공유할 때 유용합니다. 각 쇼핑몰에 고유한 접두사를 지정하십시오. 기본값: EC.

결제 알림

ECPay는 결제 결과를 쇼핑몰로 보냅니다. 이 섹션에는 Notification URL이 표시됩니다. 친숙한 URL을 사용하면 https://your-shop/module/wcp_ecpay_payment_gateway/notify와 같은 형태이며, /en/처럼 언어 코드가 붙을 수도 있습니다. 이 URL은 모든 결제와 함께 전송되므로 ECPay에서 따로 설정할 필요는 없습니다. 다만 인터넷에서 80/443 포트로 접근 가능해야 하며, 앞단에 방화벽이나 기본 인증이 없어야 합니다. 쇼핑몰의 유지 보수 모드와 국가 제한은 이를 차단하지 않습니다.

각 알림은 결제가 시작된 환경(테스트 또는 실운영)의 키로 CheckMacValue 서명을 검증하고, 해당 결제의 MerchantID도 검증합니다. 유효한 서명이 없는 알림은 거부되며, ECPay는 이를 다시 보냅니다. 알림이 없으면 주문이 생성되지 않으므로 ECPay 백오피스에서 결제를 확인하십시오.

고급

Enable Logging: 주문 ID, 거래 번호, 금액, ECPay 반환 코드를 모듈 폴더의 logs/ecpay_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 키나 고객 데이터는 기록되지 않습니다. 이 스위치가 꺼져 있어도 오류는 항상 기록됩니다. 기본값: 꺼짐.

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

Delete Data on Uninstall: 켜져 있으면 모듈을 제거할 때 설정과 로그가 삭제됩니다. ECPay 결제 기록과 주문 상태는 항상 보존되므로, 재설치 후에도 기존 주문이 계속 작동합니다. 기본값: 꺼짐.

체크아웃

결제 단계에서 고객은 결제 방법을 선택합니다(기본값은 ECPay (綠界)). 여러 방법이 활성화되어 있으면 고객은 Payment Method 아래에서 Credit Card, ATM (Virtual Account), CVS (Convenience Store), Barcode 중에서도 선택할 수 있습니다.

확인 후 고객에게는 Redirecting to ECPay for payment. Please wait...이 표시되고 ECPay 결제 페이지로 이동합니다. 리디렉션이 시작되지 않을 경우를 대비해 Proceed to ECPay 버튼도 제공됩니다. 장바구니 합계는 상품명과 수량과 함께 정수 TWD로 전송됩니다. ECPay 페이지는 대만 및 홍콩 언어에 대해서는 번체 중국어로, 해당 언어들에 대해서는 간체 중국어, 한국어, 일본어로 열리며, 그 밖의 모든 언어에 대해서는 영어로 열립니다. 고객 쇼핑몰의 언어를 따릅니다. 이 시점에는 아직 주문이 없습니다.

주문은 ECPay가 서명된 서버 알림으로 확인한 후에만 생성됩니다. 고객이 ECPay 페이지에서 쇼핑몰로 돌아가는 링크를 클릭했을 때 주문이 이미 존재하면, 표준 주문 확인 페이지가 열립니다. 결제 완료된 주문에는 Your ECPay payment has been received.가, 검토 중인 주문에는 Your ECPay payment was received and is being reviewed by the store.가 표시되며, 입금 대기 중인 ATM, CVS, 바코드 주문에는 결제 안내가 표시됩니다. 알림이 아직 도착하지 않았다면 Payment confirmation 페이지에 We have not received a payment confirmation from ECPay for this order yet. Your order will be created as soon as ECPay confirms the payment.와 함께 Check again 및 Back to checkout 버튼이 표시됩니다. ECPay가 결제 실패를 보고했다면, 고객은 The payment was not completed. You can try again or choose another payment method.와 함께 체크아웃으로 돌아갑니다. 장바구니는 유지됩니다.

ATM, CVS, 바코드의 경우 고객은 먼저 결제 정보를 받습니다. 주문은 Awaiting ECPay payment 상태로 생성되며, 은행 코드와 가상 계좌, 편의점 결제 코드 또는 바코드, 금액, Pay before 기한이 주문 확인 페이지와 고객의 주문 상세 정보에 있는 ECPay payment instructions 아래에 표시됩니다. 고객이 결제하면 ECPay가 또 다른 알림을 보내고, 주문은 결제 완료로 표시됩니다. 결제 안내는 PrestaShop 이메일에 포함되지 않습니다.

ECPay는 재사용된 번호를 거부하므로, 시도할 때마다 새로운 ECPay 거래 번호가 생성됩니다. 따라서 결제 실패 후 재시도가 작동하며, 고객이 브라우저에서 리디렉션 페이지로 돌아가면 새 시도가 시작됩니다. 하나의 장바구니는 최대 30회까지 결제를 시도할 수 있습니다. 장바구니에 주문이 생성되면 체크아웃을 통해 다시 결제할 수 없으며, 입금 대기 중인 ATM 또는 CVS 주문은 이미 발급된 결제 정보로 결제합니다.

결제를 시작할 수 없으면 고객은 짧은 메시지와 함께 체크아웃에 머뭅니다. 예를 들어 반올림 후 합계가 1 TWD 미만이면 The order total is too small for ECPay.가 표시됩니다. 결제 방법별 ECPay의 금액 한도는 체크아웃이 아니라 ECPay 페이지에서 확인합니다.

이 모듈은 ECPay 페이지에서만 일회성 결제를 받습니다. PrestaShop에서의 환불, 저장된 카드, 구독 또는 정기 결제(定期定額), 할부, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, 전자 세금계산서, 물류는 지원하지 않으며, 서버 측 상태 조회도 하지 않습니다. 쇼핑몰이 알림을 받을 수 없다면 ECPay 백오피스에서 결제를 확인하십시오.

주문

주문 상태

No order yet: 고객이 ECPay로 이동했으며 아직 결제하지 않았거나, 알림이 아직 도착하지 않았습니다. 장바구니만 존재합니다.

Awaiting ECPay payment: 고객이 ATM, CVS 또는 바코드를 선택했고 결제 정보를 받았습니다. 메모에는 은행 코드와 가상 계좌, 결제 코드 또는 바코드, 기한이 표시됩니다.

Payment accepted: 결제가 확인되었습니다. 결제는 ECPay TradeNo를 거래 ID로 하여 기록되며, 메모에는 TradeNo, 결제 유형, 금액, 거래 번호가 표시됩니다(샌드박스 결제에는 테스트 모드 표시가 붙습니다).

ECPay payment on hold: ECPay가 장바구니와 다른 금액이나 통화를 보고했을 때(예: 결제가 시작된 후 다른 탭에서 장바구니가 변경된 경우), 실운영 모드로 전환한 후 샌드박스 결제가 도착했을 때(실제 금액은 청구되지 않았습니다), 또는 주문이 취소된 후 결제가 도착했을 때(이 경우 결제는 기록됩니다)에 이 상태가 됩니다. 메모에 그 이유가 설명되어 있습니다. ECPay 백오피스와 대조한 후, 주문을 처리하거나 그곳에서 결제를 환불하십시오.

Payment error: ECPay가 입금 대기 중인 주문의 최근 ATM, CVS 또는 바코드 결제가 실패했다고 보고했습니다. 메모에는 ECPay 반환 코드와 메시지가 표시됩니다.

중복된 알림은 무시됩니다. 결제 완료, 환불 또는 취소된 주문은 늦게 도착한 실패 알림으로 다시 열리지 않습니다. 이미 결제된 주문에 대한 두 번째 결제(예: 브라우저 탭 두 개에서 결제한 경우)는 메모로 한 번 기록되므로, ECPay 백오피스에서 환불할 수 있습니다. ECPay 백오피스에서 시작한 시뮬레이션 결제는 메모로만 기록되며, ECPay가 해당 결제에 대해 금액을 받지 않으므로 주문을 결제 완료로 표시하지 않습니다.

ECPay 결제 블록

주문 페이지에는 주문의 모든 결제 시도를 보여 주는 ECPay payment 블록이 표시됩니다. 여기에는 샌드박스 시도를 위한 Test mode 배지가 붙은 MerchantTradeNo, 결제 방법, TWD 금액, 상태, ECPay TradeNo, 결제 유형과 날짜, ECPay 반환 코드가 포함됩니다. 그 아래에는 주문의 ECPay notes가 있습니다. ECPay payment on hold 상태의 주문에 대해 이 블록은 ECPay 백오피스와 대조하라고 알려 줍니다.

환불

PrestaShop에서는 환불할 수 없습니다. ECPay 백오피스에서 결제를 환불한 다음, PrestaShop에서 주문을 수동으로 업데이트하십시오. 주문 페이지의 표준 PrestaShop 환불 버튼은 ECPay를 통해 돈을 돌려주지 않습니다.

라이선스 키

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

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

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

문제 해결

체크아웃에 ECPay가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 고객의 장바구니가 TWD인지, 그리고 실운영 모드에서 Merchant ID, Hash Key, Hash IV가 설정되어 있는지 확인하십시오. 설정 페이지에는 이 각각의 경우에 대한 메시지가 표시됩니다. Payment > Preferences에서 모듈이 TWD, 고객의 국가, 고객의 그룹에 대해 허용되어 있는지 확인하십시오.

결제는 완료되었지만 주문이 생성되지 않음: ECPay 알림이 쇼핑몰에 도달하지 못했습니다(사이트 다운, 방화벽, 기본 인증). ECPay는 여러 번 재시도합니다. ECPay 백오피스에서 거래를 확인할 수도 있습니다. 모듈이 받은 알림을 보려면 Enable Logging을 켜십시오. 거부된 알림은 어떤 경우에도 오류로 기록됩니다.

알림 응답이 0|CheckMacValue verification failed: Hash Key 또는 Hash IV가 ECPay 계정과 일치하지 않거나, 결제가 다른 환경에서 시작되었습니다. ECPay 백오피스에서 다시 복사하십시오.

알림 응답이 0|MerchantID mismatch: 알림이 결제를 시작한 것과 다른 ECPay 가맹점에 속합니다.

알림 응답이 0|Order not found: 이 쇼핑몰이 거래 번호를 발급하지 않았습니다. 예를 들어 여러 쇼핑몰이 하나의 ECPay 계정을 공유하는 경우입니다. 각 쇼핑몰에 고유한 Order Prefix를 지정하십시오.

알림 응답이 0|Retry: 같은 시점에 다른 알림이 장바구니를 처리하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화된 경우). ECPay가 알림을 다시 보냅니다. 이유를 보려면 Enable Logging을 켜십시오.

알림 URL이 0|Method not allowed in the browser를 표시: 정상입니다. 이 URL은 ECPay의 요청만 받습니다.

고객이 「The order total is too small for ECPay.」를 봄: 반올림 후 장바구니 합계가 1 TWD 미만이어서 ECPay로 결제할 수 없습니다.

고객이 「Too many payment attempts for this order」를 봄: 장바구니가 30회의 결제 시도에 도달했습니다. 고객에게 새 장바구니를 시작하도록 요청하십시오.

주문이 ECPay payment on hold 상태임: ECPay payment 블록의 메모를 읽고(주문 상태 항목 참조), ECPay 백오피스와 대조한 후, 주문을 처리하거나 그곳에서 결제를 환불하십시오.

개발자: actionEcpayPRequestParams 훅을 사용하면 다른 모듈이 ECPay로 보내는 매개변수를 변경할 수 있습니다. 다만 가맹점, 거래 번호, 금액은 이 훅으로 변경할 수 없습니다.

제거

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

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