VibeFox Nexi XPay for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

WooCommerce: 7.0 이상, 설치 및 활성화되어 있어야 합니다.

PHP: 8.0 이상.

통화: 쇼핑몰 또는 주문 통화는 EUR이어야 합니다. 다른 통화의 경우 결제 시 결제 수단이 숨겨집니다.

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

공개 사이트: 알림 URL은 인터넷에서 접근할 수 있어야 합니다. 유지 보수 모드, 기본 인증 또는 Nexi를 차단하는 방화벽 규칙이 없어야 합니다. 그렇지 않더라도 서명된 고객 복귀 정보로 결제가 확인됩니다.

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

설치

1. WordPress에서 Plugins > Add New > Upload Plugin으로 이동하여 플러그인 ZIP 파일을 선택하고 Install Now를 클릭합니다. FTP로 wcp_nexi_gateway 폴더를 /wp-content/plugins/에 업로드할 수도 있습니다.

2. Activate를 클릭합니다.

3. 설정을 엽니다: WooCommerce > Settings > Payments > Nexi XPay > Manage, 또는 플러그인 페이지에서 플러그인 이름 아래의 Settings를 클릭합니다.

4. 페이지 상단의 라이선스 블록에 VibeFox 라이선스 키를 입력하고 Activate를 클릭합니다.

5. Test Mode를 켜둔 채로 테스트 별칭과 MAC 키를 입력합니다(구성 항목 참조).

6. Enable/Disable을 켜고 테스트 주문을 진행합니다. 모든 것이 정상 작동하면 실서비스 별칭과 MAC 키를 입력하고 Test Mode의 체크를 해제합니다.

구성

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Nexi XPay. 입력란 위에는 테스트 모드가 켜져 있는 동안 테스트 모드가 켜져 있습니다: 결제는 Nexi XPay 테스트 환경으로 전달되며 실제 금액은 청구되지 않습니다.가 표시됩니다. 게이트웨이가 활성화되어 있는데 현재 모드의 별칭 또는 MAC 키가 비어 있거나 쇼핑몰 통화가 EUR이 아니면 경고도 표시됩니다. 두 경우 모두 결제 시 결제 수단이 숨겨집니다. 붙여넣은 키 앞뒤의 공백과 줄바꿈은 저장할 때 제거됩니다.

일반

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

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: Enable test mode는 Nexi XPay 테스트 환경과 테스트 자격 증명을 사용합니다. 체크를 해제하면 실서비스 자격 증명으로 실제 결제를 받습니다. 기본값: 켬.

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 계산 키.

결제

알림 URL은 모든 결제와 함께 Nexi에 전달되므로 백오피스에서 따로 설정할 것은 없습니다. 이 섹션에 URL이 표시되며, https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id}와 같은 형식이고 끝에 주문 ID가 붙습니다. Nexi는 결제 결과를 서버 간 통신으로 이 URL에 보내며, 고객이 돌아올 때도 함께 전달합니다. 두 방식 모두 같은 방식으로 서명되며, 결제가 이루어진 환경의 MAC 키, 해당 환경의 별칭, 그리고 해당 주문에 발급된 거래 코드로 검증됩니다. 검증에 실패한 결과는 거부되며 아무것도 변경하지 않습니다.

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

Immediate capture: 결제가 즉시 캡처되고 주문은 결제 완료로 표시됩니다(기본값).

Deferred capture (authorize only): 캡처는 단말기 프로필에 따릅니다. 주문은 승인 상태로 보류되며, 주문 작업 Capture Nexi XPay payment로 캡처하거나 Nexi 백오피스에서 캡처한 뒤 주문을 처리 중으로 변경할 때까지 유지됩니다.

Order Status After Payment: 결제 성공 후 주문의 상태. 상태는 한 번의 상태 변경과 한 통의 이메일로 즉시 설정됩니다.

처리 중(WooCommerce 기본값): 기본값입니다.

완료됨: 결제 완료된 모든 주문이 완료됨으로 바뀝니다.

보류 중: 결제 완료된 모든 주문은 수동 검토를 기다립니다.

고급

Debug Log: Enable logging은 결제 이벤트를 WooCommerce > Status > Logs에 소스 wcp_nexi_gateway로 기록합니다. MAC 키, 카드 데이터, 이메일 주소는 기록되지 않습니다. MAC 검사 실패와 같은 오류와 경고는 옵션이 꺼져 있어도 항상 기록됩니다. 기본값: 끔.

Delete Data on Uninstall: Remove all plugin settings and logs when uninstalled. 기본값: 끔.

체크아웃

고객은 결제 수단(기본값 Credit Card (Nexi))을 선택하고 주문을 진행합니다. 다음 페이지에는 Nexi XPay로 이동하여 결제하는 중...이 표시되고, 고객은 자동으로 Nexi XPay 페이지로 이동합니다. 자동 이동이 되지 않을 경우를 대비해 Pay Now 버튼도 제공됩니다. 결제는 새 거래 코드, 고객의 이메일, 설명 Order, 주문 번호, 쇼핑몰 이름과 함께 EUR로 전달됩니다. Nexi 페이지는 쇼핑몰 언어가 이탈리아어, 영어, 스페인어, 프랑스어, 독일어, 일본어, 중국어, 아랍어, 러시아어 또는 포르투갈어일 때 해당 언어로 열리며, 그 밖의 경우에는 영어로 열립니다.

고객은 결제 후 쇼핑몰의 주문 접수 페이지로 돌아갑니다. 주문은 주문 금액과 통화가 정확히 일치하는 검증된 Nexi 결과를 받은 후에만 결제 완료로 표시됩니다. 서버 간 알림 또는 서명된 고객 복귀 정보 중 먼저 도착하는 쪽이 사용됩니다.

결제가 거부되거나 고객이 Nexi 페이지에서 취소하면, 고객은 체크아웃(장바구니가 비어 있으면 Pay for order 페이지)으로 돌아가 다음 메시지 중 하나를 보게 됩니다: 결제가 완료되지 않았습니다. 다시 시도하거나 다른 결제 수단을 선택해 주세요., 결제가 취소되었습니다. 다시 시도해 주세요. 또는 결제를 확인할 수 없습니다. 카드에서 금액이 청구되었다면 다시 결제하기 전에 문의해 주세요. Nexi 페이지에서 취소해도 주문은 변경되지 않으므로 고객은 다시 결제할 수 있습니다.

플러그인이 현재 모드에 맞게 설정되지 않은 경우 고객에게는 이 결제 수단은 현재 사용할 수 없습니다. 다른 결제 수단을 선택해 주세요.가 표시됩니다.

결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다.

플러그인은 Nexi XPay 페이지에서만 결제를 받습니다. WooCommerce에서의 환불, 저장된 카드나 OneClick, 구독이나 정기 결제, Pay-By-Link, XPay Build 내장 필드, WooCommerce에서 선택하는 결제 수단은 지원하지 않습니다. Nexi 페이지에는 단말기에서 활성화된 결제 수단이 표시됩니다.

주문 및 환불

주문 상태

결제 대기: 고객이 Nexi로 이동했지만 아직 결제하지 않았거나 Nexi 페이지에서 취소했습니다.

처리 중, 완료됨 또는 보류 중: Nexi가 결제를 확인했습니다. 상태는 Order Status After Payment를 따릅니다. 주문 메모에는 승인 코드, 거래 코드, 카드 브랜드, Nexi 메시지가 표시됩니다. 거래 ID는 Nexi 거래 코드입니다.

보류 중(승인됨): 지연 캡처가 선택되었고 결제는 승인만 된 상태입니다. 주문 작업 Capture Nexi XPay payment로 캡처하세요.

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

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

실패: 가장 최근의 결제 시도가 거부되었거나, 취소되었거나, 오류로 끝났습니다. 고객은 다시 결제할 수 있습니다.

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

지연 캡처

승인되어 보류 중인 주문을 열고, 주문 작업에서 Capture Nexi XPay payment를 선택한 뒤 화살표를 클릭합니다. 플러그인은 결제가 이루어진 환경에서 승인된 금액을 캡처하고, Order Status After Payment에 설정된 상태로 주문을 결제 완료로 표시합니다. 캡처가 실패하면 오류가 주문 화면에 표시되고 주문 메모에 추가되며, 주문은 보류 상태를 유지합니다.

환불

환불은 WooCommerce에서 진행하지 않으므로 Refund via 버튼이 없습니다. Nexi XPay 백오피스에서 환불을 진행한 뒤 WooCommerce에 수동으로 기록하세요.

라이선스 키

플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Payments > Nexi XPay 상단에 있습니다. License key에 키를 붙여넣고 Activate를 클릭하세요. 블록에는 라이선스가 유효한 기간과 도메인 등의 상태가 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하며, Remove key로 이 사이트에서 키를 제거할 수 있습니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

키 하나는 도메인 하나에서만 작동합니다. 사이트에서 키를 제거해도 도메인 슬롯은 비워지지 않습니다. vibefox.net 계정에서 슬롯을 비우세요.

활성 키가 없으면 Nexi XPay는 결제 시 고객에게 표시되지 않습니다. 그럼에도 결제가 시작되면 고객은 이 결제 수단은 사용할 수 없습니다. 다른 것을 선택해 주세요.를 보게 됩니다. 로그인한 쇼핑몰 관리자에게는 (unlicensed — visible to admins only)로 표시된 결제 수단이 계속 보이므로, 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 페이지와 WooCommerce 페이지에 알림이 표시됩니다. 기존 주문은 영향을 받지 않습니다. 이미 시작된 결제는 계속 확인되며, 지연된 결제도 계속 캡처할 수 있습니다.

라이선스가 만료되어도 플러그인은 계속 작동하지만, 업데이트와 지원을 받으려면 갱신이 필요합니다. 상태는 백그라운드에서 자동으로 다시 확인됩니다.

문제 해결

체크아웃에 Nexi XPay가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 두 가지 자격 증명(테스트 모드에서는 Test Alias와 Test MAC Key, 실서비스 모드에서는 Live Alias와 Live MAC Key)이 모두 있는지, 그리고 쇼핑몰 또는 주문 통화가 EUR인지 확인하세요. 설정 페이지는 이런 경우 경고를 표시합니다.

결제는 완료되었지만 주문이 결제 대기 상태로 남아 있음: 알림도 고객 복귀 정보도 승인되지 않았습니다. 쇼핑몰이 인터넷에서 접근 가능한지, MAC 키와 별칭이 결제의 환경(테스트 또는 실서비스)과 일치하는지 확인하고, Debug Log를 켜서 WooCommerce > Status > Logs, 소스 wcp_nexi_gateway에서 Nexi가 보낸 내용을 확인하세요.

알림이 invalid_mac 또는 invalid_alias로 응답함: 설정의 MAC 키 또는 별칭이 결과를 보낸 단말기와 일치하지 않습니다. Nexi 테스트 영역 또는 백오피스에서 다시 복사하세요.

알림이 unknown_transaction으로 응답함: 해당 거래 코드는 이 쇼핑몰이 그 주문에 대해 발급하지 않은 것입니다. 결과는 무시됩니다.

알림이 not_configured 또는 busy로 응답함: 결제 환경의 별칭 또는 MAC 키가 비어 있거나, 다른 요청이 같은 순간 주문을 업데이트하고 있었습니다. Nexi가 알림을 다시 보냅니다.

결제 후 주문이 보류 중임: 주문 메모를 읽으세요. 지연 캡처가 선택되어 있거나(주문 작업으로 결제를 캡처하세요), 금액 또는 통화가 일치하지 않았거나, 취소된 주문에 결제가 도착했거나, Nexi에서 결제가 대기 중이거나, 결제 후 상태로 보류 중이 선택되어 있을 수 있습니다.

Capture Nexi XPay payment가 없거나 실패함: 이 작업은 지연 캡처로 승인되어 보류 중인 Nexi 주문에만 표시됩니다. 실패하면 주문 메모에서 오류를 확인하세요. 캡처는 결제가 이루어진 환경의 키를 사용합니다.

라이선스 블록에 오류가 표시됨: 블록의 메시지를 따르세요. 예를 들어 키가 다른 도메인에서 이미 사용 중이면 vibefox.net 계정에서 슬롯을 비우고 Check now를 클릭하세요. 사이트 주소가 바뀌었다면 Check now를 클릭해 새 도메인에 키를 활성화하세요. 라이선스 서버에 연결할 수 없으면 플러그인은 마지막으로 확인된 상태로 계속 작동합니다.

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화한 뒤 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 제거됩니다. 게이트웨이 설정과 로그는 Delete Data on Uninstall이 켜져 있었던 경우에만 제거됩니다. 그렇지 않으면 나중에 다시 설치할 때를 위해 유지됩니다. 기존 주문은 결제 메모와 거래 ID를 유지합니다.

Nexi와 XPay는 각 소유자의 상표입니다. 이 플러그인은 Nexi와 제휴하거나 Nexi의 승인을 받지 않았습니다.