KR
EUR
뒤로

VibeFox GoPay for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

통화: GoPay는 CZK, EUR, PLN, USD, GBP, HUF, RON, BGN을 지원합니다. 장바구니 통화가 이 목록에 없으면 체크아웃에서 해당 결제 방법이 표시되지 않습니다.

GoPay 계정: GoPay 가맹점 계정의 GoID, Client ID, Client Secret이 필요합니다. 계정의 연동 설정에서 확인할 수 있습니다. 샌드박스(테스트) 계정은 별도의 자격 증명을 가집니다. 알림을 위해 GoPay 계정에서 설정할 것은 없지만, 쇼핑몰은 인터넷에서 접근 가능해야 합니다.

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

설치

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

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

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

4. 샌드박스 GoID, Client ID, Client Secret을 입력하고, Test Mode를 켜 둔 상태로 Enable/Disable을 켠 다음 Save를 클릭합니다.

5. 테스트 주문을 진행합니다. 모든 것이 정상적으로 작동하면 운영 환경 자격 증명을 입력하고 Test Mode를 끕니다.

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

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox GoPay Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 입력란 위에는 Sandbox mode — test payments only 또는 Production mode — real payments가 표시됩니다. 현재 모드의 GoID, Client ID, Client Secret이 없거나, GoPay가 쇼핑몰의 기본 통화를 허용하지 않으면 경고가 표시됩니다. 두 경우 모두 체크아웃에서 GoPay가 제공되지 않습니다. 저장하면 캐시된 GoPay 액세스 토큰이 삭제되므로 새 자격 증명이 즉시 사용됩니다.

GoPay

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

Title: 체크아웃에 표시되는 결제 방법 제목입니다. 주문에 저장되는 결제 방법 이름이기도 합니다. 기본값: GoPay. 필수: 빈 제목은 저장되지 않습니다.

Description: 체크아웃에 표시되는 결제 방법 설명입니다. 기본값: Pay securely via GoPay - cards, wallets, bank transfers.

API 자격 증명

GoID, Client ID, Client Secret은 GoPay 가맹점 계정(연동 설정)에 표시됩니다. 샌드박스(테스트) 계정은 별도의 자격 증명을 가집니다. API 문서는 doc.gopay.com에 있습니다.

Test Mode: 샌드박스 자격 증명으로 결제를 gw.sandbox.gopay.com에 보냅니다. 실제 금액은 청구되지 않습니다. 운영 환경 자격 증명으로 실제 결제를 받으려면 끄십시오. 기본값: 켜짐.

Sandbox GoID: GoPay 샌드박스(테스트) 계정의 GoID입니다.

Sandbox Client ID: 샌드박스 계정의 OAuth Client ID입니다.

Sandbox Client Secret: 샌드박스 계정의 OAuth Client Secret입니다.

Production GoID: GoPay 가맹점 ID(GoID)입니다.

Production Client ID: GoPay에서 발급받은 OAuth Client ID입니다.

Production Client Secret: GoPay에서 발급받은 OAuth Client Secret입니다.

GoID는 숫자로만 구성됩니다(예: 8123456789). 다른 값을 입력하면 페이지에 오류가 표시되고 이전 값이 유지됩니다.

저장된 Client Secret은 다시 표시되지 않습니다. 입력란은 비워 두며 Saved — leave empty to keep it.가 표시됩니다. 변경하려는 경우에만 새 값을 입력하십시오.

Clear saved client secrets: 체크한 뒤 Save를 클릭하면 저장된 Client Secret 두 개가 모두 삭제됩니다. 입력란이 비어 있으면 저장된 값이 유지됩니다.

결제

Payment Page Language: GoPay 결제 페이지의 언어입니다. 기본값: Automatic (site language, then billing country). 자동 설정은 고객 장바구니의 언어를 사용합니다. GoPay에 해당 언어가 없으면 청구 국가로 결정하고, 그 밖의 경우에는 영어를 사용합니다. 19개 언어 중 하나를 고정할 수도 있습니다: Czech, English, Slovak, German, Polish, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, French, Italian, Spanish, Portuguese, Ukrainian 또는 Russian.

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

Payment accepted (WooCommerce "Processing"): 결제된 주문에 대한 PrestaShop 표준 상태입니다(기본값).
Delivered (WooCommerce "Completed"): 결제된 모든 주문이 Delivered가 됩니다.

주문과 일치하지 않는 결제, 취소 후 결제, 사전 승인된 결제는 항상 GoPay payment on hold로 전환됩니다.

결제 알림

알림은 결제가 이루어졌음을 쇼핑몰에 알립니다. Notification URL은 이 섹션에 표시되며 모든 결제와 함께 GoPay로 전송되므로 GoPay 계정에서 설정할 것은 없습니다. 친숙한 URL을 사용하면 다음과 같은 형태입니다: https://your-shop/module/wcp_gopay_gateway/webhook, 경우에 따라 /en/ 같은 언어 코드가 포함될 수 있습니다. 인터넷에서 접근 가능해야 하며, 앞단에 비밀번호 보호나 방화벽이 없어야 합니다. 쇼핑몰이 유지 보수 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다.

GoPay 알림에는 결제 ID만 포함되며 서명은 없습니다. 모든 알림은 결제가 이루어진 모드의 자격 증명으로 GoPay API에 결제 상태를 요청하여 검증되며, 결제는 쇼핑몰의 장바구니에 대해 모듈이 생성한 것이어야 합니다. GoPay에서 상태를 읽을 수 없으면 쇼핑몰은 오류로 응답하고 GoPay는 알림을 다시 보냅니다. 알림이 없으면 주문은 고객이 결제 후 쇼핑몰로 돌아왔을 때에만 생성됩니다.

고급

Logging: GoPay 이벤트를 모듈 폴더의 logs/gopay_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류와 경고는 항상 기록됩니다. 자격 증명, 토큰, 카드 데이터, 고객의 이메일과 이름은 절대 기록되지 않습니다. 기본값: 꺼짐.

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

Delete Data on Uninstall: 켜져 있으면 모듈을 제거할 때 모듈 설정, 캐시된 GoPay 액세스 토큰, 로그가 삭제됩니다. 주문, 주문의 GoPay 결제 데이터, GoPay payment on hold 주문 상태는 항상 유지됩니다. 기본값: 꺼짐.

체크아웃

결제 단계에서 고객은 결제 방법(기본값 GoPay)을 선택하고 확인합니다. 모듈은 장바구니 통화로 장바구니 총액(상품, 배송비, 선물 포장 포함)에 대한 GoPay 결제를 생성하고, 고객을 GoPay 결제 페이지로 보냅니다. 그곳에서 GoPay는 GoPay 계정에서 활성화된 결제 방법(결제 카드, 은행 송금, 디지털 지갑 등)을 제공합니다. 고객의 청구 이름, 이메일, 전화번호, 주소는 GoPay로 전달되며, 비어 있는 항목은 전송되지 않습니다. GoPay에서 결제는 Order PS-와 장바구니 번호로 표시됩니다. 이 시점에는 아직 주문이 존재하지 않습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 GoPay가 결제를 확인한 후에만 결제 완료로 표시됩니다. 알림을 통해서 또는 고객이 돌아올 때 GoPay API에 요청하는 방식으로 확인됩니다. 알림과 복귀가 같은 시점에 도착하면 순서대로 처리되므로 주문은 하나만 생성됩니다. 이후 고객에게는 표준 주문 확인 페이지가 표시됩니다. 주문이 GoPay payment on hold로 전환되었다면, 페이지에 Your payment is being reviewed. We will contact you if anything else is needed. 메시지가 추가됩니다.

고객이 돌아올 때 GoPay가 아직 결제를 확인하지 않은 경우(예: 은행 송금이 진행 중이거나 GoPay에 접속할 수 없는 경우), Payment confirmation 페이지에 GoPay has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. 메시지와 Check again 버튼이 표시됩니다.

결제가 완료되지 않았거나, 취소되었거나, 만료된 경우 고객은 체크아웃으로 돌아가 The GoPay payment was not completed. You can try again or choose another payment method. 또는 The GoPay payment was cancelled or has expired. You can try again or choose another payment method. 메시지를 보게 됩니다. 장바구니는 유지되며, 새로 시도하면 새 GoPay 결제가 생성됩니다. 이미 주문이 있는 장바구니에는 다시 청구되지 않습니다.

GoPay가 결제를 시작할 수 없는 경우 고객은 체크아웃에 머무르며 짧은 메시지를 보게 됩니다. 예: GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. 또는 GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. 기술적인 원인은 로그에 기록됩니다.

고객은 GoPay 페이지에서 결제 방법을 선택합니다. PrestaShop에서는 선택할 수 없습니다. 이 모듈은 구독이나 정기 결제, 저장된 카드, 임베디드 결제 양식, PrestaShop에서의 사전 승인 캡처 또는 취소를 지원하지 않습니다.

주문 및 환불

주문 상태

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

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

GoPay payment on hold: GoPay가 결제를 확인했지만 금액, 통화 또는 주문 번호가 장바구니와 다릅니다(예: 결제 시작 후 장바구니가 변경됨). 또는 주문이 취소된 후에 결제가 도착했습니다. 또는 결제가 사전 승인만 되었고 아직 금액이 캡처되지 않았습니다. 메모에 이유가 설명됩니다. 사전 승인된 결제는 GoPay에서 캡처해야 하며, 이후 GoPay가 결제 완료를 보고하면 주문이 결제 완료 상태로 이동합니다.

Refunded: 주문의 GoPay 결제가 모듈을 통해서든 GoPay 계정에서든 전액 환불되었습니다.

이미 결제된 주문에 대한 다른 결제 시도도 결제되면 주문은 변경되지 않습니다. 메모에서 GoPay 계정으로 중복 결제를 환불하라고 요청합니다. GoPay 없이(예: 수동으로) 이미 결제 완료로 표시된 주문에 대해 GoPay 결제가 이루어지면 비슷한 메모가 추가됩니다. 취소되었거나 환불된 주문은 이후 알림으로 다시 열리지 않습니다.

GoPay 결제 블록

주문 페이지에는 GoPay payment 블록이 표시되며, GoPay 결제 ID, GoPay 상태 및 결제 수단, 결제 금액, 결제 및 환불된 금액, 샌드박스 결제에 대한 Sandbox 배지, 수동 검토 사유, 환불 내역, 주문의 GoPay notes가 포함됩니다.

환불

GoPay payment 블록에서 금액을 입력합니다(아직 환불되지 않은 금액이 자동으로 채워집니다). 필요하면 사유를 입력하고 Refund via GoPay를 클릭합니다. Refund this amount through GoPay? This cannot be undone. 확인 질문에 확인합니다. 전액 및 부분 환불을 지원합니다. 주문을 편집할 권한이 필요하며, Modules 페이지에 대한 접근 권한은 필요하지 않습니다. GoPay는 결제 후 24시간 이내에만 부분 환불을 받습니다. 환불은 GoPay가 청구한 금액과 통화로 이루어지므로, 금액 또는 통화가 일치하지 않은 경우에는 고객이 실제로 결제한 금액까지만 환불할 수 있습니다. 환불은 결제가 이루어진 모드(샌드박스 또는 운영 환경)로 전송되므로, 해당 모드의 자격 증명이 설정되어 있어야 합니다. GoPay가 환불을 거부하면 블록에 GoPay의 메시지가 표시되며 환불은 기록되지 않습니다. 성공한 환불은 환불 내역과 메모에 추가됩니다. GoPay가 나중에 처리하도록 수락한 환불은 수락됨으로 표시됩니다. 전액 환불은 주문을 Refunded로 설정합니다. 부분 환불은 상태를 변경하지 않습니다.

모듈은 크레딧 슬립(credit slip)을 생성하지 않습니다. 주문 페이지의 PrestaShop 표준 환불 버튼은 GoPay를 통해 금액을 돌려주지 않습니다.

GoPay 계정에서 이루어진 환불은 알림을 통해 전달됩니다. 전액 환불은 주문을 Refunded로 변경하며, 부분 환불은 메모를 추가합니다. 이들은 블록의 환불 내역에 추가되지 않습니다.

라이선스 키

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

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

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

문제 해결

GoPay가 체크아웃에 표시되지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 GoID, Client ID, Client Secret이 설정되어 있는지, 장바구니 통화가 CZK, EUR, PLN, USD, GBP, HUF, RON, BGN 중 하나인지 확인하십시오. 자격 증명이 없으면 설정 페이지에 경고가 표시됩니다. Payment > Preferences에서 모듈이 장바구니 통화, 고객의 국가, 고객 그룹에 대해 허용되어 있는지 확인하십시오.

결제는 완료되었지만 주문이 생성되지 않음: GoPay가 설정에 표시된 Notification URL에 접속할 수 없었고, 고객도 쇼핑몰로 돌아오지 않았습니다. URL을 차단하는 비밀번호 보호나 방화벽 규칙을 제거하십시오. 결제가 이루어진 모드의 자격 증명이 설정되어 있는지 확인하십시오. 모든 알림이 그 자격 증명으로 검증되기 때문입니다. Logging을 켜고 Log 필드를 확인하십시오. GoPay는 성공 응답을 받지 못한 알림을 다시 보냅니다.

Notification answers Order not found: 이 결제는 이 쇼핑몰에서 생성되지 않았거나, 해당 장바구니가 삭제되었습니다.

Notification answers Payment state could not be verified: GoPay API에 접속할 수 없거나, 해당 모드의 자격 증명이 없거나 잘못되었습니다. GoPay는 알림을 다시 보냅니다.

Notification answers Busy, retry later: 같은 시점에 다른 요청이 장바구니를 처리하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). GoPay는 알림을 다시 보냅니다. 원인을 확인하려면 Logging을 켜십시오.

고객이 GoPay를 선택할 때 오류가 표시됨: Logging을 켜고 Log 필드를 확인하십시오. 잘못된 자격 증명이나 다른 모드의 자격 증명이 일반적인 원인입니다. 청구 정보에 관한 메시지는 GoPay가 이메일, 전화번호 또는 주소를 수락하지 않았다는 뜻입니다.

테스트 결제가 실제 주문을 확인하지 않음: 샌드박스와 운영 환경은 분리되어 있습니다. 각 결제는 생성된 모드에서 확인됩니다. 원하는 모드로 Test Mode를 전환하고 그 모드의 자격 증명을 사용하십시오.

결제 후 주문이 GoPay payment on hold 상태임: GoPay payment 블록의 메모를 읽으십시오. 결제된 금액 또는 통화가 장바구니와 달랐거나, 주문이 취소된 후 결제가 도착했거나, 결제가 사전 승인만 된 경우입니다.

환불 실패: 블록에 표시된 GoPay 메시지를 읽으십시오. 부분 환불은 결제 후 24시간 이내에만 가능합니다. 모드에 관한 메시지는 결제가 샌드박스 또는 운영 환경 모드에서 이루어졌고 해당 모드의 자격 증명이 설정되지 않았다는 뜻입니다.

개발자용: actionGopayPaymentPayload 후크는 결제 요청이 GoPay로 전송되기 전에 이를 변경합니다.

제거

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

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