VibeFox PayPlug for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

통화 및 금액: 유로(EUR), 결제당 0.99 ~ 20,000.00. PayPlug의 기본값입니다. 장바구니 통화가 다르거나 이 범위를 벗어나면 결제 수단이 표시되지 않습니다.

PayPlug 계정: PayPlug 계정의 비밀 키가 필요합니다. 테스트 키(sk_test_...) 및/또는 운영 키(sk_live_...)입니다. 다른 키는 필요하지 않으며, PayPlug에서 알림을 설정할 필요도 없습니다. 알림을 받으려면 쇼핑몰이 인터넷에서 접근 가능해야 합니다. 그렇지 않으면 고객이 PayPlug에서 돌아올 때 주문이 생성됩니다.

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

설치

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

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

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

4. PayPlug 포털에서 비밀 키를 붙여 넣습니다(설정 참조).

5. Enable/Disable을 켜고 Save를 클릭합니다. Test Mode를 켠 상태에서 결제를 테스트한 뒤, 실제 결제를 받으려면 끕니다.

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

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox PayPlug Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 필드 위에서 페이지는 결제 수단이 활성화되어 있지만 현재 모드의 비밀 키가 비어 있을 때, 그리고 쇼핑몰의 기본 통화가 EUR이 아닐 때 경고합니다. 두 경우 모두 체크아웃에서 결제 수단이 숨겨집니다.

체크아웃

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

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

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely by card via PayPlug.

API 키

비밀 키는 PayPlug 포털의 Developers > API keys에서 찾을 수 있습니다. 이 섹션에는 포털 링크가 있습니다.

Test Mode: 새 결제에 테스트 비밀 키를 사용합니다. 실제 결제는 처리되지 않습니다. 다른 모드에서 이루어진 결제는 상태 확인과 환불에 여전히 해당 모드의 키를 사용합니다. 기본값: on. 켜져 있는 동안 고객에게는 결제 수단 아래에 Test mode: no real payment will be made.가 표시됩니다.

Test Secret Key: PayPlug 테스트 비밀 키입니다. sk_test_로 시작합니다.

Live Secret Key: PayPlug 운영 비밀 키입니다. sk_live_로 시작합니다.

잘못된 접두사가 붙은 키는 저장되지 않습니다. 페이지에는 예를 들어 Test Secret Key must start with "sk_test_". The previous value was kept.가 표시됩니다. 저장된 키는 다시 표시되지 않습니다. 필드는 비어 있고 Saved — leave empty to keep it.가 표시됩니다. 변경하려는 경우에만 새 값을 입력하세요.

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

Notification URL: 모듈이 모든 결제와 함께 PayPlug에 보내는 주소입니다. 친근한 URL을 사용하면 https://your-shop/module/wcp_payplug_gateway/webhook처럼 보입니다. PayPlug 포털에는 아무것도 입력할 필요가 없습니다. 이 URL은 인터넷에서 접근 가능해야 합니다. 그렇지 않으면 고객이 PayPlug에서 돌아올 때 주문이 생성됩니다.

주문

Order Status After Payment: 결제 성공 후 설정되는 주문 상태입니다. 상태는 즉시 설정되며 두 번째 상태 변경은 없습니다.

고급

Logging: API 호출과 알림을 모듈 폴더의 logs/ppg_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류와 경고는 항상 기록됩니다. 비밀 키, 카드 정보, 고객 데이터는 절대 기록되지 않습니다. 기본값: off.

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

Delete Data on Uninstall: 켜면 모듈을 제거할 때 모듈 설정과 로그가 삭제됩니다. 주문과 함께 저장된 PayPlug 결제 ID와 PayPlug payment on hold 주문 상태는 유지됩니다. 기본값: off.

체크아웃

결제 단계에서 고객은 결제 수단(기본값은 PayPlug 로고가 있는 PayPlug)을 선택합니다. 테스트 모드에서는 이 옵션에 Test mode: no real payment will be made.가 표시됩니다. 확인하면 모듈은 장바구니 합계를 센트 단위로 하여 PayPlug 결제를 생성하고, 고객을 PayPlug 결제 페이지로 보냅니다. 청구지 주소와 배송지 주소, 이메일, 장바구니의 언어가 PayPlug에 전달됩니다. 고객은 그곳에서 카드로 결제합니다. 이 시점에는 아직 주문이 없습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 PayPlug가 확인한 후에만 결제 완료로 표시됩니다. 모듈은 알림이 도착할 때와 고객이 돌아올 때 PayPlug API에서 결제 정보를 읽습니다. 그런 다음 주문이 생성되고, 고객은 Your payment with PayPlug has been received.가 표시된 표준 주문 확인 페이지를 봅니다. 주문이 보류 상태이면 페이지에 We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again.가 표시됩니다. 주문이 Payment error 상태이거나 결제 없이 취소되었다면 페이지에 Your PayPlug payment was not completed. Please contact us about this order.가 표시됩니다. 고객이 돌아왔을 때 PayPlug에 조회할 수 없었다면 Payment confirmation 페이지에 같은 "we are confirming" 문구와 Check again 버튼이 표시되며, 알림이 도착하는 즉시 주문이 생성됩니다.

고객이 PayPlug 페이지에서 취소하면 결제 페이지가 PayPlug에서 닫히므로 나중에 실수로 결제할 수 없습니다. 고객은 체크아웃으로 돌아가 다음 메시지 중 하나를 보게 됩니다: You cancelled the PayPlug payment. You can try again or choose another payment method., The PayPlug payment session has expired. Please try again or choose another payment method., The PayPlug payment failed. Please try again or choose another payment method. 또는 결제가 열린 상태로 남아 있었다면 Your PayPlug payment was not completed. You can try again or choose another payment method. 장바구니는 유지됩니다.

고객이 같은 장바구니를 다시 결제하면 모듈은 먼저 이전 시도를 확인합니다. 그사이 결제되었다면 새 결제 없이 주문이 생성됩니다. 같은 금액으로 아직 열려 있다면 같은 결제 페이지를 다시 사용합니다. 그렇지 않으면 이전 페이지가 PayPlug에서 닫히고 새 결제가 생성됩니다.

PayPlug가 결제를 시작할 수 없으면 고객은 체크아웃에 머무르며, 예를 들어 PayPlug could not accept your billing details (postcode). Please check them and try again. 또는 The payment provider could not be reached. Please try again in a moment.와 같은 짧은 메시지를 봅니다. 기술적인 원인은 로그에 기록됩니다.

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

결제는 즉시 매출로 확정됩니다. 이 모듈에는 Oney 할부, 원클릭 저장 카드, 임베디드 결제 양식, 구독, 지연 캡처가 없습니다.

주문 및 환불

주문 상태

No order yet: 고객이 PayPlug로 이동했지만 결제하지 않았거나, PayPlug가 아직 결제를 확인하지 않았습니다. 장바구니만 존재합니다.

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

PayPlug payment on hold: 결제된 금액 또는 통화가 장바구니와 다름(메모 amount/currency mismatch, 예: 결제 시작 후 장바구니가 변경됨); 쇼핑몰이 운영 모드인 동안 테스트 결제가 이루어져 돈이 입금되지 않았고 결제가 기록되지 않음; 취소된 주문에 대한 결제가 도착함; 또는 결제가 승인되었지만 캡처되지 않음(PayPlug 포털에서 캡처하세요. PayPlug가 결제 완료로 보고하면 주문이 결제 완료로 표시됩니다). 메모에 확인해야 할 내용이 설명되어 있습니다.

Payment error: 보류 주문의 승인된 결제가 실패했거나 취소되었습니다.

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

이미 결제된 장바구니에 대한 두 번째 시도도 결제되었다면 주문은 변경되지 않습니다. 메모에서 PayPlug 포털을 통해 중복 결제를 환불하라는 안내가 표시됩니다. 결제 완료, 취소 또는 환불된 주문은 이후 알림으로 다시 열리지 않습니다.

PayPlug 결제 블록

주문 페이지에는 PayPlug payment 블록이 표시되며, PayPlug 결제 ID, 결제 상태, 결제 금액과 환불 금액, 테스트 결제를 위한 Test mode 배지, 환불 내역, 주문의 PayPlug notes가 포함됩니다.

환불

PayPlug payment 블록에서 금액을 입력하고(아직 환불되지 않은 금액이 자동으로 채워짐), 필요하면 사유를 입력한 뒤 Refund via PayPlug를 클릭합니다. Refund this amount through PayPlug? This cannot be undone. 질문을 확인하세요. 전액 환불과 부분 환불을 지원합니다. 주문을 편집할 수 있는 권한이 필요하며, 모듈 페이지에 접근할 권한은 필요하지 않습니다. 환불은 PayPlug가 실제로 청구한 금액 한도 내에서 이루어집니다. 따라서 금액 불일치가 있는 경우 주문 합계가 아니라 고객이 실제로 지불한 금액을 환불할 수 있습니다. 환불은 주문을 실제로 결제한 결제 건에 대해, 환불이 이루어진 모드(테스트 또는 운영)의 비밀 키로 진행되므로 해당 모드의 키가 설정되어 있어야 합니다. PayPlug가 환불을 거부하면 블록에 오류가 표시되며 환불은 기록되지 않습니다. 성공한 환불은 PayPlug 환불 ID와 사유와 함께 환불 내역과 메모에 추가됩니다. 전액 환불은 주문을 Refunded 상태로 바꿉니다. 부분 환불은 상태를 바꾸지 않습니다. 환불은 PayPlug가 결제를 완료로 보고한 후에만 가능합니다.

모듈은 크레딧 전표를 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 PayPlug를 통해 돈을 돌려주지 않습니다.

PayPlug 포털에서 진행한 환불은 알림을 통해 도착하며, 메모에 한 번만 추가됩니다. 이 환불은 블록에 집계되지 않고 주문 상태나 크레딧 전표도 바꾸지 않습니다. 필요하면 직접 기록하세요.

라이선스 키

모듈은 vibefox.net에서 발급받은 VibeFox 라이선스 키와 함께 작동합니다. 라이선스 블록 License — VibeFox PayPlug Gateway는 Modules > Module Manager > VibeFox PayPlug Gateway > Configure의 첫 번째 블록이며, 설정 위에 있습니다. 키를 License key에 붙여 넣고 Activate를 클릭합니다. 그러면 블록에 마스킹된 키, 상태(예: 라이선스가 유효한 날짜와 도메인), 그리고 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key 버튼이 표시됩니다. 그 아래에는 Product: presta-payment-payplug 줄과 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 계정에서 슬롯을 해제하세요.

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

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

문제 해결

체크아웃에 PayPlug가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 비밀 키가 있는지(테스트 모드는 Test Secret Key, 운영 모드는 Live Secret Key), 장바구니 통화가 EUR인지, 장바구니 합계가 0.99 ~ 20,000.00 EUR 사이인지 확인하세요. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객의 그룹에 대해 모듈이 허용되어 있는지 확인하세요. 개발자는 actionWcpPayplugSupportedCurrencies 및 actionWcpPayplugAmountLimits 훅으로 통화와 한도를 변경할 수 있습니다(센트 단위 값).

결제는 완료되었지만 주문이 생성되지 않음: 알림이 쇼핑몰에 도달하지 않았고 고객도 돌아오지 않았습니다. 설정에 표시된 Notification URL로 쇼핑몰이 인터넷에서 접근 가능한지 확인하세요. 예를 들어 방화벽이나 비밀번호 보호가 이를 막고 있지 않은지 확인합니다. Logging을 켜고 Log 필드에서 거부된 알림을 확인하세요.

알림 응답이 Verification failed.: PayPlug API에서 결제를 읽을 수 없었습니다. 예를 들어 PayPlug가 응답하지 않았거나 결제 모드의 비밀 키가 설정되지 않은 경우입니다. 주문은 변경되지 않으며, PayPlug가 알림을 다시 보냅니다.

알림 응답이 Temporarily unavailable.: 고객의 복귀 등 다른 요청이 같은 순간 장바구니를 업데이트하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). PayPlug가 알림을 다시 보냅니다. 로그에 이유가 표시됩니다.

알림 응답이 Unknown payment. 또는 Payment does not belong to the order.: 결제가 이 쇼핑몰에서 만들어지지 않았거나 이 장바구니를 위한 것이 아닙니다. 예를 들어 같은 PayPlug 계정의 다른 쇼핑몰 결제입니다. 무시됩니다.

브라우저에서 알림 URL이 Method not allowed.를 표시: 정상입니다. 이 URL은 PayPlug의 요청만 받습니다.

고객이 PayPlug를 선택할 때 오류 발생: Logging을 켜고 Log 필드를 확인하세요. 잘못된 키는 This payment method is temporarily unavailable. Please choose another payment method.를 표시하며, 다른 메시지들은 PayPlug가 거부한 청구 필드를 알려 줍니다.

결제 후 주문이 PayPlug payment on hold 상태: PayPlug payment 블록의 메모를 읽은 뒤(주문 상태 참조) 주문을 처리하거나 결제를 환불하세요.

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

Unexpected response from PayPlug.와 함께 환불 실패: PayPlug가 유효한 환불 없이 응답했습니다. 아무것도 기록되지 않았습니다. 다시 시도하기 전에 PayPlug 포털에서 환불을 확인하세요.

제거

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

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