VibeFox Viva Wallet for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

Viva 계정: Viva 가맹점 계정. 테스트에는 데모 계정(demo.vivapayments.com), 실제 결제에는 라이브 계정(www.vivapayments.com)을 사용할 수 있습니다. 각 계정에는 별도의 자격 증명이 있습니다. 결제에는 Smart Checkout 자격 증명(Client ID 및 Client Secret)과 결제 소스의 Source Code가 필요합니다. Merchant ID와 API Key는 선택 사항이며, Viva의 웹훅 URL 확인에 응답하는 데만 사용됩니다.

통화: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK 또는 CHF. 그 밖의 통화에서는 결제 시 결제 수단이 표시되지 않습니다.

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

설치

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

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

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

4. Viva 데모 계정 및/또는 라이브 계정의 자격 증명을 입력하고, Viva 계정에서 결제 소스와 웹훅을 설정합니다(설정 참조).

5. Enable/Disable을 켜고 Save를 클릭합니다. Test Mode가 켜진 상태에서 Viva 데모 카드로 데모 결제를 한 후, Test Mode를 끄면 실제 운영을 시작합니다.

설치 시 모듈은 주문 상태 Viva Wallet payment on hold를 생성합니다. 모듈은 설치 당시 활성화된 국가에 제공됩니다. 통화, 국가, 고객 그룹은 Payment > Preferences에서 변경할 수 있으며, 새 국가는 나중에 그곳에서 추가할 수 있습니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 필드 위에는 현재 모드에 Client ID, Client Secret 또는 Source Code가 없을 때(Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered., 또는 라이브 모드의 Live) 및 쇼핑몰의 기본 통화가 지원되지 않을 때 경고가 표시됩니다. 테스트 모드가 켜져 있는 동안에는 Test mode is on: payments go to the Viva demo environment. 메시지가 표시됩니다. 설정을 저장하면 캐시된 Viva 액세스 토큰이 삭제되므로 새 자격 증명이 즉시 사용됩니다.

Viva Wallet

Enable/Disable: Enable Viva Wallet payment gateway는 결제 수단을 켜거나 끕니다. 기본값: 꺼짐.

Title: 고객이 결제 시 보는 결제 수단 이름입니다. 주문에 저장되는 결제 수단 이름이기도 합니다. 기본값: Viva Wallet. 필수: 빈 제목은 저장되지 않으며, 페이지에 Enter a title for the payment method.가 표시됩니다.

Description: 결제 시 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: Viva 데모 환경(demo.vivapayments.com)을 사용합니다. 새 결제와 API 호출은 데모 계정의 자격 증명을 사용합니다. 실제 금액은 청구되지 않으며, 결제 시 고객에게 (Test mode: use Viva demo cards, no real money is charged.)가 표시됩니다. 기본값: 켜짐. 라이브 계정으로 실제 결제를 받으려면 끄십시오. 이미 이루어진 결제는 이루어진 환경에서 계속 확인 및 환불됩니다.

데모 계정(테스트 모드)과 라이브 계정

두 섹션은 필드가 같습니다. 데모 계정용 한 세트와 라이브 계정용 한 세트가 있습니다. Viva 계정에서 Settings > API Access를 열고 Smart Checkout 자격 증명(Client ID, Client Secret), Merchant ID, API Key를 복사합니다. Source Code는 Sales > Online payments > Websites / apps에 있습니다.

Client ID (Demo) / Client ID (Live): 계정의 Smart Checkout OAuth 2.0 Client ID입니다. 결제에 필요합니다.

Client Secret (Demo) / Client Secret (Live): 계정의 Smart Checkout OAuth 2.0 Client Secret입니다. 결제에 필요합니다.

Source Code (Demo) / Source Code (Live): 계정 결제 소스의 4자리 코드입니다. 해당 Success URL과 Failure URL은 이 쇼핑몰을 가리켜야 합니다(아래 참조). 결제에 필요합니다.

Merchant ID (Demo) / Merchant ID (Live): 선택 사항입니다. Viva의 웹훅 URL 확인에 응답하는 데만 사용됩니다.

API Key (Demo) / API Key (Live): 선택 사항입니다. Viva의 웹훅 URL 확인에 응답하는 데만 사용됩니다.

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

Clear saved secrets: 비밀 값을 체크하고 Save를 클릭하면 삭제됩니다. 필드를 비워 두면 저장된 값이 유지됩니다.

반환 URL 및 웹훅

Addresses for the Viva account: 이 필드에는 Viva 계정에 입력할 쇼핑몰의 세 가지 주소가 표시됩니다. 친숙한 URL을 사용하면 https://your-shop/module/wcp_viva_gateway/success, https://your-shop/module/wcp_viva_gateway/fail, https://your-shop/module/wcp_viva_gateway/webhook 형태이며, /en/ 같은 언어 코드가 붙을 수도 있습니다. 설정에 표시된 그대로 정확히 복사하십시오.

Payment source: 사용하는 각 Viva 계정에서 Sales > Online payments > Websites / apps에 들어가 쇼핑몰 도메인용 결제 소스를 만듭니다. Success URL과 Failure URL에는 성공 및 실패 주소에서 도메인 뒤에 오는 경로를 입력합니다.

Webhook: Settings > API Access > Webhooks에서 다음 이벤트에 대한 웹훅 주소를 추가합니다:

Viva는 저장하기 전에 URL을 확인합니다. 모듈은 계정의 확인 키로 응답합니다. 현재 모드의 Merchant ID와 API Key로 키를 가져오거나, 아래에 입력한 키를 사용합니다. 웹훅은 고객이 브라우저를 닫아도 결제를 확정합니다. Viva 웹훅은 서명되지 않으므로, 모듈은 웹훅만으로는 절대 신뢰하지 않습니다. 모든 결제는 주문을 생성하기 전에 Viva API로 검증됩니다. 웹훅이 없으면, 고객이 결제 후 쇼핑몰로 돌아왔을 때만 주문이 생성됩니다.

Webhook Verification Key: 선택 사항입니다. 비워 두면 현재 모드의 Merchant ID와 API Key로 키를 자동으로 가져오며, Viva 계정의 확인 키를 여기에 붙여 넣을 수도 있습니다.

고급 설정

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

Brand Color: Viva 결제 페이지용 6자리 HEX 색상 코드입니다(예: 0000ff). 앞의 #은 제거됩니다. 기본 색상을 쓰려면 비워 두십시오. 다른 값은 저장되지 않으며, 페이지에 Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept.가 표시됩니다.

Debug Logging: API 요청을 모듈 폴더의 logs/viva_wp_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 키, 토큰, 고객 데이터는 기록되지 않습니다. 오류는 이 옵션이 꺼져 있어도 항상 기록됩니다. 기본값: 꺼짐.

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

Delete Data on Uninstall: 켜져 있으면 모듈을 제거할 때 설정과 모듈 로그가 삭제됩니다. 주문과 결제 데이터(Viva 결제 시도, 환불, 주문 상태)는 절대 삭제되지 않습니다. 기본값: 꺼짐.

결제 과정

결제 단계에서 고객은 결제 수단(기본값 Viva Wallet)을 선택하고 You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). 안내를 봅니다. 확인하면 모듈은 장바구니 금액을 장바구니 통화로 하여 Viva 결제 주문을 생성하고, 고객을 Viva Smart Checkout 페이지로 보냅니다. 고객은 그곳에서 Viva 계정에 활성화된 결제 수단 중 하나로 결제합니다. 고객의 이메일, 이름, 전화번호, 국가가 Viva에 전달되며, Viva가 지원하는 경우 페이지는 장바구니의 언어로 열립니다. Viva에서 결제는 Cart #, 장바구니 번호, 쇼핑몰 이름으로 표시됩니다. Viva 결제 주문은 30분 후에 만료됩니다. 이 시점에는 아직 주문이 없습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 Viva가 확인한 후에만 결제 완료로 표시됩니다. 모듈은 복귀 시와 웹훅 수신 시 Viva API에서 거래를 다시 조회합니다. 그런 다음 주문이 생성되고, 고객은 표준 주문 확인 페이지를 봅니다. 결제가 아직 확인되지 않았다면 Payment confirmation 페이지에 We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. 메시지와 Check again, Back to checkout 버튼이 표시됩니다. Viva가 결제를 확인하는 즉시 웹훅이 주문을 생성합니다.

결제가 실패하거나 고객이 Viva 페이지에서 취소하면 주문은 생성되지 않으며 장바구니는 유지됩니다. 고객은 The Viva Wallet payment was not completed. Please try again or choose another payment method. 또는 The Viva Wallet payment was cancelled. You can try again or choose another payment method. 메시지와 함께 결제 단계로 돌아가 다시 결제할 수 있습니다.

Viva가 결제를 시작할 수 없으면, 고객은 Viva Wallet payments are not available at the moment. Please choose another payment method or contact us.(자격 증명이 없거나 잘못된 경우) 또는 We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. 메시지와 함께 결제 단계에 머무릅니다. 기술적인 원인은 로그에 기록됩니다.

반환 페이지는 결제한 고객에게만 주문 확인을 보여줍니다. 반환 주소를 여는 다른 사람은 주문 세부 정보 없이 주문 내역 또는 결제 단계로 이동합니다.

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

모듈은 일회성 결제만 지원하며, 결제는 Viva 페이지에서 즉시 청구됩니다. 사전 승인 및 캡처, 할부, 저장된 카드, 구독, Viva Native Checkout(자체 페이지의 카드 입력란), POS 단말기는 지원하지 않습니다. 고객이 새로운 시도를 시작해도 이전의 미결제 Viva 결제 주문은 취소되지 않으며, Viva가 30분 후에 만료시킵니다.

주문과 환불

주문 상태

아직 주문 없음: 고객이 Viva로 이동했지만 결제하지 않았거나, 결제가 실패했거나 취소되었거나, Viva가 아직 결제를 완료하지 않았습니다. 장바구니만 존재하며, 고객은 다시 결제할 수 있습니다.

Payment accepted, Delivered 또는 Viva Wallet payment on hold: 결제가 확인되었습니다. 상태는 Order Status After Payment를 따릅니다. 결제는 Viva 거래 ID와 함께 기록되며, 메모에는 금액, 거래, Viva 주문 코드, 환경(데모 또는 라이브), 확인 방식(웹훅 또는 고객 복귀)이 표시됩니다.

불일치 후 Viva Wallet payment on hold: Viva가 장바구니 금액이나 통화와 다른 금액 또는 통화를 보고했습니다. 예를 들어 고객이 결제를 시작한 후 장바구니가 변경된 경우입니다. 주문은 기록된 결제 없이 생성되며, Viva Wallet payment held for review 메모에 이유가 나옵니다. 고객은 Viva 확인을 약속하지 않는 표준 주문 확인 페이지를 봅니다. Viva 대시보드의 결제와 주문을 대조한 후, 주문을 처리하거나 결제를 수동으로 환불하십시오. 같은 장바구니에 대한 일치하는 결제가 나중에 도착하면 주문은 결제 완료 상태로 이동합니다.

취소되었거나 환불된 주문에 들어온 결제는 주문 상태를 바꾸지 않습니다. 메모는 주문을 복구하거나 Viva 대시보드에서 결제를 환불하라고 안내합니다. 이미 결제 완료된 주문에 두 번째 결제가 들어오면 주문은 변경되지 않으며, 메모는 중복 결제를 Viva 대시보드에서 환불하라고 안내합니다.

Viva Wallet payment 블록

주문 페이지에는 Viva 주문 코드, 거래 ID, 환경 및 Source Code, Viva 상태, 결제 금액 및 환불 금액, 데모 결제용 Demo 배지, 환불 내역, 장바구니의 결제 시도(한 번 이상인 경우), 주문의 Viva Wallet notes가 포함된 Viva Wallet payment 블록이 표시됩니다.

환불

Viva Wallet payment 블록에 금액을 입력합니다(아직 환불되지 않은 금액이 자동으로 채워집니다). 필요하면 사유를 입력하고 Refund via Viva Wallet을 클릭합니다. Refund this amount via Viva Wallet? This cannot be undone. 질문을 확인하십시오. 전액 및 부분 환불은 확인된 Viva 거래가 있는 주문에 대해 지원됩니다. 주문을 편집할 권한이 필요하며, 모듈 접근 권한은 필요하지 않습니다. 주문이 나중에 편집되었더라도 Viva가 결제에 대해 청구한 금액까지 환불할 수 있습니다. 환불은 결제가 이루어진 계정(데모 또는 라이브)으로 결제 통화에 맞춰 전송되므로, 해당 계정의 Client ID와 Client Secret이 입력되어 있어야 합니다. Viva가 환불을 받아들이지 않으면 블록에 오류가 표시되며 환불은 기록되지 않습니다. 성공한 환불은 Viva 환불 거래와 함께 환불 내역 및 메모에 추가됩니다. 전액 환불은 주문을 Refunded로 설정합니다. 부분 환불은 상태를 바꾸지 않습니다. 확인된 결제 없이 검토를 위해 보류된 주문은 이 블록에서 환불할 수 없습니다.

모듈은 신용 전표를 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 Viva를 통해 돈을 돌려주지 않습니다. Viva 대시보드에서 이루어진 환불은 가져오지 않습니다. 필요한 경우 주문을 수동으로 업데이트하십시오.

라이선스 키

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

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

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

문제 해결

결제 시 Viva Wallet이 표시되지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 Client ID, Client Secret, Source Code가 있는지 확인하십시오(테스트 모드에서는 Demo 필드, 라이브 모드에서는 Live 필드). 장바구니 통화는 EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK 또는 CHF 중 하나여야 합니다. Payment > Preferences에서 모듈이 장바구니 통화, 고객의 국가, 고객의 그룹에 대해 허용되어 있는지 확인하십시오. 자격 증명이 없으면 설정 페이지에 경고가 표시됩니다.

결제는 완료되었지만 주문이 생성되지 않음: 웹훅이 작동하지 않습니다. Viva에서 사용 중인 계정(데모 또는 라이브)에 웹훅이 있는지, URL이 설정에 표시된 것과 정확히 같은지, Transaction Payment Created가 선택되어 있는지 확인하십시오. 해당 결제 계정의 Client ID와 Client Secret이 아직 입력되어 있는지도 확인하십시오. 모듈이 결제를 검증하는 데 필요합니다. Debug Logging을 켜고 Log 필드를 확인하십시오. 고객이 결제 후 쇼핑몰로 돌아오면 주문도 생성됩니다.

Viva가 웹훅 URL을 확인할 수 없음: 현재 모드의 Merchant ID와 API Key(또는 Webhook Verification Key에 확인 키 자체)를 입력하고 저장한 다음, Viva에서 다시 확인하십시오. 다른 계정의 웹훅을 확인하려면 먼저 Test Mode를 전환하거나 해당 계정의 키를 입력하십시오.

웹훅이 오류로 응답함: Viva는 쇼핑몰의 응답을 표시하며 실패한 웹훅을 재시도합니다. verification_failed(HTTP 500)는 결제를 확인하기 위해 Viva API에 연결할 수 없었거나 주문을 생성할 수 없었음을 뜻합니다(예: 모듈이 비활성화된 경우). busy(HTTP 503)는 같은 시점에 다른 요청이 주문을 처리하고 있었음을 뜻합니다. transaction_not_found(HTTP 404)는 해당 결제 계정에 거래가 없음을 뜻하며, 예를 들어 잘못된 자격 증명 때문일 수 있습니다. 같은 Viva 계정의 다른 쇼핑몰 결제에 대한 이벤트는 ignored로 응답합니다.

고객이 Viva Wallet을 선택할 때 오류가 표시됨: 모듈 페이지의 Log 필드를 확인하십시오. 잘못된 Client ID 또는 Client Secret은 Viva Wallet 결제를 사용할 수 없다는 메시지를 표시합니다. Viva에 연결할 수 없거나 결제 주문을 거부하면(예: Source Code가 다른 계정에 속한 경우), 고객은 쇼핑몰이 Viva Wallet에 연결할 수 없다는 메시지를 받습니다.

고객이 돌아와서 We could not find your order. If you were charged, please contact us. 메시지를 봄: 반환 주소의 Viva 주문 코드가 이 쇼핑몰의 결제가 아닙니다. 예를 들어 다른 쇼핑몰의 결제 소스가 여기를 가리키는 경우입니다. 결제 소스의 Success URL과 Failure URL을 확인하십시오.

결제 후 주문이 Viva Wallet payment on hold 상태임: Viva Wallet payment 블록의 메모를 읽은 다음(주문 상태 참조), 주문을 처리하거나 결제를 환불하십시오.

This payment was made in the Viva demo (or live) environment: 메시지와 함께 환불이 실패함: 결제가 이루어진 계정의 Client ID와 Client Secret이 입력되지 않았습니다. 입력한 후 다시 시도하십시오. 다른 환불 오류는 HTTP 코드와 Viva의 메시지를 표시합니다.

블록에 Transaction ID not found. Cannot process refund. 메시지가 표시됨: 주문에 확인된 Viva 결제가 없습니다. 예를 들어 금액 불일치 후일 수 있습니다. 필요하면 Viva 대시보드에서 결제를 환불하십시오.

제거

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

Viva Wallet은 각 소유자의 상표입니다. 이 모듈은 Viva Wallet과 제휴하거나 Viva Wallet의 승인을 받지 않았습니다.