VibeFox ePay.bg for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

통화: 불가리아 레프(BGN), 유로(EUR) 또는 미국 달러(USD). 장바구니는 자체 통화로 소수점 2자리까지 청구됩니다. 다른 통화의 장바구니는 체크아웃에서 결제 수단이 숨겨집니다.

ePay.bg 계정: ePay.bg 가맹점 프로필의 고객 번호(MIN)와 비밀 키가 필요합니다. 운영용은 www.epay.bg에서, 테스트용은 demo.epay.bg에서 확인합니다(테스트 계정은 별도로 등록합니다). 또한 쇼핑몰의 알림 URL을 가맹점 프로필에 입력해야 합니다.

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

설치

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

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

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

4. 테스트 및/또는 운영 MIN과 비밀 키를 입력합니다(설정 참조).

5. Payment notifications (IPN) 섹션에 표시된 URL을 ePay.bg 가맹점 프로필의 URL for receiving notifications 필드에 복사합니다. 데모 프로필과 운영 프로필 모두에 입력하세요. 이 설정이 없으면 주문이 생성되지 않습니다.

6. Enable/Disable을 켜고 Save를 클릭합니다. 테스트 모드에서 테스트 주문을 하나 한 뒤 Test Mode를 끕니다.

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

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox ePay.bg Gateway > Configure. 각 Save 버튼은 페이지 전체를 저장합니다. 필드 위에는 쇼핑몰의 기본 통화가 BGN, EUR 또는 USD가 아니면 오류가, 게이트웨이가 켜져 있는데 선택한 모드의 MIN 또는 비밀 키가 비어 있으면 경고가 표시됩니다(이 경우 체크아웃에서 숨겨지며, 저장 시 같은 경고가 표시됩니다). 그리고 테스트 모드가 켜져 있는 동안에는 Test mode is on: payments go to demo.epay.bg and no real money is charged.가 표시됩니다.

ePay.bg

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

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

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely via ePay.bg with a bank card or your ePay.bg account.

ePay.bg 계정

고객 번호(MIN)와 비밀 키는 www.epay.bg(운영)와 demo.epay.bg(테스트 계정, 별도 등록)의 가맹점 프로필에 표시됩니다.

Test Mode: 테스트 모드를 켭니다. 고객은 ePay.bg 데모 환경으로 이동하며, 요청은 테스트 자격 증명으로 서명됩니다. 기본값: 켬.

Test Merchant ID (MIN): demo.epay.bg 가맹점 계정의 고객 번호(MIN)입니다.

Test Secret Key: demo.epay.bg 가맹점 계정의 비밀 키(64자)입니다.

Live Merchant ID (MIN): www.epay.bg 가맹점 계정의 고객 번호(MIN)입니다.

Live Secret Key: www.epay.bg 가맹점 계정의 비밀 키(64자)이며 HMAC-SHA1 서명에 사용됩니다.

저장된 비밀 키는 다시 표시되지 않습니다. 필드는 비어 있으며 Saved — leave empty to keep it.를 표시합니다. 변경하려는 경우에만 새 값을 입력하세요. 붙여넣은 키의 공백과 줄바꿈은 저장할 때 제거됩니다.

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

Payment notifications (IPN)

알림은 결제 요청이 결제되었거나, 거부되었거나, 만료되었음을 쇼핑몰에 알립니다. Notification URL 필드는 ePay.bg 가맹점 프로필의 URL for receiving notifications에 입력할 URL을 보여 줍니다. 운영과 테스트 모두에 해당합니다. 친숙한 URL을 사용하는 경우 https://your-shop/module/wcp_epaybg_gateway/notify 형태이며, /en/ 같은 언어 코드가 포함될 수 있습니다. 설정에 표시된 URL을 정확히 그대로 복사하세요. 주문은 이 서명된 알림으로만 생성됩니다. 고객이 쇼핑몰로 돌아오는 것만으로는 주문이 생성되거나 결제되지 않습니다.

ePay.bg는 각 청구서에 대해 다음 결과를 보고합니다:

유효한 체크섬이 없는 알림은 거부되며, ePay.bg는 계속 알림을 보냅니다. 체크섬은 키가 있는 각 모드의 비밀 키로 확인하므로, 테스트와 운영 사이를 전환하기 전에 시작된 결제도 계속 확인됩니다. 결제는 요청이 만들어진 모드로 도착해야 합니다. 그렇지 않으면 주문이 ePay.bg payment on hold 상태가 됩니다. 가맹점 프로필에 알림 URL이 없으면 주문이 생성되지 않습니다.

Payment request

Invoice Prefix: 숫자만 가능(최대 10자리). 장바구니 ID 앞에 붙여 ePay.bg 청구서 번호를 만듭니다. 예: 00001 + 123 = 00001123. 같은 ePay.bg 계정에서 여러 쇼핑몰을 운영한다면 쇼핑몰마다 다른 접두사를 사용하세요. 저장할 때 다른 문자는 경고와 함께 제거됩니다. 나중에 접두사를 바꿔도 안전합니다. 열린 결제 요청은 각 요청에 저장된 청구서로 찾습니다. 기본값: 00001.

Expiration Time: 결제되지 않은 결제 요청이 만료되는 시간입니다. 만료되면 ePay.bg는 만료된 것으로 보고하며 주문은 생성되지 않습니다. 1, 3, 6, 12, 24, 48 또는 72시간 중에서 선택합니다. 이 시간은 쇼핑몰의 시간대와 관계없이 불가리아 시간으로 전송됩니다. 기본값: 24시간.

Language: ePay.bg 결제 페이지의 언어(영어 또는 불가리아어)입니다. 기본값: 영어.

Order Status After Payment: 결제 성공 후 설정되는 주문 상태입니다.

Advanced

Logging: 결제 요청과 알림을 모듈 폴더의 logs/epay_bp_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 비밀 키와 카드 데이터는 기록되지 않습니다. 기본값: 끔. 꺼져 있어도 오류는 항상 기록됩니다.

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

Delete Data on Uninstall: 켜져 있으면 모듈을 제거할 때 게이트웨이 설정과 로그가 삭제됩니다. ePay.bg 결제 기록, ePay.bg payment on hold 주문 상태, 주문은 항상 보존됩니다. 기본값: 끔.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 ePay.bg)을 선택하고 확인합니다. 고객에게는 Redirecting to ePay.bg for payment...가 표시되며, 장바구니 통화로 된 장바구니 합계, 청구서 번호, 만료 시간이 포함된 서명된 결제 요청과 함께 ePay.bg로 이동합니다. ePay.bg에서 결제는 Cart와 장바구니 번호로 표시됩니다. 리디렉션이 시작되지 않을 경우를 대비해 페이지에는 Pay via ePay.bg 버튼과 Cancel 버튼도 있습니다. ePay.bg에서 고객은 은행 카드 또는 ePay.bg 계정으로 결제합니다. 이 시점에는 아직 주문이 없습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 서명된 ePay.bg 알림이 도착했을 때만 생성됩니다. 이미 도착했다면 고객은 표준 주문 확인 페이지를 보게 됩니다. 도착하지 않았다면 Payment confirmation 페이지에 Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. 문구가 표시되고 Check again 및 Back to checkout 버튼이 나타납니다.

고객이 ePay.bg에서 취소하면 체크아웃으로 돌아가며 The ePay.bg payment was cancelled. You can try again or choose another payment method. 메시지가 표시됩니다. ePay.bg가 요청을 거부 또는 만료로 보고한 경우 메시지는 The payment was not completed. You can try again or choose another payment method.입니다. 장바구니는 유지됩니다. 같은 장바구니로 다시 시도하면 같은 청구서 번호를 사용합니다.

장바구니를 ePay.bg로 결제할 수 없으면 고객은 짧은 메시지(예: ePay.bg payments are temporarily unavailable. Please choose another payment method. 또는 ePay.bg가 장바구니 통화의 결제를 받지 않는다는 내용)와 함께 체크아웃에 머뭅니다.

알림은 쇼핑몰이 유지 보수 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다.

모듈은 ePay.bg에서의 일회성 결제만 받습니다. PrestaShop에서의 환불, 저장된 카드, 구독 또는 정기 결제, EasyPay 또는 B-Pay 현금 결제 코드는 지원하지 않습니다.

주문

주문 상태

No order yet: 고객이 ePay.bg로 이동했지만 결제하지 않았거나, 알림이 아직 도착하지 않았거나, ePay.bg가 요청을 거부 또는 만료로 보고한 상태입니다. 장바구니만 존재합니다.

Payment accepted, Delivered or ePay.bg payment on hold: 결제가 확인되었습니다. 상태는 Order Status After Payment를 따릅니다. 결제는 STAN을 거래 ID로 하여 기록되며(STAN이 없으면 청구서 번호), 메모에는 청구서 번호, 결제 날짜, STAN, BORICA 코드가 표시됩니다.

ePay.bg payment on hold after payment: 결제는 도착했지만 현재 장바구니의 내용과 맞지 않습니다. 결제 요청 이후 장바구니 합계나 통화가 변경되었거나, 알림이 요청과 다른 모드(테스트 또는 운영)로 도착한 경우입니다. 결제는 완료된 것으로 기록되지 않습니다. 장바구니에 이미 결제되지 않은 주문(취소된 주문이나 다른 결제 수단으로 생성된 주문 등)이 있는 경우에도 같은 일이 발생합니다. 메모에 이유가 설명됩니다. ePay.bg 가맹점 패널에서 결제를 확인한 후 주문을 수동으로 처리하거나 환불하세요.

이미 결제 완료되었거나 환불된 주문에 대해 결제가 도착하면 상태는 변경되지 않으며, 메모는 ePay.bg 가맹점 패널에서 이중 결제가 있는지 확인하라고 안내합니다. 뒤늦게 도착한 거부 또는 만료 알림이 결제 완료된 주문을 변경하는 일은 없습니다.

ePay.bg 결제 블록

주문 페이지에는 청구서, 요청된 금액과 통화, 알림 결과, 결제 날짜, STAN, BORICA 코드, 테스트 결제용 Test mode 배지, 주문의 ePay.bg notes가 포함된 ePay.bg payment 블록이 표시됩니다.

환불

ePay.bg WEB API에는 환불 호출이 없으므로 PrestaShop에서는 환불을 사용할 수 없습니다. ePay.bg 가맹점 패널에서 결제를 환불하고, PrestaShop에서 주문을 수동으로 업데이트하세요.

라이선스 키

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

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

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

문제 해결

체크아웃에 ePay.bg가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 선택한 모드의 MIN과 비밀 키가 설정되어 있는지, 장바구니 통화가 BGN, EUR 또는 USD인지 확인하세요. 자격 증명이 없으면 설정 페이지에 경고가 표시됩니다. Payment > Preferences에서 모듈이 장바구니 통화, 고객의 국가, 고객 그룹에 대해 허용되어 있는지 확인하세요.

결제는 완료되었지만 주문이 생성되지 않음: 주문은 ePay.bg 알림으로만 생성됩니다. 사용 중인 모드(데모 또는 운영)의 ePay.bg 가맹점 프로필에 Notification URL에 표시된 그대로 알림 URL이 입력되어 있는지, 그리고 해당 모드의 비밀 키가 올바른지 확인하세요. 모듈 페이지의 Log 필드를 보고, 모든 알림을 보려면 Logging을 켜세요.

알림이 ERR=Not valid CHECKSUM으로 응답함: 저장된 비밀 키 중 알림을 보낸 가맹점 프로필과 일치하는 키가 없습니다. ePay.bg는 계속 재시도하므로, 키가 올바르게 되면 주문이 생성됩니다.

알림이 ERR=Not configured로 응답함: 저장된 비밀 키가 없습니다. 입력하세요.

알림이 청구서에 대해 STATUS=NO로 응답함: 이 쇼핑몰이 발행하지 않은 청구서입니다. 예를 들어 같은 ePay.bg 계정의 다른 쇼핑몰이 발행했을 수 있습니다. 쇼핑몰마다 고유한 Invoice Prefix를 지정하세요.

알림이 STATUS=ERR로 응답함: 일시적인 오류입니다. 예를 들어 같은 장바구니에 대해 같은 순간에 알림 두 개가 도착했거나, 주문을 생성할 수 없었던 경우(예: 모듈이 비활성화됨)입니다. ePay.bg는 알림을 다시 보냅니다. 이유는 로그에 있습니다.

브라우저에서 알림 URL이 ERR=Method not allowed in the browser를 표시함: 정상입니다. 이 URL은 ePay.bg의 요청만 받습니다.

결제 후 주문이 ePay.bg payment on hold 상태임: ePay.bg payment 블록의 메모를 읽고(주문 상태 참조), ePay.bg 가맹점 패널에서 결제를 확인한 후 주문을 처리하거나 그곳에서 결제를 환불하세요.

저장할 때 청구서 접두사가 변경됨: 접두사는 숫자만 포함할 수 있으며 최대 10자리입니다. 다른 문자는 제거됩니다.

개발자의 경우, readme에는 WooCommerce 버전의 epay_bp_form_fields 필터인 actionEpayBpFormFields 훅이 언급되어 있습니다. 예를 들어 카드 직접 결제 페이지(PAGE=credit_paydirect)를 사용하는 경우에 쓸 수 있습니다.

제거

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

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