VibeFox Eupago for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0부터 9.x까지.

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

통화: 유로(EUR). Eupago는 유로로만 결제를 처리하므로, 다른 통화의 장바구니에서는 체크아웃에 해당 결제 방법이 표시되지 않습니다.

Eupago 계정: Eupago 채널의 API 키와, Eupago 백오피스에서 생성한 Webhook 2.0의 키가 필요합니다(설정 참조). 운영 백오피스는 clientes.eupago.pt이고, 샌드박스 백오피스는 sandbox.eupago.pt입니다. 샌드박스와 운영은 별도 계정이며 키도 각각 다릅니다.

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

설치

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

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

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

4. Eupago 채널의 API 키를 입력하고, Eupago 백오피스에서 Webhook 2.0을 생성한 뒤 그 키를 붙여 넣습니다(설정 참조).

5. Payment Method를 선택하고, Enable/Disable을 켠 다음 Save를 클릭합니다. 샌드박스 모드에서 테스트 주문을 한 뒤 Sandbox Mode를 끕니다.

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

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Eupago Gateway > Configure. 각 섹션에는 별도의 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. 결제 방법이 활성화되어 있을 때 현재 모드의 API 키가 비어 있으면, 항목 위에 경고가 표시됩니다(이 경우 체크아웃에서 결제 방법이 숨겨집니다). 샌드박스 모드가 켜져 있는 동안에는 Sandbox mode: no real payments are taken. 문구가 표시됩니다.

Eupago

Enable/Disable: Enable Eupago Gateway는 결제 방법을 켜거나 끕니다. 기본값: 끔.

Title: 고객이 체크아웃에서 보는 결제 방법 이름입니다. 주문에 저장되는 결제 방법 이름이기도 합니다. 기본값: Eupago. 필수: 제목이 비어 있으면 Enter a title for the payment method.가 표시됩니다.

Description: 체크아웃에서 결제 방법 아래에 표시되는 텍스트입니다. 기본값: Pay securely via Eupago.

Payment Method: 체크아웃에서 제공되는 Eupago 결제 방법은 하나뿐입니다.

Multibanco: 고객은 ATM 또는 인터넷뱅킹에서 결제할 수 있도록 기관 번호와 참조 번호를 받습니다(기본값). 주문 금액 1 € ~ 999,999.99 €에 대해 제공됩니다.

MB WAY: 고객은 체크아웃에서 MB WAY 전화번호를 입력하고 MB WAY 앱에서 결제를 승인합니다.

Credit Card: 고객은 Eupago 카드 결제 페이지로 이동합니다.

Order Status After Payment: 결제가 확인되었을 때 설정되는 주문 상태입니다.

Processing (default): 주문이 Payment accepted가 됩니다.

Completed: 주문이 한 번의 상태 변경으로 Delivered가 됩니다.

Eupago 계정

Eupago 백오피스에서 채널의 API 키와 Webhook 2.0 키를 확인하세요: clientes.eupago.pt(운영) 또는 sandbox.eupago.pt(샌드박스). 샌드박스와 운영은 별도 계정이며 키도 각각 다릅니다.

Sandbox Mode: sandbox.eupago.pt와 샌드박스 키를 사용합니다. 실제 결제는 이루어지지 않습니다. 기본값: 켬. 운영 키로 실제 결제를 받으려면 끄세요. 켜져 있는 동안 고객은 결제 방법 아래에 SANDBOX / TEST MODE를 보게 됩니다.

Live API Key: 운영 Eupago 채널의 API 키(clientes.eupago.pt)입니다.

Live Webhook Key: 운영 Webhook 2.0의 암호화 키입니다. 필수: 유효한 서명이 없는 알림은 거부됩니다.

Sandbox API Key: 샌드박스 채널의 API 키(sandbox.eupago.pt)입니다.

Sandbox Webhook Key: 샌드박스 Webhook 2.0의 암호화 키입니다.

저장된 키는 다시 표시되지 않습니다. 필드는 비어 있으며 Saved — leave empty to keep it.가 표시됩니다. 값을 바꾸고 싶을 때만 새 값을 입력하세요.

Clear saved keys: 키에 체크하고 Save를 클릭하면 삭제됩니다. 필드가 비어 있으면 저장된 값이 유지됩니다.

웹훅 URL

웹훅은 쇼핑몰에 결제가 이루어졌음을 알려 줍니다. Eupago 백오피스에서 이 섹션에 표시된 URL, 메서드 POST, 암호화 사용을 지정하여 Webhook 2.0을 만드세요. 친숙한 URL을 사용하면 https://your-shop/module/wcp_eupago_gateway/webhook 같은 형태가 되며, /pt/ 같은 언어 코드가 붙을 수도 있습니다. URL은 설정에 표시된 그대로 정확하게 복사하세요. 샌드박스 백오피스와 운영 백오피스에 각각 웹훅을 하나씩 만드세요.

각 웹훅의 키를 Sandbox Webhook Key 또는 Live Webhook Key에 복사하세요. 유효한 서명이 없는 웹훅은 거부됩니다. 암호화되지 않은 웹훅은 Eupago가 서명한 경우에만 허용되므로 암호화는 켜 두세요. 알림은 결제를 시작한 모드의 키로 서명되어야 하므로, 샌드박스 알림이 운영 결제를 완료하는 일은 없습니다. 모듈은 다음 알림 상태에 반응합니다:

PAID: 결제가 완료되었습니다. 모든 검사를 마친 후 주문이 결제 완료로 표시됩니다.

CANCELED: 결제가 취소되었습니다. 대기 중인 주문은 Canceled가 됩니다.

EXPIRED: 결제 기한이 만료되었습니다. 대기 중인 주문은 Canceled가 됩니다.

ERROR: 결제에 실패했습니다. 대기 중인 주문은 Payment error가 됩니다.

그 밖의 상태에서는 조치가 필요 없습니다. 같은 URL로 들어오는 Eupago의 기존 GET 콜백도 허용됩니다. 이 콜백은 API 키로 인증되며 항상 결제를 알립니다. 알림이 없으면 주문은 결코 결제 완료로 표시되지 않습니다. 모듈은 Eupago를 폴링하지 않으며, 고객이 쇼핑몰로 돌아와도 주문이 결제 완료되지 않습니다. 웹훅은 쇼핑몰이 유지 보수 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다.

고급

Debug Log: API 호출과 알림을 모듈 폴더의 logs/eupago_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 키, 이메일, 전체 전화번호는 기록되지 않습니다. 오류는 항상 기록됩니다. 기본값: 끔.

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

Delete Data on Uninstall: 켜져 있으면 모듈을 제거할 때 게이트웨이 설정, 이 모듈의 Eupago 결제 기록, 로그가 삭제됩니다. 주문과 주문의 결제 데이터는 유지됩니다. 기본값: 끔.

체크아웃

고객은 결제 단계에서 결제 방법(기본값 Eupago)을 선택하고 주문합니다. 그 이후의 동작은 Payment Method에 따라 달라집니다.

Multibanco: 체크아웃에서 고객에게 You will receive Multibanco payment details after placing the order.가 표시됩니다. 모듈은 장바구니 합계에 대한 Multibanco 참조 번호를 생성합니다. 주문은 일반 PrestaShop 주문과 마찬가지로 즉시 Awaiting Eupago payment 상태로 생성되고, 장바구니는 비워집니다. 주문 확인 페이지에는 기관, 참조 번호, 금액이 포함된 Multibanco Payment Details가 표시됩니다. 같은 정보가 주문 확인 이메일의 결제 항목에도 추가됩니다. 고객은 ATM 또는 인터넷뱅킹에서 결제합니다.

MB WAY: 체크아웃에서 고객은 MB WAY Phone Number를 입력합니다. 이 항목에는 청구지 주소의 전화번호가 미리 채워집니다. 포르투갈 번호는 +351 없이 입력할 수 있습니다. 잘못된 번호를 입력하면 Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678).가 표시됩니다. 모듈은 결제 요청을 MB WAY 앱으로 보내고, 주문을 Awaiting Eupago payment 상태로 생성합니다. 주문 확인 페이지는 고객에게 마스킹된 전화번호의 MB WAY 앱을 열고 5분 안에 요청을 승인하도록 안내합니다.

Credit Card: 체크아웃에서 고객에게 You will be redirected to a secure payment page to enter your card details.가 표시됩니다. 고객은 장바구니 언어에 따라 포르투갈어, 스페인어 또는 영어로 된 Eupago 카드 결제 페이지로 이동합니다. 아직 주문은 없으며 장바구니는 유지됩니다. 주문은 Eupago가 결제를 확인한 후에만 생성됩니다. 고객이 돌아왔을 때 알림이 이미 도착했다면 표준 주문 확인 페이지가 표시됩니다. 그렇지 않으면 Payment confirmation 페이지에 Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed.가 표시되고 Check again 버튼이 나타납니다. 카드 결제가 실패하거나 중단되면, 고객은 The card payment was not completed. You can try again or choose another payment method. 또는 The card payment was cancelled. You can try again or choose another payment method. 메시지와 함께 체크아웃으로 돌아갑니다.

모든 방법에서 주문은 Eupago가 검증된 알림으로 결제를 확인한 후에만 결제 완료로 표시됩니다. 결제 정보는 주문이 Awaiting Eupago payment 상태인 동안에만 표시됩니다. 이후 Eupago가 결제가 취소되었거나, 기한이 만료되었거나, 실패했다고 알렸는데 주문이 결제되지 않은 상태라면, 주문 확인 페이지에 Your Eupago payment was not completed. Please contact us about this order.가 표시됩니다.

Eupago가 결제를 시작할 수 없으면, 고객은 체크아웃에 남아 짧은 메시지를 보게 됩니다. 예를 들면 The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method.입니다. 주문은 생성되지 않으며, 자세한 내용은 로그에 있습니다. 다른 통화의 장바구니에서는 Eupago only supports payments in EUR.가 표시됩니다.

모듈은 설치당 하나의 Eupago 결제 방법만 제공합니다. PrestaShop에서의 환불, 카드 저장, 구독, 사전 승인은 지원하지 않습니다. PayShop, Cofidis Pay, Bizum 또는 다른 Eupago 결제 방법, SMS 알림, Multibanco 만료일, 상태 폴링도 지원하지 않습니다.

주문

주문 상태

No order yet: 카드 결제가 시작되었지만 Eupago가 아직 확인하지 않은 상태입니다. 장바구니만 존재합니다.

Awaiting Eupago payment: Multibanco 참조 번호 또는 MB WAY 요청이 생성되었습니다. 메모에는 기관과 참조 번호, 또는 마스킹된 전화번호가 표시됩니다.

Payment accepted or Delivered: 결제가 확인되었습니다. 상태는 Order Status After Payment 설정을 따릅니다. 결제는 Eupago 거래 ID를 거래 ID로 하여 기록되며, 메모에는 결제 방법, 거래 ID, 참조 번호가 표시됩니다.

Eupago payment on hold: Eupago가 금액이나 통화가 다른 결제, 이 장바구니를 위해 생성되지 않은 참조 번호로 이루어진 결제, 또는 그사이 취소되었거나 실패한 주문에 대한 결제(예: 늦게 결제된 Multibanco 참조 번호)를 보고했습니다. 메모에 이유가 설명되어 있습니다. 결제와 재고를 확인한 다음, 주문을 수동으로 완료하거나 고객에게 환불하세요. 이 결제에 대한 이후 알림은 주문을 사용자 몰래 완료하지 않습니다.

Canceled: 대기 중인 주문의 현재 결제 시도에 대해 Eupago가 결제가 취소되었거나 만료되었다고 보고했습니다.

Payment error: 대기 중인 주문의 현재 결제 시도에 대해 Eupago가 오류를 보고했습니다.

이미 결제된 주문에 대해 Eupago가 다른 결제를 보고하면(예: 이전 Multibanco 참조 번호도 결제된 경우), 주문은 변경되지 않습니다. 메모에서 중복 결제가 있는지 확인하고 Eupago 백오피스에서 환불하라고 안내합니다. 결제 완료 후 취소되거나 환불된 주문은 결제 알림으로 다시 열리지 않습니다.

Eupago 결제 블록

주문 페이지에는 장바구니의 모든 결제 시도를 보여 주는 Eupago payment 블록이 표시됩니다. 날짜, 결제 방법, 샌드박스 결제를 나타내는 Sandbox 배지, 금액, Multibanco 기관과 참조 번호 또는 MB WAY의 마스킹된 전화번호, Eupago 거래 ID, 상태가 포함됩니다. 주문이 Eupago payment on hold 상태인 동안 이 블록에는 Manual review 경고가 표시됩니다. 그 아래의 Eupago notes에는 주문에 대한 모듈 메모가 최신순으로 나열됩니다.

환불

PrestaShop에서의 환불은 지원하지 않습니다. Eupago 백오피스에서 고객에게 환불하고, PrestaShop에서 주문을 수동으로 업데이트하세요. 주문 페이지의 표준 PrestaShop 환불 버튼은 Eupago를 통해 돈을 돌려주지 않습니다.

라이선스 키

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

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

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

문제 해결

체크아웃에 Eupago가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드의 API 키가 설정되어 있는지 확인하세요(샌드박스 모드에서는 Sandbox API Key, 운영 모드에서는 Live API Key). 장바구니 통화는 EUR이어야 하며, Payment > Preferences에서 유로, 고객의 국가, 고객의 그룹에 대해 모듈이 허용되어 있어야 합니다. Multibanco의 경우 주문 합계가 1 € ~ 999,999.99 € 사이여야 합니다.

결제는 되었는데 주문이 계속 Awaiting Eupago payment 상태이거나 주문이 생성되지 않음: Eupago 알림이 도착하지 않았거나 거부되었습니다. 사용 중인 모드의 Eupago 백오피스에서 Webhook 2.0이 존재하는지, URL이 Webhook URL에 표시된 것과 정확히 같은지, 메서드가 POST이고 암호화가 켜져 있는지 확인하세요. 그 키가 해당 필드(Sandbox Webhook Key 또는 Live Webhook Key)에 있는지 확인하세요. Debug Log를 켜고 모듈 페이지의 Log 필드를 확인하세요. 알림이 전혀 도착하지 않으면 Eupago 백오피스에서 결제를 확인하세요.

웹훅이 Invalid signature 또는 Missing signature로 응답함: 모듈의 웹훅 키가 웹훅의 키와 일치하지 않거나, 웹훅이 암호화도 서명도 되어 있지 않습니다. 키를 다시 복사하고 암호화를 켜 두세요.

웹훅이 Webhook key not configured로 응답함: 웹훅 키가 하나도 설정되지 않았습니다. 키를 붙여 넣으면 Eupago가 알림을 다시 시도합니다.

웹훅이 Decryption failed로 응답함: 서명은 유효하지만 본문을 복호화할 수 없습니다. Eupago 백오피스에서 Webhook 2.0 설정을 확인하세요.

웹훅이 Environment mismatch로 응답함: 알림이 결제를 시작한 모드와 다른 모드의 키로 서명되었습니다. 샌드박스 알림이 운영 결제를 완료하는 일은 없으며, 그 반대도 마찬가지입니다. 샌드박스 키와 운영 키가 서로 바뀌지 않았는지 확인하세요.

웹훅이 Order not found로 응답함: 알림이 이 쇼핑몰의 Eupago 결제가 없는 장바구니에 대한 것입니다. 예를 들어 같은 Eupago 채널을 사용하는 다른 쇼핑몰에서 이루어진 결제가 해당합니다.

웹훅이 Busy or Retry로 응답함: 같은 순간에 다른 요청이 장바구니를 처리하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화된 경우). Eupago가 알림을 다시 시도합니다. 이유는 로그에 있습니다.

기존 콜백이 Invalid API key로 응답함: Eupago가 보낸 API 키가 Live API Key 또는 Sandbox API Key와 일치하지 않습니다. 웹훅 URL을 브라우저에서 열면 같은 응답이 나타나는데, 이는 정상입니다.

고객에게 The MB WAY payment could not be started가 표시됨: 전화번호가 MB WAY에 연결되어 있는지 확인하고 다시 시도하세요.

결제 후 주문이 Eupago payment on hold 상태임: Eupago payment 블록의 Eupago notes를 읽으세요. 금액 또는 통화가 달랐거나, 참조 번호를 알 수 없었거나, 주문이 취소된 뒤에 결제가 들어온 것입니다. Eupago 백오피스에서 결제를 확인한 다음, 주문을 완료하거나 고객에게 환불하세요.

제거

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

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