VibeFox Windcave for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

Windcave 계정: REST API 자격 증명(API 사용자 이름과 API 키)이 포함된 Windcave 가맹점 계정이 필요합니다. Windcave는 UAT 테스트 환경(uat.windcave.com)과 운영 환경(sec.windcave.com)용 자격 증명을 각각 따로 발급합니다. Windcave 고객 지원팀이나 담당 계정 매니저에게 문의하십시오. PxPay 키는 이 모듈에서 사용할 수 없습니다. 제공하려는 결제 수단(카드, 간편결제 및 기타)은 Windcave 계정에서 활성화되어 있어야 합니다.

알림: Windcave가 결제 알림을 보낼 수 있도록 쇼핑몰은 인터넷에서 접근 가능해야 합니다. Windcave 측에서 별도로 설정할 것은 없습니다.

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서만 사용할 수 있습니다.

설치

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

2. 업로드가 끝나면 Configure를 클릭합니다. 나중에 설정하려면 모듈 목록에서 VibeFox Windcave Payment Gateway를 찾아 Configure를 클릭합니다.

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

4. REST API 사용자 이름과 키를 입력합니다. 테스트 모드에는 UAT 자격 증명을, 실제 결제에는 운영 환경 자격 증명을 입력합니다(설정 참조).

5. 거래 유형과 결제 수단을 선택하고 Enable/Disable을 켠 뒤 Save를 클릭합니다. Test mode를 켠 상태에서 테스트 결제를 진행한 다음, 실제 결제를 받으려면 Test mode를 끕니다.

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

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 개별 Save 버튼이 있습니다. 테스트 모드가 켜져 있는 동안 페이지에는 테스트 모드가 켜져 있습니다. 결제는 Windcave UAT 환경으로 전송되며 실제 금액은 청구되지 않습니다.가 표시됩니다. 모듈은 활성화되어 있지만 현재 모드에 API 사용자 이름이나 키가 없으면, 페이지는 결제 수단이 체크아웃에서 숨겨진다는 경고를 표시합니다(예: Windcave가 활성화되어 있지만 UAT API 사용자 이름 / 키가 비어 있어 결제 수단이 체크아웃에서 숨겨집니다.). Title은 비워 둘 수 없습니다. 비어 있으면 페이지에 결제 수단의 제목을 입력하십시오.가 표시되며 아무것도 저장되지 않습니다.

Windcave

Enable/Disable: Enable Windcave payments는 결제 수단을 켜거나 끕니다. 기본값: 끔.

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

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: You will be redirected to the secure Windcave payment page to complete your payment.

Windcave REST API

Windcave에서 발급한 REST API 자격 증명(사용자 이름과 API 키, PxPay 키가 아님)을 입력합니다. 운영 환경과 UAT 자격 증명은 나란히 저장할 수 있습니다. 테스트 모드는 UAT 자격 증명만, 실제 모드는 운영 환경 자격 증명만 사용합니다. 이 섹션에는 Windcave REST API 문서 링크가 있습니다.

Test mode: Windcave UAT 테스트 환경(uat.windcave.com)을 사용합니다. 실제 금액은 청구되지 않습니다. 새 결제는 UAT 자격 증명을 사용합니다. 환불과 캡처는 항상 주문이 결제된 환경으로 처리됩니다. 기본값: 끔.

Production API username: sec.windcave.com용 REST API 사용자 이름입니다.

Production API key: sec.windcave.com용 REST API 키입니다.

UAT API username: uat.windcave.com용 REST API 사용자 이름입니다(테스트 모드).

UAT API key: uat.windcave.com용 REST API 키입니다(테스트 모드).

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

Clear saved keys: Production API key 또는 UAT API key를 체크한 뒤 Save를 클릭하면 삭제됩니다. 필드가 비어 있으면 저장된 값이 유지됩니다.

Notification URL: Windcave가 결제 알림(Fail-Proof Result Notification)을 보내는 주소를 표시합니다. 친숙한 URL을 사용하는 경우 https://your-shop/module/wcp_windcave_payment_gateway/notification 형태입니다. Windcave에서 설정할 것은 없습니다. 모듈은 결제 세션마다 반환 주소와 이 알림 주소를 전송합니다. 이 주소는 인터넷에서 접근 가능해야 하며, 그렇지 않으면 주문은 고객이 Windcave에서 돌아왔을 때에만 확인됩니다. 고객의 복귀와 알림 모두 Windcave가 서명하지 않으므로, 모듈은 이것만으로는 절대 신뢰하지 않습니다. 모듈은 항상 세션이 생성된 환경의 자격 증명으로 Windcave REST API에서 세션 결과를 읽습니다.

Payment

Transaction type: 결제를 처리하는 방식입니다. 기본값: Purchase.

Purchase (capture immediately): 고객이 결제할 때 금액이 청구됩니다.

Auth (authorise now, capture later): 금액은 예약만 됩니다. 주문은 Windcave payment on hold 상태가 되며, 주문의 Windcave 블록에 있는 Capture Windcave payment로 금액을 청구하거나, 전액을 환불하여 예약을 해제할 수 있습니다. 캡처되지 않은 승인은 며칠 후 만료됩니다.

Payment methods: Windcave 결제 페이지에 표시되는 수단입니다: Cards, Account2Account(뉴질랜드 계좌이체), Apple Pay, Google Pay, PayPal, Alipay, WeChat Pay, UnionPay, Interac, humm. 여러 개를 선택하려면 Ctrl 또는 Cmd를 누른 채 클릭합니다. 이 수단들은 Windcave 계정에서 활성화되어 있어야 합니다. 필드를 비워 두면 계정에서 활성화된 모든 수단이 표시됩니다. 기본값: Cards.

Advanced

Debug log: API 요청과 결제 이벤트를 모듈 폴더의 logs/windcave_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 이 옵션이 꺼져 있는 동안에는 오류와 경고만 기록됩니다. API 키, 카드 정보, 고객의 개인정보는 절대 기록되지 않습니다. 기본값: 끔.

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

Clean uninstall: 모듈을 제거할 때 모듈 설정과 로그를 삭제합니다. 주문과 함께 저장된 결제 데이터(환불에 필요한 Windcave 거래 ID)는 항상 유지됩니다. 기본값: 끔.

모듈 버전은 페이지 하단에 표시됩니다.

체크아웃

결제 단계에서 고객은 설명과 함께 결제 수단(기본값 Credit/Debit Card (Windcave))을 선택합니다. 테스트 모드에서는 고객에게 Test mode: 결제는 Windcave UAT 환경으로 전송되며 실제 금액은 청구되지 않습니다.도 표시됩니다. 확인을 누르면 모듈은 장바구니 합계 금액에 대해 장바구니 통화로 Windcave 결제 세션을 생성하고, 고객을 Windcave Hosted Payment Page로 보냅니다. 장바구니 번호가 가맹점 참조 번호로 전송되며, 쇼핑몰 언어와 고객의 이름, 이메일, 전화번호, 청구지 주소도 함께 전송됩니다(장바구니에 배송이 필요하면 배송지 주소도 전송됩니다). 이 시점에는 아직 주문이 존재하지 않습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 Windcave가 확인한 후에만 결제 완료로 표시됩니다. 모듈은 고객이 돌아왔을 때와 Windcave 알림이 도착했을 때 모두 REST API에 세션 결과를 요청합니다. 장바구니별 잠금 기능으로 결제는 한 번만 적용됩니다. 그 후 주문이 생성되고, 고객은 Your Windcave payment has been received.가 표시된 표준 주문 확인 페이지를 봅니다. 보류 중인 주문(승인 또는 장바구니와 일치하지 않는 결제)의 경우, 페이지에는 Your payment was received by Windcave. The shop will check it before processing your order — please do not pay again.가 표시됩니다.

승인된 결제 후 고객이 돌아왔지만 결과를 아직 알 수 없는 경우, Payment confirmation 페이지에 We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again.와 Check again 버튼이 표시됩니다. 알림은 Windcave가 결제를 확인하는 즉시 주문을 생성합니다.

고객이 결제를 완료하지 않고 돌아오면, 체크아웃 페이지에 다음 메시지 중 하나가 표시됩니다. 장바구니는 유지됩니다.

Declined: 결제가 거부되었습니다. 다시 시도하시거나 다른 결제 수단을 선택해 주십시오.

Cancelled or expired: Windcave 페이지에서 결제가 완료되지 않았습니다. 장바구니가 저장되어 있으므로 다시 시도하시거나 다른 결제 수단을 선택하실 수 있습니다.

Not confirmed yet: 아직 결제를 확인하지 못했습니다. 결제를 완료하셨다면 다시 결제하지 마십시오. Windcave가 확인하는 즉시 확인 이메일을 받으실 것입니다.

Return could not be processed: 결제 페이지에서 돌아오는 과정을 처리하지 못했습니다. 금액이 청구되었다면, 다시 결제하기 전에 문의해 주십시오.

고객은 같은 장바구니로 다시 시도할 수 있습니다. 새 시도는 먼저 이전 세션을 확인합니다. 이미 결제되었다면 주문이 생성되고 두 번째 결제는 시작되지 않습니다. 고객이 결제 페이지를 한 번도 사용하지 않았고 장바구니가 변경되지 않았다면, 같은 페이지로 돌아갑니다. 그 순간 이전 결제가 확인 중이라면, 고객에게는 Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.가 표시됩니다.

Windcave가 결제를 시작할 수 없으면, 고객은 체크아웃 페이지에 머물면서 짧은 메시지를 봅니다. 이 주문의 정보로 Windcave가 결제를 시작할 수 없었다는 내용이거나, 결제 서비스를 일시적으로 사용할 수 없다는 내용입니다. 이유는 로그에 기록됩니다. 현재 모드에 자격 증명이 없으면, 고객에게는 This payment method is not available at the moment. Please choose another payment method or contact us.가 표시됩니다.

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

이 모듈은 구독이나 정기 결제, 저장된 카드, 사이트에 내장된 카드 양식(고객은 항상 Windcave 페이지에서 결제합니다), PxPay 2.0 API 지원을 제공하지 않으며, 추가 요금도 부과하지 않습니다. Windcave가 추가 요금을 부과하면, 주문은 주 거래와 대조됩니다.

주문과 환불

Order statuses

No order yet: 고객은 Windcave로 이동했지만 아직 결제하지 않았거나, Windcave가 아직 결제를 확인하지 않았거나, 결제가 거부, 취소 또는 만료되었습니다. 장바구니만 존재합니다.

Payment accepted: Purchase 결제가 확인되었고 장바구니와 일치합니다. 결제는 Windcave 거래 ID와 함께 기록되며, 메모에는 금액, 거래 ID, 승인 코드, 마스킹된 카드 번호가 포함된 카드 유형, 환경(UAT 또는 운영)이 표시됩니다.

Windcave payment on hold (authorised): Auth 결제가 승인되었지만 아직 캡처되지 않았습니다. 캡처되기 전까지는 주문에 결제가 기록되지 않습니다. 메모에는 캡처하거나 해제하는 방법이 설명되어 있습니다.

Windcave payment on hold (does not match): Windcave가 보고한 금액, 통화, 가맹점 참조 번호 또는 거래 유형이 장바구니와 다릅니다(예: 결제가 시작된 후 다른 탭에서 장바구니가 변경된 경우). 메모에는 차이점이 나열됩니다. 장바구니 통화의 Purchase인 경우, 결제는 Windcave가 실제로 청구한 금액으로 기록됩니다. 배송 전에 Windcave Payline에서 결제를 확인하고, 필요하면 환불하십시오.

Refunded: 결제가 전액 환불되었거나, 모듈을 통해 승인이 해제되었습니다.

취소된 주문에 대해 승인된 결제가 도착하거나, 이미 존재하는 주문에 대해 두 번째 승인 결제가 도착하면, 주문은 변경되지 않습니다. 거래 ID가 포함된 메모는 Windcave Payline에서 환불하거나(또는 취소된 주문을 수동으로 복원하도록) 요청합니다.

Windcave payment block

주문 페이지에는 Windcave payment 블록이 표시되며, 거래 ID, 세션 ID, 거래 유형과 환경이 포함된 상태, 결제 금액, 승인 코드와 카드, 캡처 또는 취소 거래, 결제 합계와 환불 금액, 테스트 결제용 Test mode (UAT) 배지, 환불 이력, 장바구니의 모든 Windcave 세션, 주문의 Windcave notes가 포함됩니다.

Capture (Auth mode)

아직 캡처되거나 해제되지 않은 승인이 있는 Windcave payment on hold 주문의 경우, 블록에는 금액과 함께 Capture Windcave payment가 표시됩니다. 클릭한 후 Capture the authorised amount through Windcave now?를 확인하면, 승인된 금액이 캡처됩니다(결제가 주문과 일치하지 않는 경우를 제외하고 주문 합계). 주문은 Payment accepted로 바뀌고, 결제는 캡처 거래 ID와 함께 기록됩니다. Windcave가 캡처를 수락하지 않으면, 블록에 이유와 함께 Windcave capture failed:가 표시되고, 그 이유는 메모에 추가되며, 주문은 보류 상태로 남습니다.

Refunds

Windcave payment 블록에서 금액을 입력하고(아직 환불되지 않은 금액이 자동으로 채워집니다), 필요하면 사유를 입력한 다음 Refund via Windcave를 클릭합니다. Refund this amount through Windcave? This cannot be undone. 질문을 확인하십시오. 전액 및 부분 환불을 지원합니다. 주문을 편집할 수 있는 권한이 필요하며, 모듈 페이지에 접근할 필요는 없습니다. 환불은 Windcave가 승인한 금액과 통화를 기준으로 계산됩니다. 따라서 불일치가 발생한 후에는 주문 합계가 아니라 고객이 실제로 지불한 금액까지 환불할 수 있습니다. 캡처 이후의 환불은 캡처 거래로 처리됩니다. 환불은 결제가 이루어진 환경(UAT 또는 운영)과 계정으로 전송되므로, 해당 환경의 자격 증명이 저장되어 있어야 합니다. 성공한 환불은 Windcave 거래 ID와 함께 환불 이력과 메모에 추가됩니다. 전액 환불하면 주문은 Refunded로 설정됩니다. 부분 환불은 상태를 바꾸지 않습니다.

캡처되지 않은 Auth 결제의 경우 버튼은 Release authorisation (void)이 되며, 전액만 해제할 수 있습니다. 일부 금액을 입력하면 전액을 환불하거나 먼저 결제를 캡처하라는 오류가 표시됩니다.

Windcave가 환불을 거부하면 블록에 이유와 함께 Windcave declined the refund:가 표시되며, 환불은 기록되지 않습니다. Windcave가 아직 환불을 처리 중이면 블록에 Windcave has not confirmed the refund yet. See the order notes.가 표시되며, 환불은 기록되지 않습니다. Windcave Payline에서 거래를 확인하십시오. 승인되었다면 환불을 수동으로 기록하고, 그렇지 않으면 다시 시도하십시오. 같은 환불을 반복해서 시도해도 Windcave로 두 번 전송되지 않습니다.

이 모듈은 크레딧 메모를 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 Windcave를 통해 돈을 돌려보내지 않습니다. Windcave Payline에서 이루어진 환불은 쇼핑몰에 보고되지 않습니다.

라이선스 키

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

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

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

문제 해결

체크아웃에 Windcave가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 두 자격 증명이 모두 있는지 확인하십시오. 테스트 모드에서는 UAT API username과 UAT API key, 운영 모드에서는 Production API username과 Production API key입니다. 설정 페이지는 이들이 없으면 경고를 표시합니다. Payment > Preferences에서 모듈이 장바구니 통화, 고객의 국가, 고객 그룹에 대해 허용되어 있는지 확인하십시오.

결제는 완료되었으나 주문이 생성되지 않음: 모듈이 아직 Windcave에서 결과를 가져오지 못했습니다. 모듈 페이지의 Log 필드를 확인하십시오. 세션을 검증하지 못한 경우 등 오류는 항상 기록됩니다. 결제 환경의 자격 증명이 저장되어 있고 올바른지 확인하십시오. 이 확인은 Windcave가 알림을 다시 보낼 때(모듈은 오류 코드와 함께 payment could not be verified yet, retry later로 응답하여 Windcave가 다시 시도하도록 합니다), 고객이 Check again을 클릭할 때, 고객이 같은 장바구니로 새 결제를 시작할 때 반복됩니다. 서버는 설정에 표시된 Notification URL로 오는 Windcave의 요청을 수락해야 합니다.

알림이 order not found로 응답함: 해당 세션은 이 쇼핑몰이 만든 것이 아닙니다. 예를 들어 같은 Windcave 계정을 사용하는 다른 쇼핑몰의 세션입니다. 이 알림은 무시됩니다.

로그에 Authentication failed가 있음: REST API 사용자 이름이나 키가 잘못되었거나, 다른 환경의 것입니다. UAT 자격 증명은 테스트 모드에서만, 운영 환경 자격 증명은 운영 모드에서만 작동합니다. PxPay 키는 작동하지 않습니다.

고객에게 이 주문의 정보로 Windcave가 결제를 시작할 수 없었다고 표시됨: Windcave가 세션 요청을 거부했습니다. 예를 들어 통화나 계정에서 활성화되지 않은 결제 수단 때문입니다. 정확한 이유는 로그에 있습니다.

결제 후 주문이 Windcave payment on hold 상태임: Windcave payment 블록의 메모를 읽으십시오. 결제가 캡처를 기다리는 Auth이거나, 결제 금액, 통화, 가맹점 참조 번호가 장바구니와 달랐던 것입니다. 결제를 캡처, 발송 또는 환불하십시오.

테스트 결제와 실제 결제: UAT와 운영 환경은 분리되어 있습니다. 각 세션은 생성된 환경에서 확인되며, 환불과 캡처는 나중에 Test mode를 전환하더라도 결제의 환경으로 처리됩니다.

환불이 환경 관련 메시지와 함께 실패함: 결제는 UAT 또는 운영 환경에서 이루어졌으나, 해당 환경의 자격 증명이 저장되어 있지 않습니다. 자격 증명을 입력한 후 다시 시도하십시오.

주문 블록에 Capture Windcave payment가 없음: 이 버튼은 Auth로 결제되었고 아직 캡처 또는 해제되지 않은 Windcave payment on hold 주문에만 표시되며, 주문을 편집할 수 있는 직원에게만 보입니다.

자세한 내용 확인: 오류와 경고는 항상 로그에 기록됩니다. API 요청과 결제 이벤트도 기록하려면 Debug log를 켜십시오.

제거

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

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