VibeFox Viva Wallet for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

WooCommerce: 7.0 이상, 설치 및 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인이 활성화되지 않습니다.

PHP: 8.0 이상.

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. 그 밖의 통화에서는 체크아웃에서 결제 수단이 숨겨집니다.

공개 HTTPS 사이트: 웹훅을 받으려면 사이트가 인터넷에서 HTTPS로 접근 가능해야 합니다.

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

설치

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

2. Activate를 클릭하세요.

3. 설정을 여세요: WooCommerce > Settings > Payments > Viva Wallet > Manage. 또는 Plugins 페이지에서 플러그인 이름 아래의 Settings를 클릭하세요.

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

5. Viva 데모 및/또는 라이브 계정의 자격 증명을 입력하고, 결제 소스와 웹훅을 설정하세요(설정 항목 참조).

6. Enable/Disable을 켜세요. Test Mode가 켜진 상태에서 Viva 데모 카드로 데모 결제를 진행한 뒤, Test Mode 체크를 해제하여 라이브로 전환하세요.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Viva Wallet. 현재 모드에 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 Wallet이 설정 필요 상태로 표시됩니다.

General

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

Title: 고객이 체크아웃에서 보는 결제 수단 이름입니다. 기본값: Viva Wallet.

Description: 체크아웃에서 결제 수단 아래에 표시되는 문구입니다. 기본값: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: Use the Viva demo environment (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 확인에 응답할 때만 사용됩니다.

반환 URL 및 웹훅

Payment source: 사용하는 각 계정의 Sales > Online payments > Websites / apps에서 쇼핑몰 도메인용 결제 소스를 만드세요. Success URL과 Failure URL에는 설정에 표시된 두 주소의 도메인 뒤 경로를 입력하세요. 주소는 다음과 같은 형태입니다: https://your-site/wc-api/viva_payment_success/ 및 https://your-site/wc-api/viva_payment_fail/.

Webhook: Settings > API Access > Webhooks에서 설정에 표시된 URL을 추가하세요. URL은 다음과 같은 형태입니다: https://your-site/wp-json/wc-viva-gateway/v1/webhook. 다음 이벤트를 선택하세요:

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). 앞의 #은 제거됩니다. 기본 색상을 쓰려면 비워 두세요. 그 밖의 값은 저장 시 거부되고 이전 값이 유지됩니다.

Debug Logging: Enable logging을 켜면 API 요청이 WooCommerce > Status > Logs에 기록됩니다(소스: wcp_viva_gateway). 키와 고객 데이터는 기록되지 않습니다. 이 옵션을 꺼 두어도 오류는 항상 기록됩니다. 기본값: 끔.

Delete Data on Uninstall: Remove all plugin data when the plugin is deleted. 켜져 있으면 플러그인을 삭제할 때 설정, 결제 시도 테이블, 플러그인 로그가 제거됩니다. 주문 메모와 주문 데이터는 유지됩니다. 기본값: 끔.

체크아웃

고객이 결제 수단(기본값 Viva Wallet)을 선택하고 주문합니다. 플러그인은 주문 금액을 주문 통화로 하는 Viva 결제 주문을 만들고, 고객을 Viva Smart Checkout 페이지로 보냅니다. 고객은 그곳에서 Viva 계정에 활성화된 결제 수단(카드, Apple Pay, Google Pay 등) 중 하나로 결제합니다. 고객의 이메일, 이름, 전화번호, 국가는 Viva로 전달되며, 페이지는 Viva가 지원하면 쇼핑몰의 언어로, 지원하지 않으면 영어로 열립니다. Viva에는 결제가 WooCommerce #와 주문 번호로 표시됩니다. Viva 결제 주문은 30분 후에 만료됩니다.

결제 후 고객은 쇼핑몰의 주문 접수 페이지로 돌아갑니다. 주문은 Viva가 확인한 후에만 결제 완료로 표시됩니다. 플러그인은 복귀 시와 웹훅 시점에 Viva API에서 거래를 다시 조회합니다. 결제가 아직 확인되지 않았다면 페이지에 We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed.가 표시됩니다.

결제가 실패하거나 고객이 Viva 페이지에서 취소하면 주문 상태는 바뀌지 않습니다. 고객은 Pay for order 페이지로 이동하며, 여기에는 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.가 표시됩니다. 기술적인 이유는 로그에 기록됩니다.

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

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

주문 및 환불

Order statuses

Pending payment: 고객이 Viva로 이동했지만 아직 결제하지 않았거나, 결제가 아직 확인되지 않았거나, 결제가 실패 또는 취소된 상태입니다. 메모에는 Viva 결제 주문과 환경(데모 또는 라이브)이 표시됩니다. 실패하거나 취소된 시도는 주문 메모에 추가되며, 고객은 다시 결제할 수 있습니다.

Processing, Completed or On Hold: 결제가 확인되었습니다. 상태는 Order Status After Payment를 따릅니다. 주문 메모에는 금액, Viva 거래 ID, 환경, 확인 방식(웹훅 또는 고객의 복귀)이 표시됩니다.

On hold for review: Viva가 주문 총액과 다른 금액이나 통화를 보고했습니다. 예를 들어 고객이 결제를 시작한 뒤 주문이 수정된 경우입니다. Viva Wallet payment held for review 메모에 그 이유가 적힙니다. Viva 대시보드에서 결제를 주문과 비교한 뒤 주문을 완료하거나 결제를 수동으로 환불하세요.

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

환불

주문을 열고 Refund를 클릭한 다음 금액을 입력하고 Refund via Viva Wallet을 클릭하세요. Viva 거래가 확인된 주문에 대해 전액 및 부분 환불을 지원합니다. 환불은 결제가 이루어진 계정(데모 또는 라이브)으로, 결제 통화로 전송되므로 해당 계정의 Client ID와 Client Secret을 입력해야 합니다. Viva가 환불을 거부하면 WooCommerce에 오류가 표시되고 환불은 기록되지 않습니다. 환불이 성공하면 Viva 환불 거래와 함께 주문 메모에 추가됩니다.

Viva 대시보드에서 이루어진 환불은 가져오지 않습니다. 필요하면 Refund via Viva Wallet을 사용하지 않고 WooCommerce에서 수동 환불을 만드세요.

라이선스 키

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

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

활성 키가 없으면 Viva Wallet은 체크아웃에서 고객에게 표시되지 않습니다. 그래도 결제가 시작되면 고객에게 This payment method is not available. Please choose another one.가 표시됩니다. 로그인한 쇼핑몰 관리자에게는 결제 수단이 (unlicensed — visible to admins only)로 표시되어 계속 보이므로, 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 페이지와 WooCommerce 페이지에 알림이 표시됩니다. 기존 주문은 영향을 받지 않습니다. 이미 시작된 결제는 계속 확인되고, 환불도 정상적으로 작동합니다.

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

문제 해결

Viva Wallet이 체크아웃에 표시되지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 Client ID, Client Secret, Source Code가 있는지 확인하세요(테스트 모드에서는 Demo 항목, 라이브 모드에서는 Live 항목). 쇼핑몰 통화(Pay for order 페이지에서는 주문 통화)는 EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK 또는 CHF 중 하나여야 합니다. 빠진 항목이 있으면 설정 페이지에 경고가 표시됩니다.

결제는 완료되었지만 주문이 Pending payment 상태에 머묾: 웹훅이 작동하지 않습니다. Viva에서 사용 중인 계정(데모 또는 라이브)에 웹훅이 있는지, URL이 설정에 표시된 것과 정확히 같은지, Transaction Payment Created가 선택되어 있는지 확인하세요. 해당 결제 계정의 Client ID와 Client Secret이 여전히 입력되어 있는지도 확인하세요. 플러그인이 결제를 확인하려면 이 값이 필요합니다. 자세한 내용은 WooCommerce > Status > Logs(소스: wcp_viva_gateway)에 있습니다.

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로 응답합니다.

고객이 주문할 때 오류가 보임: Debug Logging을 켜고 WooCommerce > Status > Logs(소스: wcp_viva_gateway)를 확인하세요. 잘못된 Client ID 또는 Client Secret이나 누락된 Source Code는 Viva Wallet 결제를 사용할 수 없다는 메시지로 이어집니다. Viva에 연결할 수 없거나 Viva가 결제 주문을 거부하면(예: Source Code가 다른 계정 소속인 경우), 고객에게는 쇼핑몰이 Viva Wallet에 연결하지 못했다는 메시지가 표시됩니다.

결제 후 주문이 On hold 상태임: 주문 메모를 읽으세요. 결제된 금액이나 통화가 주문과 달랐습니다. 주문을 완료하거나 결제를 환불하세요.

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

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

개발자용: viva_wp_supported_currencies 필터는 Viva 계정에서 지원하는 추가 통화를 활성화합니다. viva_wp_create_order_payload는 결제 주문 요청을 변경합니다(금액, 통화, Source Code는 그대로 유지해야 합니다). viva_wp_icon은 체크아웃 아이콘을 변경합니다.

제거

플러그인을 비활성화해도 모든 데이터는 유지되며, 캐시된 Viva 액세스 토큰만 제거됩니다. 완전히 제거하려면 플러그인을 비활성화한 뒤 Plugins 페이지에서 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태, 캐시된 토큰과 웹훅 키는 항상 제거됩니다. 설정, 결제 시도 테이블, 플러그인 로그(순환된 로그 파일과 데이터베이스 로그 항목 포함)는 Delete Data on Uninstall이 켜져 있을 때만 제거됩니다. 그렇지 않으면 나중에 다시 설치할 때를 위해 유지됩니다. 기존 주문은 결제 메모와 거래 ID를 유지합니다.

Viva Wallet은 해당 소유자의 상표입니다. 이 플러그인은 Viva Wallet과 제휴하거나 Viva Wallet의 승인을 받지 않았습니다.