VibeFox Nexi XPay for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

통화: 장바구니의 통화는 EUR이어야 합니다. 다른 통화의 경우 결제 시 이 결제 수단이 표시되지 않습니다.

Nexi XPay 계정: 터미널의 별칭(터미널 ID)과 MAC 키가 포함된 Nexi XPay 가맹점 계정("Pagamento Semplice" 리디렉션 연동)이 필요합니다. 테스트 자격 증명과 실서비스 자격 증명은 별도입니다. 테스트 자격 증명은 Nexi XPay 테스트 영역이나 개발자 포털(developer.nexi.it)에서 받고, 실서비스 자격 증명은 가맹점 계정이 활성화된 후 Nexi XPay 백오피스에서 받습니다. Nexi 백오피스에서는 아무것도 설정할 필요가 없습니다. 알림 주소는 모든 결제와 함께 전달됩니다.

공개 사이트: 알림 URL은 인터넷에서 접근할 수 있어야 하며, Nexi를 차단하는 기본 인증이나 방화벽 규칙이 없어야 합니다. 쇼핑몰의 유지 보수 모드는 이를 차단하지 않습니다. 알림이 쇼핑몰에 도달하지 못하더라도 서명된 고객 복귀를 통해 결제는 확인됩니다.

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

설치

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

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

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

4. Test Mode를 켠 상태로 두고 테스트용 별칭과 MAC 키를 입력합니다(설정 항목 참조).

5. Enable/Disable을 켜고 Save를 클릭한 후 테스트 주문을 생성합니다. 모든 것이 정상적으로 작동하면 실서비스용 별칭과 MAC 키를 입력하고 Test Mode를 끕니다.

설치 시 모듈은 두 가지 주문 상태를 생성합니다: Awaiting Nexi XPay payment와 Nexi XPay payment on hold. PrestaShop은 모든 통화, 국가, 고객 그룹에 대해 새 결제 모듈을 제공합니다. Payment > Preferences에서 이를 제한할 수 있습니다. 모듈 설치 후 쇼핑몰에서 활성화한 국가도 그곳에서 체크해야 합니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 테스트 모드가 켜져 있는 동안 페이지는 입력란 위에 Test mode is on: payments go to the Nexi XPay test environment, no real money is charged.를 표시합니다. 게이트웨이는 활성화되어 있지만 현재 모드의 별칭이나 MAC 키가 비어 있거나, 쇼핑몰의 기본 통화가 EUR이 아닌 경우 경고가 표시됩니다. 이러한 경우 결제 시 이 결제 수단은 표시되지 않습니다. 붙여 넣은 값 앞뒤의 공백과 줄바꿈은 저장할 때 제거됩니다.

Nexi XPay

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

Title: 결제 시 고객에게 표시되는 결제 수단의 제목입니다. 주문에 저장되는 결제 수단 이름이기도 합니다. 기본값: Credit Card (Nexi). 테스트 모드에서는 결제 페이지와 주문의 제목에 (TEST MODE)가 추가됩니다.

Description: 결제 시 고객에게 표시되는 결제 수단의 설명입니다. 기본값: Pay securely with your credit card via Nexi XPay.

테스트 환경

테스트 결제는 int-ecommerce.nexi.it로 전송되며 실제 카드에 요금이 청구되지 않습니다. 테스트 별칭과 MAC 키는 Nexi XPay 테스트 영역이나 개발자 포털(developer.nexi.it)에서 받을 수 있습니다.

Test Mode: Nexi XPay 테스트 환경과 테스트 자격 증명을 사용합니다. 실서비스 자격 증명으로 실제 결제를 받으려면 끄십시오. 기본값: on.

Test Alias: Nexi XPay 테스트 터미널의 별칭(터미널 ID)입니다.

Test MAC Key: Nexi XPay 테스트 터미널의 MAC 계산 키입니다.

실서비스 환경

실서비스 별칭과 MAC 키는 가맹점 계정이 활성화된 후 Nexi XPay 백오피스(ecommerce.nexi.it)에 표시됩니다.

Live Alias: Nexi XPay 실서비스 터미널의 별칭(터미널 ID)입니다.

Live MAC Key: Nexi XPay 실서비스 터미널의 MAC 계산 키입니다.

저장된 MAC 키는 다시 표시되지 않습니다. 입력란은 비어 있으며 Saved — leave empty to keep it.를 표시합니다. 변경하려는 경우에만 새 값을 입력하십시오.

저장된 비밀 정보 삭제: Test MAC Key 또는 Live MAC Key를 체크하고 Save를 클릭하면 저장된 키가 삭제됩니다. 빈 입력란은 저장된 값을 유지합니다.

결제

Notification URL: 참고용으로 표시됩니다. 모든 결제와 함께 Nexi로 전송되므로 Nexi 백오피스에서 설정할 것은 없습니다. 친숙한 URL을 사용하는 경우 https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}와 같은 형태이며, /it/ 같은 언어 코드가 포함될 수 있고 끝에 장바구니 번호가 붙습니다. Nexi는 결제 결과를 서버 간 방식으로 이 URL에 전송하고, 고객의 복귀와 함께도 전달합니다. 두 방식 모두 같은 방법으로 서명되며, 결제가 이루어진 환경의 MAC 키, 해당 환경의 별칭, 그 장바구니에 발급된 거래 코드로 검증됩니다. 검증에 실패한 결과는 거부되며 아무것도 변경하지 않습니다.

Capture: 금액이 청구되는 시점입니다.

Order Status After Payment: 결제가 성공한 후 주문의 상태입니다.

고급

Debug Log: 결제 이벤트를 모듈 폴더의 logs/nexi_ip_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. MAC 키, MAC 값, 카드 정보, 이메일 주소는 기록되지 않습니다. MAC 검증 실패와 같은 오류와 경고는 이 옵션이 꺼져 있어도 항상 기록됩니다. 기본값: off.

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

Delete Data on Uninstall: 켜져 있으면 모듈을 제거할 때 모든 모듈 설정과 로그가 삭제됩니다. 주문의 Nexi XPay 결제 데이터와 주문 상태는 유지됩니다. 기본값: off.

결제 페이지

결제 단계에서 고객은 결제 수단(기본값 Credit Card (Nexi))을 선택하고 확인합니다. 다음 페이지에는 Redirecting to Nexi XPay for payment...가 표시되며, 고객은 자동으로 Nexi XPay 페이지로 이동합니다. 대체 수단으로 Pay Now 버튼도 제공됩니다. 결제는 장바구니 합계를 EUR로, 새 거래 코드, 고객의 이메일, 설명 Cart, 장바구니 번호, 쇼핑몰 이름과 함께 전송됩니다. Nexi 페이지는 장바구니 언어가 이탈리아어, 영어, 스페인어, 프랑스어, 독일어, 일본어, 중국어, 아랍어, 러시아어 또는 포르투갈어인 경우 그 언어로 열리며, 그 외에는 영어로 열립니다. 이 시점에는 아직 주문이 없습니다.

고객은 결제를 마치고 쇼핑몰로 돌아옵니다. 주문은 장바구니의 정확한 금액과 통화가 포함된 검증된 Nexi 결과를 받은 후에만 결제 완료로 표시됩니다. 서버 간 알림 또는 서명된 고객 복귀 중 먼저 도착하는 것을 기준으로 합니다. 그 후 주문이 생성되고 고객은 Your Nexi XPay payment has been received.라는 문구가 있는 표준 주문 확인 페이지를 봅니다. Nexi가 결제를 보류 중으로 보고하면 페이지에 Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed.가 표시됩니다. 보류 상태의 주문(지연 캡처 또는 수동 검토)의 경우 We have received your Nexi XPay payment authorization. Your order will be processed shortly.가 표시됩니다. 보류 중이던 결제가 나중에 실패하면 페이지에 The payment was not completed. Please contact us.가 표시됩니다.

고객이 돌아왔을 때 결과가 아직 처리되지 않았다면 We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. 문구와 Check again 버튼이 있는 페이지가 표시됩니다. 알림이 도착하는 즉시 주문이 생성됩니다.

결제가 거부되거나 고객이 Nexi 페이지에서 취소하면 고객은 결제 페이지로 돌아가 다음 메시지 중 하나를 보게 됩니다: The payment was not completed. Please try again or choose a different payment method., Payment was cancelled. Please try again. 또는 We could not confirm the payment. If your card was charged, please contact us before paying again. 주문은 생성되지 않으며 장바구니는 유지되므로 고객은 다시 결제할 수 있습니다. 장바구니에 이미 주문이 있는 경우(예: 다른 탭에서 결제됨), 고객은 새 결제 대신 주문 확인 페이지로 이동합니다.

모듈이 현재 모드용으로 설정되지 않은 경우, 고객에게는 This payment method is not available right now. Please choose another payment method.가 표시됩니다.

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

모듈은 Nexi XPay 페이지에서만 결제를 받습니다. PrestaShop에서의 환불, 저장된 카드 또는 OneClick, 구독이나 정기 결제, Pay-By-Link, XPay Build 내장 필드, PrestaShop에서 선택한 결제 수단은 지원하지 않습니다. Nexi 페이지에는 터미널에서 활성화된 결제 수단이 표시됩니다.

주문 및 환불

주문 상태

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

Payment accepted, Delivered or Nexi XPay payment on hold: Nexi가 결제를 확인했습니다. 상태는 Order Status After Payment를 따릅니다. 결제는 Nexi 거래 코드를 거래 ID로 하여 기록되며, 메모에는 승인 코드, 거래 코드, 카드 브랜드, Nexi 메시지가 표시됩니다.

Nexi XPay payment on hold (authorized): 지연 캡처가 선택되었고 결제는 승인만 된 상태입니다. 주문 페이지에서 Capture Nexi XPay payment로 캡처하십시오.

Awaiting Nexi XPay payment: Nexi가 결제를 확인 대기 중으로 보고했습니다. 주문은 최종 결과에 따라 업데이트됩니다.

Nexi XPay payment on hold after payment: Nexi에서 받은 금액 또는 통화가 장바구니와 일치하지 않았거나(주문은 결제 완료로 표시되지 않음), 이미 취소된 주문에 대해 성공한 결제가 도착했습니다. 메모에 이유가 설명되어 있습니다. Nexi XPay 백오피스에서 결제를 확인한 후 주문을 처리하거나 환불하십시오.

결제 오류: 보류 중이던 결제가 실패했습니다. 같은 장바구니는 다시 결제할 수 없으므로 고객은 새 주문을 해야 합니다.

결제 완료된 주문은 이후의 실패로 등급이 낮아지지 않습니다. 이미 결제된 주문에 대해 다른 성공한 결제가 도착하면, 중복인 경우 Nexi XPay 백오피스에서 환불하라는 메모가 표시됩니다.

Nexi XPay 결제 블록

주문 페이지에는 Nexi XPay payment 블록이 표시되며, 거래 코드(codTrans), 상태 및 Nexi 결과, 캡처 모드, Nexi로 보낸 금액과 받은 금액, 승인 코드, 카드 브랜드, Nexi 메시지와 날짜, 테스트 결제의 경우 Test environment 배지, 그리고 주문의 Nexi XPay notes가 포함됩니다.

지연 캡처

승인되어 보류 중인 주문의 경우 블록에서 Capture Nexi XPay payment를 클릭하고(버튼에 금액이 표시됨), Capture the authorized amount through Nexi XPay? 질문을 확인하십시오. 주문을 편집할 권한이 필요합니다. 모듈은 결제가 이루어진 환경에서 해당 환경의 키로 승인된 금액을 캡처하고, 결제를 기록하며, Order Status After Payment에 따라 상태를 설정합니다. 캡처가 실패하면 블록에 오류가 표시되고 메모가 추가되며 주문은 보류 상태로 남습니다. 같은 결제를 두 번 캡처하려고 하면 거부됩니다.

환불

환불은 PrestaShop에서 하지 않으므로 Nexi XPay용 환불 버튼은 없습니다. Nexi XPay 백오피스에서 환불을 진행한 후 PrestaShop에 수동으로 기록하십시오. 주문 페이지의 기본 PrestaShop 환불 버튼은 Nexi를 통해 돈을 돌려주지 않습니다.

라이선스 키

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

활성 키가 없으면 결제 시 고객에게 Nexi XPay가 표시되지 않습니다. 결제가 그래도 시작되면 고객에게 This payment method is not available. Please choose another one.가 표시됩니다. PrestaShop 스토어프런트는 백오피스에 로그인한 사실을 알지 못하므로, 결제 수단은 본인에게도 숨겨집니다. 구매 전에 모듈을 설정할 수는 있지만 결제 시 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 표시됩니다. 기존 주문에는 영향이 없습니다. 이미 시작된 결제는 여전히 확인되며, 승인된 결제는 계속 캡처할 수 있습니다.

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

문제 해결

결제 시 Nexi XPay가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 두 자격 증명이 모두 있는지(테스트 모드에서는 Test Alias와 Test MAC Key, 실서비스 모드에서는 Live Alias와 Live MAC Key), 그리고 장바구니 통화가 EUR인지 확인하십시오. 이런 경우 설정 페이지에 경고가 표시됩니다. Payment > Preferences에서 모듈이 EUR, 고객의 국가, 고객의 그룹에 대해 허용되어 있는지 확인하십시오.

결제는 완료되었지만 주문이 생성되지 않음: 알림과 고객의 복귀가 모두 수락되지 않았습니다. 쇼핑몰이 인터넷에서 접근 가능한지, MAC 키와 별칭이 결제의 환경(테스트 또는 실서비스)과 일치하는지 확인하고, Debug Log를 켜서 모듈 페이지의 Log 필드에서 Nexi가 보낸 내용을 확인하십시오.

알림이 invalid_mac 또는 invalid_alias로 응답: 설정의 MAC 키 또는 별칭이 결과를 보낸 터미널과 일치하지 않습니다. Nexi 테스트 영역이나 백오피스에서 다시 복사하십시오.

알림이 unknown_transaction으로 응답: 해당 거래 코드는 이 쇼핑몰이 그 장바구니에 대해 발급한 것이 아닙니다. 결과는 무시됩니다.

알림이 not_configured 또는 busy로 응답: 결제 환경의 별칭 또는 MAC 키가 비어 있거나, 같은 순간에 다른 요청이 주문을 업데이트 중이었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). Nexi는 알림을 다시 시도합니다.

알림 URL을 브라우저에서 열면 method_not_allowed가 표시됨: 정상입니다. 이 URL은 Nexi의 요청만 받습니다.

주문이 Nexi XPay payment on hold after payment 상태임: 주문 블록의 Nexi XPay notes를 읽으십시오. 지연 캡처가 선택되었거나(버튼으로 결제를 캡처하십시오), 금액 또는 통화가 일치하지 않았거나, 취소된 주문에 대해 결제가 도착했거나, 결제 후 상태로 Nexi XPay payment on hold가 선택되어 있습니다.

Capture Nexi XPay payment가 없거나 실패함: 이 버튼은 지연 캡처로 승인되어 보류 중인 Nexi XPay 주문에만 표시되며, 주문을 편집할 수 있는 직원에게만 표시됩니다. 결제 환경의 별칭 또는 MAC 키가 비어 있으면 블록에 그 사실이 표시됩니다. 캡처가 실패하면 블록과 메모의 오류를 읽으십시오. 예: Nexi 코드와 메시지가 포함된 Nexi XPay refused the capture.

테스트 결제가 실서비스 결제를 확인하지 않음: 각 결제는 시작된 환경의 키로 검증됩니다. Test Mode를 원하는 모드로 전환하고 해당 모드의 별칭과 MAC 키를 사용하십시오.

제거

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

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