VibeFox Mollie for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

쇼핑몰 통화: 장바구니 통화는 Mollie가 지원하는 통화 중 하나여야 합니다: AED, AUD, BGN, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, ISK, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TWD, USD, ZAR. 그 밖의 통화에서는 체크아웃에 결제 옵션이 표시되지 않습니다. Mollie가 제공하는 결제 수단은 통화와 계정에 따라 다릅니다.

쇼핑몰의 인터넷 접근: Mollie는 쇼핑몰로 웹훅을 보내므로, 사이트가 인터넷에서 접근 가능해야 합니다. 웹훅이 없어도 고객이 Mollie에서 돌아오면 주문은 생성됩니다.

Mollie 계정: Mollie Dashboard > Developers > API keys의 API 키가 필요합니다. 테스트 키는 test_, 운영 키는 live_로 시작합니다. 다른 키나 비밀 값은 필요하지 않습니다. 결제 수단 자체는 Mollie 계정에서 활성화합니다.

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

설치

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

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

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

4. 테스트 및 운영 API 키를 입력합니다(설정 참조). Mollie에서는 웹훅을 설정할 필요가 없습니다.

5. Enable/Disable을 켜고 Save를 클릭합니다. 테스트 결제를 완료할 때까지 Test Mode는 켜 둔 상태로 두었다가, 그 뒤에 끕니다.

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

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Mollie Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 필드 위에는 Mollie가 활성화되어 있지만 현재 모드의 API 키가 비어 있거나, Mollie가 쇼핑몰의 기본 통화를 지원하지 않는 경우 경고가 표시됩니다. 두 경우 모두 체크아웃에서 결제 옵션이 숨겨집니다.

저장할 때 test_ 또는 live_로 시작하지 않거나, 그 뒤에 영문자와 숫자가 30자 이상 이어지지 않는 API 키는 저장되지 않습니다. 오류가 표시되고, 이전에 저장된 키는 유지됩니다.

체크아웃

Enable/Disable: Enable Mollie Gateway는 결제 옵션을 켜거나 끕니다. 기본값: off.

Title: 체크아웃에서 고객에게 표시되는 결제 수단의 제목입니다. 주문에 저장되는 결제 수단 이름이기도 합니다. 기본값: Mollie. 필수.

Description: 체크아웃에서 고객에게 표시되는 결제 수단의 설명입니다. 기본값: Pay securely via Mollie.

API 키

API 키는 Mollie Dashboard의 Developers > API keys에서 찾을 수 있으며, 이 섹션에는 해당 페이지로 연결되는 링크가 있습니다. 테스트 키와 운영 키는 별도입니다.

Test Mode: 새 결제에 테스트 API 키를 사용합니다. 실제 결제는 처리되지 않습니다. Mollie의 테스트 체크아웃 페이지에서 결제 결과를 선택할 수 있습니다. 고객에게는 결제 옵션 아래에 Test mode: no real payment will be made.가 표시됩니다. 다른 모드에서 이루어진 결제는 상태 확인과 환불에 여전히 해당 모드의 키를 사용합니다. 기본값: on.

Test API Key: Mollie 테스트 API 키입니다(test_로 시작).

Live API Key: Mollie 운영 API 키입니다(live_로 시작).

저장된 키는 다시 표시되지 않습니다. 필드는 비어 있으며 Saved — leave empty to keep it.가 표시됩니다. 변경하려는 경우에만 새 값을 입력하세요.

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

Webhook: 웹훅 URL을 표시합니다. 별도 설정은 필요하지 않습니다. 모듈이 모든 결제와 함께 이 URL을 Mollie에 보냅니다. 친숙한 URL을 사용하면 다음과 같은 모양이며, 앞에 언어 코드가 붙을 수 있습니다: https://your-shop/module/wcp_mollie_gateway/webhook. 인터넷에서 접근 가능해야 하며, 그렇지 않으면 고객이 Mollie에서 돌아온 경우에만 주문이 생성됩니다.

주문

Order Status After Payment: 결제가 성공한 후 설정되는 주문 상태입니다. 상태는 한 단계에서 설정됩니다.

계좌이체는 Awaiting Mollie payment 상태에서 기다립니다. 승인된 결제와 금액 또는 통화 불일치는 Mollie payment on hold로 넘어갑니다.

고급

Logging: API 호출과 웹훅을 모듈 폴더의 logs/molg_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 이 옵션이 꺼져 있어도 오류와 경고는 항상 기록됩니다. API 키와 고객 데이터는 절대 기록되지 않습니다. 기본값: off.

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

Delete Data on Uninstall: 켜 두면 모듈을 제거할 때 모듈 설정과 로그가 삭제됩니다. 주문에 저장된 Mollie 결제 ID, 환불 기록, 모듈의 주문 상태는 항상 유지됩니다. 기본값: off.

체크아웃

결제 단계에서 고객은 결제 옵션(기본값 Mollie)을 선택하고 확인합니다. 모듈은 장바구니 통화로 장바구니 금액(JPY와 ISK는 소수점 없음)에 대한 Mollie 결제를 만들고, 설명에는 Order #와 장바구니 번호를 넣은 뒤, 고객을 Mollie 호스팅 체크아웃 페이지로 보냅니다. 그곳에서 고객은 Mollie 계정에서 활성화된 결제 수단 중 하나를 선택하여 결제합니다. 이 시점에는 아직 주문이 존재하지 않습니다.

Mollie 웹훅에는 서명이 없고 결제 ID만 들어 있습니다. 따라서 모듈은 웹훅 자체를 신뢰하지 않습니다. 모듈이 직접 만든 결제 ID만 허용하고, 결제가 이루어진 모드의 키로 Mollie API에서 결제 정보를 읽은 다음, 결제가 장바구니에 속하는지 확인하고, 결제된 금액과 통화를 장바구니 합계와 비교합니다. 주문은 Mollie가 이런 방식으로 확인한 후에만 결제 완료로 표시됩니다. 모듈은 다음 Mollie 결제 상태를 처리합니다:

고객이 돌아오면 모듈은 같은 방식으로 Mollie API를 통해 장바구니의 최신 결제를 확인합니다. 결제가 완료되었다면 표준 주문 확인 페이지로 이동하며, 여기에는 Your payment with Mollie has been received.가 표시됩니다. 계좌이체의 경우 페이지에 Your order will be processed as soon as Mollie receives your bank transfer.가 표시됩니다. 주문이 보류 상태이면 We are confirming your payment with Mollie. The order will be updated automatically — please do not pay again.가 표시됩니다. 기존 주문의 결제가 실패했거나 주문이 취소된 경우에는 Your Mollie payment was not completed. Please contact us about this order.가 표시됩니다.

결제가 취소되었거나, 실패했거나, 만료되었거나, 완료되지 않은 경우 고객은 다음과 같은 메시지와 함께 체크아웃으로 돌아갑니다. 예: You cancelled the Mollie payment. You can try again or choose another payment method. 또는 The Mollie payment has expired. Please try again or choose another payment method. 장바구니는 유지됩니다. Mollie에 연결할 수 없거나 아직 결정하지 않은 경우에는 Payment confirmation 페이지가 표시되어 고객에게 다시 결제하지 말 것을 요청하고, Check again 버튼을 제공합니다. 웹훅이 도착하는 즉시 주문이 생성됩니다.

고객이 다시 결제하면, 두 번째 결제 가능한 결제를 만드는 대신 같은 금액의 아직 열려 있는 Mollie 결제를 재사용합니다. 장바구니 합계가 바뀌었다면, Mollie가 허용하는 경우 이전의 열린 결제는 Mollie에서 취소됩니다. 그 사이에 이전 결제가 완료되었다면, 새 결제 없이 주문이 생성됩니다.

Mollie가 결제를 시작할 수 없으면 고객은 짧은 메시지와 함께 체크아웃에 머뭅니다. 예: The payment provider could not be reached. Please try again in a moment., This payment method is temporarily unavailable. Please choose another payment method.(잘못된 API 키) 또는 Mollie cannot accept a payment of this amount or currency. Please choose another payment method. 기술적 원인은 로그에 기록됩니다.

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

고객은 쇼핑몰 체크아웃이 아니라 Mollie 페이지에서 Mollie 결제 수단을 선택합니다. 모듈은 구독이나 정기 결제, 저장된 카드나 위임(mandate), 사이트의 카드 입력란, Apple Pay 또는 PayPal 간편 결제 버튼을 지원하지 않으며, Orders API도 사용하지 않습니다. 따라서 이러한 결제에 대해 Mollie는 주문 항목이 필요한 결제 수단(예: 일부 Klarna, Billie 또는 in3 변형)을 제공하지 않습니다. 승인된 결제는 PrestaShop이 아니라 Mollie Dashboard에서 캡처하거나 취소합니다.

주문 및 환불

주문 상태

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

Payment accepted 또는 Delivered: 결제가 확인되었습니다. 상태는 Order Status After Payment를 따릅니다. 결제는 Mollie 결제 ID(tr_...)를 거래 ID로 하여 기록되며, 메모에는 Mollie 결제, 결제 수단, 모드가 표시됩니다.

Awaiting Mollie payment: 고객이 Mollie 페이지에서 계좌이체를 선택했습니다. Mollie가 입금을 받으면 주문이 결제 완료 상태로 넘어갑니다.

Mollie payment on hold: 승인된 결제가 캡처를 기다리는 경우, Mollie가 차지백을 보고한 경우, 결제된 금액 또는 통화가 장바구니와 달랐던 경우(예: 결제 시작 후 장바구니가 변경됨), 쇼핑몰이 운영 모드인 동안 테스트 결제가 이루어진 경우(입금된 금액 없음), 또는 주문이 취소된 후에 결제가 들어온 경우입니다. 메모에 이유가 설명되어 있습니다. Mollie Dashboard에서 결제를 확인한 다음, 주문을 처리하거나 결제를 환불하세요.

Payment error: 기존 주문의 계좌이체 또는 승인이 실패, 만료되었거나 취소되었습니다. 결제 완료된 주문은 절대 변경되지 않습니다.

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

같은 장바구니의 두 번째 결제가 완료되어도 주문은 변경되지 않습니다. 메모에서 Mollie Dashboard에서 중복 결제를 환불하라고 요청합니다.

Mollie payment 블록

주문 페이지에는 Mollie payment 블록이 표시되며, Mollie 결제 ID, 결제 수단, 결제 상태, 결제 및 환불된 금액, 테스트 결제를 위한 Test mode 배지, 환불 내역, 주문의 Mollie notes가 포함됩니다. 메모는 백오피스에서만 볼 수 있습니다.

환불

Mollie payment 블록에서 금액을 입력하고(아직 환불되지 않은 금액이 자동으로 채워집니다), 필요하면 사유를 입력한 다음 Refund via Mollie를 클릭합니다. Refund this amount through Mollie? This cannot be undone. 질문에 확인하세요. 전액 환불과 부분 환불을 모두 지원합니다. 주문을 편집할 권한이 필요하며, 모듈 페이지에 접근할 권한은 필요하지 않습니다. 환불은 Mollie가 청구한 금액과 통화로 이루어지므로, 금액 불일치가 있는 경우 주문 합계가 아니라 고객이 실제로 결제한 금액까지만 환불할 수 있습니다. 환불은 주문을 실제로 결제한 결제에 대해, 그 결제가 이루어진 모드의 API 키로 전송되므로 해당 모드의 키가 설정되어 있어야 합니다. Mollie가 환불을 거절하면 블록에 Mollie의 오류 메시지가 표시되고 환불은 기록되지 않습니다. 성공한 환불은 환불 내역과 메모에 Mollie 환불 ID와 함께 추가됩니다. 전액 환불은 주문을 Refunded로 설정합니다. 부분 환불은 상태를 변경하지 않습니다. 환불은 Mollie가 결제를 완료된 것으로 보고한 후에만 사용할 수 있습니다.

모듈은 크레딧 슬립(credit slip)을 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 Mollie를 통해 돈을 돌려보내지 않습니다. Mollie Dashboard에서 만든 환불은 주문에 표시되지 않으며, 차지백은 메모를 추가합니다.

라이선스 키

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

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

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

문제 해결

체크아웃에 Mollie가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 API 키가 있는지 확인하세요. 테스트 모드에서는 Test API Key, 운영 모드에서는 Live API Key입니다. 장바구니 통화가 Mollie에서 지원되는지 확인하세요. 설정 페이지는 키가 없는 경우와 지원되지 않는 쇼핑몰 통화에 대해 경고를 표시합니다. Payment > Preferences에서 장바구니 통화, 고객 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인하세요.

결제는 완료되었지만 주문이 생성되지 않음: 웹훅이 쇼핑몰에 도달할 수 없습니다. Webhook에 표시된 URL은 인터넷에서 접근 가능해야 합니다(기본 인증이나 접근을 막는 방화벽이 없어야 함). 고객이 결제 후 쇼핑몰로 돌아오거나 Check again을 클릭해도 주문이 생성됩니다.

웹훅이 Unknown payment.로 응답: 결제가 이 쇼핑몰에서 생성되지 않았거나, Mollie가 해당 모드의 API 키로는 이 결제를 알지 못합니다. 예: 다른 Mollie 계정의 결제.

웹훅이 Payment ID mismatch.로 응답: 결제가 생성된 장바구니에 속하지 않습니다. 아무것도 변경되지 않습니다.

웹훅이 Failed to fetch payment.로 응답: Mollie API에 연결할 수 없거나, 결제 모드의 API 키가 설정되지 않았습니다. Mollie는 나중에 웹훅을 다시 시도합니다.

웹훅이 Temporarily unavailable.로 응답: 같은 순간에 다른 요청이 장바구니를 처리하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). Mollie는 웹훅을 다시 시도합니다. 원인을 확인하려면 Logging을 켜세요.

브라우저에서 웹훅 URL이 Method not allowed.를 표시: 정상입니다. 이 URL은 Mollie의 요청만 허용합니다.

API 키가 저장되지 않음: 키는 test_ 또는 live_로 시작하고, 그 뒤에 영문자와 숫자가 30자 이상 이어져야 합니다. Mollie Dashboard에서 다시 복사하세요.

고객이 Mollie를 선택할 때 오류가 표시됨: 모듈 페이지의 Log 필드를 확인하세요. HTTP 코드와 Mollie 메시지가 표시됩니다. 401은 잘못된 API 키를, 422는 요청의 필드(예: Mollie가 허용하지 않는 금액이나 통화)에 문제가 있음을 나타냅니다.

주문이 Mollie payment on hold 상태임: 주문의 메모를 읽고(주문 상태 참조), 주문을 처리하거나 결제를 환불하세요.

모드 관련 메시지와 함께 환불 실패: 결제는 테스트 또는 운영 모드에서 이루어졌으며, 해당 모드의 API 키가 설정되지 않았습니다. 키를 입력한 후 다시 시도하세요.

다른 통화 또는 결제 데이터: 개발자는 actionWcpMollieSupportedCurrencies 훅으로 통화 목록을, actionWcpMolliePaymentData 훅으로 결제 요청을 변경할 수 있습니다.

제거

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

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