VibeFox PayU for OpenCart — 도움말

요구 사항

OpenCart: 3.0.x(3.0.5.0에서 테스트됨) 또는 4.0.2 이상(4.1.0.3에서 테스트됨).

PHP: 8.0 이상, cURL 확장 포함.

통화: 고객의 결제 통화는 PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH 중 하나여야 합니다. 이 통화는 PayU에서 사용하는 판매 지점(POS)에서도 활성화되어 있어야 합니다. 그 밖의 통화에서는 체크아웃에 이 결제 수단이 표시되지 않습니다.

쇼핑몰의 인터넷 접근: PayU는 결제 알림을 쇼핑몰로 보내므로, 쇼핑몰은 인터넷에서 접근 가능해야 합니다(HTTP 인증 뒤나 방화벽 뒤에 있으면 안 됩니다). 알림이 없어도 고객이 PayU에서 돌아오면 결제 상태를 확인합니다.

PayU 계정: 판매 지점(POS)의 키 네 개가 필요합니다: POS ID, Second key (MD5), OAuth client_id, OAuth client_secret. 이 키는 PayU 가맹점 관리 패널의 Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys에 있습니다. 샌드박스 키는 별도의 PayU 샌드박스 계정에서 발급됩니다.

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

설치

다운로드 파일은 두 OpenCart 버전용 패키지가 들어 있는 하나의 zip 파일입니다. 컴퓨터에서 압축을 푸세요. 여기에는 README.txt, OpenCart 3 패키지 wcp_payu_payment-oc3-(version).ocmod.zip, OpenCart 4 패키지 wcp_payu_payment.ocmod.zip이 들어 있습니다. 사용 중인 OpenCart 버전의 패키지만 설치하세요. 라이선스 키는 두 버전에서 같습니다.

OpenCart 3

1. 관리자 화면에서 Extensions > Installer로 이동하여 Upload를 클릭하고 wcp_payu_payment-oc3-(version).ocmod.zip 파일을 선택합니다. 이 확장 기능은 OCMOD 수정 사항이 없으므로 Extensions > Modifications를 새로 고칠 필요가 없습니다. 설치 도구 대신, 이 패키지의 upload 폴더 내용을 쇼핑몰의 루트 폴더에 복사할 수도 있습니다.

2. Extensions > Extensions로 이동하여 유형으로 Payments를 선택합니다. VibeFox PayU Payment를 찾아 Install(초록색 + 버튼)을 클릭합니다. 관리자 사용자에게 결제 확장 기능 목록을 수정할 권한이 있어야 합니다.

3. Edit(연필 버튼)을 클릭하여 설정 페이지를 엽니다. 페이지 상단의 라이선스 블록에 있는 License key에 VibeFox 라이선스 키를 붙여 넣고 Activate를 클릭합니다(라이선스 키 참조).

4. Sandbox 키 네 개와 Live 키 네 개를 입력합니다(설정 참조). PayU에서 알림 URL을 설정할 필요는 없습니다.

5. Enable/Disable을 켜고 Save를 클릭합니다. 테스트 결제를 완료하기 전까지는 Test Mode를 켜 둔 상태로 두고, 이후 Live 키로 실제 결제를 받으려면 끕니다.

OpenCart 4

1. 관리자 화면에서 Extensions > Installer로 이동하여 Upload를 클릭하고 wcp_payu_payment.ocmod.zip 파일을 선택합니다. 파일 이름을 바꾸지 마세요. OpenCart 4는 파일 이름에서 확장 기능 코드를 가져오므로, 이름을 바꾼 패키지는 작동하지 않습니다.

2. 설치된 확장 기능 목록의 같은 페이지에 패키지가 표시됩니다. 그 옆의 Install(초록색 + 버튼)을 클릭합니다.

3. Extensions > Extensions로 이동하여 유형으로 Payments를 선택합니다. VibeFox PayU Payment를 찾아 Install(초록색 + 버튼)을 클릭한 다음 Edit(연필 버튼)을 클릭합니다.

4. OpenCart 3의 3~5단계와 같이 라이선스 키와 PayU 키를 입력합니다. 설정 페이지와 입력란은 두 버전에서 같습니다. 알림 URL만 다릅니다(「결제 알림」 참조).

새로 설치하면 결제 수단은 꺼진 상태이며 테스트 모드가 켜져 있습니다.

설정

모든 설정은 확장 기능 페이지에 있습니다: Extensions > Extensions > Payments > VibeFox PayU Payment > Edit. 섹션은 왼쪽에 나열되며, 목록 아래의 Save 버튼은 페이지 전체를 저장합니다. 설정 위쪽에서는 샌드박스 모드가 켜져 있을 때(샌드박스(테스트) 모드가 켜져 있습니다. 결제는 PayU 샌드박스로 전달되며 실제 금액은 청구되지 않습니다. 테스트 모드로 결제된 주문은 발송하지 마세요.), 현재 모드의 키 네 개 중 하나가 없을 때(이 경우 체크아웃에서 PayU가 표시되지 않음), 그리고 PayU가 쇼핑몰의 기본 통화를 허용하지 않을 때(이 경우 해당 통화의 주문에서 PayU가 숨겨짐) 페이지가 경고합니다. 확장 기능을 수정할 권한이 없으면 페이지에 설정은 표시되지만 저장할 수 없습니다.

저장하면 모든 키에서 공백과 줄 바꿈이 제거됩니다. PayU 패널에서 복사할 때 자주 들어가기 때문입니다. Title은 비워 둘 수 없으며 128자를 넘을 수 없습니다(페이지에 Enter a title for the payment method (at most 128 characters).가 표시됩니다). Sort Order는 정수여야 합니다(음수 허용). Total은 0 이상의 숫자여야 하며, 지역(Geo Zone)과 주문 상태가 존재해야 합니다. 그렇지 않으면 아무것도 저장되지 않습니다. 설정을 저장하면 캐시된 PayU 액세스 토큰도 삭제됩니다.

PayU

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

Title: 고객이 체크아웃에서 보는 결제 수단 이름입니다. 주문에 저장되는 결제 수단 이름이기도 합니다. 기본값: PayU. 필수, 최대 128자.

Description: Confirm Order 단계에서 확인 버튼 위에 고객에게 표시되는 텍스트입니다. 기본값: Pay securely via PayU.

Sort Order: 체크아웃에서 결제 수단 목록 안의 PayU 위치입니다. 비워 두거나 정수를 입력합니다.

Geo Zone: 선택한 지역 내의 결제 주소에 대해서만 PayU를 제공합니다. 기본값: All zones. 지역은 System > Localisation > Geo Zones에서 설정합니다.

Total: PayU를 제공하기 위해 주문이 도달해야 하는, 쇼핑몰 기본 통화 기준의 체크아웃 합계입니다. 비워 두면 모든 금액에 대해 PayU를 제공합니다.

API 자격 증명

키는 PayU 가맹점 관리 패널에서 찾을 수 있습니다: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. 샌드박스 키는 별도의 PayU 샌드박스 계정에서 발급됩니다. 한 모드의 키 네 개를 모두 입력해야 합니다. 이 섹션에는 PayU 개발자 문서로 연결되는 링크가 있습니다.

Test Mode: PayU 샌드박스와 아래의 Sandbox 키를 사용합니다. 실제 금액은 청구되지 않습니다. 켜져 있는 동안 고객은 Confirm Order 단계에서 샌드박스 모드: 실제 결제가 이루어지지 않습니다.를 봅니다. Live 키로 실제 결제를 받으려면 끄세요. 기본값: 켜짐.

Live POS ID: 운영 판매 지점의 POS ID(merchantPosId)입니다.

Live Second Key (MD5): PayU 알림의 서명을 검증하는 데 사용됩니다.

Live OAuth Client ID: 판매 지점의 OAuth client_id입니다.

Live OAuth Client Secret: 판매 지점의 OAuth client_secret입니다.

Sandbox POS ID: PayU 샌드박스 판매 지점의 POS ID입니다.

Sandbox Second Key (MD5): PayU 샌드박스 알림의 서명을 검증하는 데 사용됩니다.

Sandbox OAuth Client ID: 샌드박스 판매 지점의 OAuth client_id입니다.

Sandbox OAuth Client Secret: 샌드박스 판매 지점의 OAuth client_secret입니다.

저장된 Second Key와 client secret은 다시 표시되지 않습니다. 필드는 비어 있으며 저장됨 — 유지하려면 비워 두세요.라고 표시됩니다. 값을 바꾸려는 경우에만 새 값을 입력하세요. POS ID와 client ID는 저장된 대로 표시됩니다.

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

모든 결제는 자신의 환경을 기억합니다. 알림, 상태 확인, 결제 수령 또는 취소, 환불은 항상 해당 환경의 키를 사용하므로, 모드를 전환한 뒤에도 이전 결제는 계속 작동합니다. 샌드박스 키로 서명된 알림은 실제 결제에 절대 허용되지 않으며, 그 반대도 마찬가지입니다.

주문 상태

OpenCart는 Confirm Order 단계에서 상태 없이 주문(누락된 주문)을 만듭니다. 주문은 PayU가 서명된 알림으로 결제를 확인하거나, 고객이 돌아올 때 상태 확인으로 결제를 확인한 후에야 상태를 받습니다. OpenCart에는 On hold 상태가 없으므로 대기 상태는 기본적으로 Pending이 되며, 주문의 PayU 탭과 메모에 이유가 설명됩니다. 아래의 각 필드에는 OpenCart 주문 상태가 나열됩니다. 직접 만든 상태는 System > Localisation > Order Statuses에서 만들 수 있습니다.

Order Status After Payment: PayU가 결제를 확인하고(COMPLETED) 금액과 통화가 일치할 때 설정됩니다. 기본값: Processing.

Awaiting PayU Payment Confirmation: 결제가 승인되었으며 수령을 기다립니다(자동 수령이 꺼졌거나 실패함). 주문의 PayU 탭에서 Receive PayU payment 또는 Cancel PayU payment를 사용합니다. 기본값: Pending.

PayU Payment On Hold: 결제된 금액이나 통화가 주문과 일치하지 않거나, 취소된 주문에 대해 결제가 완료되었습니다. 주문은 결제 완료로 표시되지 않으며, 메모에 이유가 나타납니다. 기본값: Pending.

Payment Error Status: 확인을 기다리던 주문의 결제가 취소되었거나 거부되었습니다. 기본값: Failed.

Cancelled Order Status: 이 상태의 주문에 대해 PayU 결제가 완료되면, 주문을 조용히 다시 열지 않고 보류 상태로 둡니다. 이 확장 기능은 이 상태를 설정하지 않습니다. 기본값: Canceled.

Refunded Status: 주문의 PayU 탭에서 결제 금액 전액을 환불한 뒤 설정됩니다. 기본값: Refunded.

결제 알림

Notification URL: PayU가 알림을 보내는 주소를 보여 줍니다. OpenCart 3에서는 https://your-store/index.php?route=extension/payment/wcp_payu_payment/notify 형태이고, OpenCart 4에서는 https://your-store/index.php?route=extension/wcp_payu_payment/payment/wcp_payu_payment.notify 형태입니다. URL은 OpenCart 설치의 스토어 프런트 주소로부터 만들어집니다. 확장 기능은 결제마다 이 주소를 PayU에 보내므로, PayU 패널에서 따로 설정할 것은 없습니다. 인터넷에서 접근 가능한지 확인하세요(방화벽이나 HTTP 인증에 의해 차단되지 않아야 합니다). 쇼핑몰이 유지 보수 모드에 있을 때도 알림은 작동합니다(OpenCart 4에서는 확장 기능의 시작 액션을 통해 작동하며, 이를 통해 고객이 PayU에서 돌아오는 것도 허용됩니다). 유효한 서명이 없는 알림은 거부됩니다.

고급

Receive payments automatically: 확인을 기다리는 결제를 자동으로 수령합니다. 이 옵션은 PayU 패널에서 판매 지점의 자동 수령이 꺼져 있을 때만 의미가 있습니다. 그 경우 결제는 확인을 기다립니다(WAITING_FOR_CONFIRMATION). 이 옵션이 켜져 있으면 확장 기능이 이러한 결제를 즉시 수령하고, PayU가 결제 완료를 알리면 주문이 결제 완료 상태를 받습니다. 옵션이 꺼져 있거나 수령에 실패하면 주문은 Awaiting PayU Payment Confirmation을 받으며, 주문의 PayU 탭에 있는 버튼으로 결제를 수령하거나 취소합니다. 기본값: 켜짐.

Logging: 기술적인 이벤트(주문 번호, PayU 주문 ID, 상태, 오류; 키나 개인 정보는 제외)를 OpenCart 로그 폴더(storage/logs)의 wc_pu_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류는 항상 기록되며, 다른 이벤트는 이 옵션이 켜져 있는 동안에만 기록됩니다. 기본값: 꺼짐.

Log: 로그의 크기와 최신 항목을 보여 줍니다. Clear log를 클릭하면 로그가 비워집니다.

Delete data on uninstall: 켜져 있으면 확장 기능을 제거할 때 게이트웨이 설정과 로그가 삭제됩니다. 주문과 결제 데이터(PayU 거래 및 환불)는 절대 삭제되지 않습니다. 캐시된 PayU 액세스 토큰은 항상 삭제됩니다. 기본값: 꺼짐.

가져오기 / 내보내기

Export: Download JSON은 설정을 JSON 파일로 저장합니다. 비밀 값은 내보내지 않습니다.

Import: 이전에 내보낸 JSON을 붙여 넣고 Import를 클릭하면 설정이 복원됩니다. 저장된 비밀 값은 유지됩니다.

체크아웃

Payment Method 단계에서 고객은 결제 수단을 선택합니다(기본값은 PayU). Confirm Order 단계에서 고객은 쇼핑몰의 설명과 BLIK, 계좌이체, 카드 등 기타 수단을 통해 결제를 완료하도록 PayU로 이동합니다. 안내를 봅니다. OpenCart는 이 단계에서 아직 상태가 없는 주문을 만듭니다. OpenCart 4에서는 고객이 결제 수단 블록의 Choose 버튼을 눌러 Payment method options 창에서 결제 수단을 선택하고, 체크아웃 페이지 하단의 Confirm Order를 클릭합니다. 고객이 Confirm Order를 클릭하면 확장 기능은 주문 통화로 주문 합계에 대한 PayU 주문을 만듭니다. 설명에는 Order #, 주문 번호, 쇼핑몰 이름이 포함되며, PayU 페이지에 표시하기 위해 상품, 배송 방법, 주문의 다른 합계 행도 함께 전달됩니다. 고객의 이메일, 이름, 전화번호는 PayU로 전달되며, PayU 페이지의 언어는 스토어 프런트의 언어를 따릅니다. 고객은 PayU 페이지로 이동하여 그곳에서 결제 방법을 선택하고 결제합니다.

시도마다 자체 PayU 주문이 생성됩니다. 고객이 다시 시도하면(OpenCart 3에서는 Confirm Order 단계가 표시될 때마다 새 주문을 만들고, OpenCart 4에서는 체크아웃의 주문을 업데이트합니다), 같은 주문과 장바구니의 이전 시도에서 완료되지 않은 PayU 결제가 PayU에서 취소되므로, 오래된 결제 링크로 두 번 결제할 수 없습니다. 이전 결제가 이미 완료된 것으로 확인되면 그 결제가 대신 적용되며, 이미 결제되었거나 PayU 대기 중이거나 확인 대기 중인 주문 또는 장바구니는 두 번째 결제 없이 바로 성공 페이지로 이동합니다. 장바구니를 변경하면(수량 변경 포함) 새 장바구니로 간주되며, 자체 결제가 필요합니다.

고객이 쇼핑몰로 돌아오는 것만으로는 주문이 결제되지 않습니다. 주문은 PayU가 확인한 후에만 결제 완료로 표시됩니다. 결제 환경의 Second Key로 서명된 알림을 받거나, 고객이 돌아올 때 서버에서 PayU 주문의 상태를 확인하는 방식입니다(결제당 최대 10초에 한 번). 금액과 통화가 일치해야 합니다. 그런 다음 주문은 OpenCart의 표준 방식으로 상태를 받으며, 일반 주문 이메일이 발송되고 재고가 업데이트됩니다. 확장 기능은 다음 PayU 상태를 처리합니다:

결제가 확인된 후 고객은 OpenCart 주문 성공 페이지를 봅니다. 확인을 기다리거나 보류 중인 주문의 경우 페이지에 결제를 확인하고 있습니다. 확인되는 즉시 이메일로 알려 드리겠습니다.가 추가로 표시됩니다. 이후 이러한 주문이 결제되거나 결제가 실패하면, OpenCart는 고객에게 새 상태를 알립니다. 주문의 결제가 실패했다면 페이지에 PayU 결제가 완료되지 않았습니다. 이 주문에 대해 문의해 주세요.가 표시됩니다.

고객이 돌아온 시점에 PayU가 아직 결제를 확인하지 않았다면, Payment confirmation 페이지에 PayU로부터 아직 결제 확인을 받지 못했습니다. 결제가 중단되었다면 다시 시도할 수 있습니다:(또는 PayU가 오류를 보고했다면 결제가 완료되지 않았습니다. 다시 시도할 수 있습니다:)가 표시되고, Pay again(체크아웃으로 돌아가기) 및 Check again 버튼이 나타납니다. 알림이 도착하면 즉시 주문 상태가 설정됩니다. 결제가 취소되었다면 고객은 결제가 완료되지 않았습니다. 다시 시도하거나 다른 결제 수단을 선택할 수 있습니다.가 표시된 체크아웃으로 돌아갑니다. 장바구니는 유지됩니다. OpenCart 4에서는 이 메시지가 체크아웃 페이지 상단에 표시됩니다.

OpenCart 4는 성공 페이지가 표시될 때까지 주문을 체크아웃에 유지합니다. 그 사이에 결제 없이 주문이 닫힌 경우(예: 확인 대기 중인 결제가 취소되었거나 주문을 취소하거나 환불한 경우), 고객은 Your previous order was closed (not paid, cancelled or refunded). Please confirm the order again to pay with a new order. 메시지와 함께 체크아웃으로 돌아갑니다. 결제 없이 닫힌 주문에 대해 고객이 PayU에서 돌아온 경우, 메시지는 The payment was not completed. You can try again or choose another payment method.입니다. 그 주문이 이전 장바구니에 대해 이미 결제되었고 그 후 장바구니가 변경된 경우, 고객은 체크아웃으로 돌아갑니다. 어느 경우든 다음 Confirm Order에서 현재 장바구니의 새 주문에 대한 결제가 이루어집니다. 닫힌 주문은 결제 완료된 것으로 표시되지 않습니다.

PayU가 결제를 시작할 수 없으면 고객은 Confirm Order 단계에 머물며 결제 오류입니다. 다시 시도하거나 다른 결제 수단을 선택해 주세요.를 봅니다. 기술적인 이유는 로그에 기록됩니다. 현재 모드의 키가 없으면 메시지는 결제 게이트웨이가 올바르게 설정되지 않았습니다. 관리자에게 문의해 주세요.입니다.

고객은 쇼핑몰의 체크아웃이 아니라 PayU 페이지에서 결제 수단을 선택합니다. 이 확장 기능은 쇼핑몰에 카드 입력 양식을 제공하지 않으며, 저장된 카드나 원클릭 결제, 정기 결제, PayU 할부 또는 신용 위젯을 제공하지 않습니다. 환경마다 하나의 판매 지점을 사용합니다.

주문 및 환불

주문 상태

상태 없음(누락된 주문): 고객이 PayU로 이동했으나 결제하지 않았거나, 결제가 취소되었거나, PayU가 아직 결제를 확인하지 않았습니다. Sales > Orders에서 이러한 주문은 Order Status 필터를 Missing Orders로 설정했을 때만 표시됩니다.

Order Status After Payment(기본값 Processing): 결제가 확인되었습니다. 메모에는 PayU 주문 ID, 금액, 환경(샌드박스 또는 운영)이 표시됩니다.

Awaiting PayU Payment Confirmation(기본값 Pending): 결제가 승인되었으며 관리자의 처리를 기다립니다(자동 수령이 꺼졌거나 수령에 실패함).

PayU Payment On Hold(기본값 Pending): 결제된 금액이나 통화가 주문과 일치하지 않았거나, 확인을 기다리던 결제의 금액이 달랐거나, 취소된 주문에 대해 결제가 완료되었습니다. 메모에 어떤 경우인지 나타납니다. 주문을 확인하고 처리하거나 결제를 환불하세요.

Payment Error Status(기본값 Failed): 확인을 기다리던 주문의 결제가 취소되었거나 거부되었습니다.

Refunded Status(기본값 Refunded): 결제 금액이 확장 기능을 통해 전액 환불되었습니다.

모든 알림은 한 번만 처리됩니다. 같은 알림이 반복되어도 메모가 추가되거나 주문이 다시 변경되지 않습니다. 이미 결제되었거나 환불된 주문에 대해 다른 결제가 완료되었거나, 이미 결제된 장바구니의 다른 주문에 대해 결제가 완료되면, 결제된 주문의 메모에서 PayU 패널을 통해 환불하라고 안내합니다. 이미 결제되었거나 종료된 주문에 대한 확인 대기 결제는 자동으로 취소되므로 돈이 두 번 청구되지 않습니다.

메모는 주문의 History에 있는 항목이며, 고객에게는 보이지 않습니다.

VibeFox PayU Payment 탭

Sales > Orders에서 PayU로 결제된 주문을 엽니다. 주문 페이지 하단, History와 Additional 옆의 VibeFox PayU Payment 탭에는 PayU order ID(샌드박스 결제에는 Sandbox 표시 포함), extOrderId, PayU status, Payment amount, Paid / refunded 금액, 환불 양식, Refunds 기록, 주문의 PayU payment attempts, 그리고 PayU notes가 표시됩니다. 이 탭은 확장 기능에 접근 권한이 있는 사용자에게 표시되며, 탭의 작업에는 확장 기능을 수정할 권한이 필요합니다(System > Users > User Groups에서 설정).

확인 대기 중인 결제

확인을 기다리는 결제가 있는 주문의 경우, 탭에 Receive PayU payment와 Cancel PayU payment가 표시됩니다. 질문을 확인하면 해당 작업이 결제 환경의 키를 사용하여 PayU로 전송되고, 사용자 이름과 함께 메모에 추가되며, 새 PayU 상태가 즉시 적용됩니다. 수령한 결제는 Order Status After Payment를, 취소한 결제는 Payment Error Status를 설정합니다.

환불

탭에서 Amount(아직 환불되지 않은 금액이 자동으로 채워짐)를 입력하고, 필요하면 Reason (optional)을 입력한 뒤 Refund via PayU를 클릭합니다. Refund this amount through PayU? This cannot be undone. 질문을 확인하세요. 전액 및 부분 환불을 지원합니다. 환불은 PayU가 결제를 완료한 후 가능합니다. 환불은 실제로 결제된 PayU 주문에 대해, 결제 환경의 키로 전송되므로 해당 키가 설정되어 있어야 합니다. 환불은 PayU가 청구한 금액과 통화로 이루어지므로, 금액이나 통화가 일치하지 않은 경우에는 주문 합계가 아니라 고객이 실제로 지불한 금액까지만 환불할 수 있습니다. 사유는 환불 설명으로 전송됩니다. PayU가 환불을 거부하면 탭에 PayU의 오류가 표시되며 환불은 기록되지 않습니다. 전액 환불을 하면 주문이 Refunded Status로 설정되며, 고객에게 알리지 않고 상품도 재고로 되돌리지 않습니다. 부분 환불은 상태를 바꾸지 않습니다.

PayU의 환불은 비동기로 처리됩니다. 확장 기능은 PayU 환불 ID와 상태가 담긴 메모를 즉시 추가합니다. 최종 상태는 나중에 PayU 알림으로 도착하며, 메모와 환불 기록에 추가됩니다. PayU가 환불을 취소하면 메모에 고객에게 돈이 돌아가지 않았다고 표시되며, 해당 금액은 다시 환불할 수 있습니다.

Sales > Returns의 상품 반품은 PayU를 통해 돈을 돌려주지 않습니다.

라이선스 키

이 확장 기능은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. License — VibeFox PayU Payment 라이선스 블록은 Extensions > Extensions > Payments > VibeFox PayU Payment > Edit의 첫 번째 블록이며, 설정 위에 있습니다. 키를 License key에 붙여 넣고 Activate를 클릭합니다. 그 후 블록에는 마스킹된 키, 상태(예: 라이선스 유효 기간 종료일과 도메인), 그리고 다음 버튼이 표시됩니다: 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key. 그 아래에는 Product: opencart-payment-payu 줄과, vibefox.net 계정을 여는 Manage licenses and domains in your account 링크가 있습니다. 키를 변경할 수 있는 사람은 이 확장 기능의 Modify 권한이 있는 관리자 사용자뿐입니다. 블록의 텍스트는 관리자 화면의 언어를 따릅니다(영어와 러시아어 포함).

키가 받아들여지지 않으면 블록에 이유가 표시됩니다. 예: Key not found, This key belongs to another product, Domain limit reached, 또는 날짜가 붙은 License expired on. 쇼핑몰 주소가 바뀐 후, 또는 계정에서 도메인 슬롯을 해제한 후에는 Check now를 클릭하세요. 라이선스 서버에 연결할 수 없으면 확장 기능은 마지막으로 확인된 상태로 계속 작동합니다.

키 하나는 도메인 하나에서 작동합니다. 즉, OpenCart 설정의 쇼핑몰 주소입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하세요.

유효한 키가 없으면 체크아웃에서 PayU가 고객에게 표시되지 않습니다. 그래도 결제가 시작되면 고객은 This payment method is not available. Please choose another one.를 봅니다. 같은 브라우저에서 관리자 화면에 로그인한 관리자 사용자에게는 쇼핑몰에서 결제 수단이 (unlicensed — visible to admins only) 표시와 함께 계속 보이므로, 키를 구매하기 전에 확장 기능을 설정하고 테스트할 수 있습니다. OpenCart 4에서는 이 미리보기를 사용할 수 없습니다. 스토어는 관리자 로그인을 확인하지 않으므로, 활성 키가 없으면 결제 수단은 모든 사용자에게 숨겨집니다. Edit 페이지를 한 번 열면 관리자 Dashboard에 알림이 나타납니다. ×로 닫으면 7일 동안 숨겨집니다. 기존 주문에는 영향이 없습니다. 이미 시작된 결제는 여전히 알림으로 확인되며, 환불도 작동합니다.

라이선스가 만료되어도 확장 기능은 계속 작동하지만, 업데이트와 지원에는 갱신이 필요합니다. 관리자 Dashboard 또는 Edit 페이지를 열면 상태가 자동으로 다시 확인됩니다. 키를 입력한 후 처음 14일 동안은 하루에 한 번, 그 후에는 일주일에 한 번 확인합니다. cron 작업은 필요하지 않습니다. 확장 기능을 제거하면 라이선스 키와 라이선스 상태는 항상 삭제됩니다.

문제 해결

PayU가 체크아웃에 표시되지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 그리고 현재 모드의 키 네 개가 모두 입력되었는지 확인하세요. 샌드박스 모드에서는 Sandbox 키, 라이브 모드에서는 Live 키입니다. 고객의 통화가 지원되는 통화인지, 결제 주소가 선택된 Geo Zone에 속하는지, 주문이 설정의 Total에 도달했는지 확인하세요. 설정 페이지는 키가 없거나 쇼핑몰 통화가 지원되지 않을 때 경고를 표시합니다.

결제는 완료되었지만 주문에 상태가 없음: PayU가 아직 알림을 전달하지 않았고, 반환 페이지의 상태 확인에서도 완료된 결제를 찾지 못했습니다. 설정에 표시된 알림 URL이 인터넷에서 접근 가능한지 확인하세요. Logging을 켜면 무엇이 수신되는지 볼 수 있습니다. 고객은 Payment confirmation 페이지에서 Check again을 클릭할 수도 있습니다.

알림이 Invalid signature로 응답함: 알림이 두 환경 중 어느 쪽의 Second Key로도 서명되지 않았습니다. Live Second Key (MD5)와 Sandbox Second Key (MD5)를 확인하세요. Invalid signature for this payment 응답은 알림이 결제 환경과 다른 환경의 키로 서명되었다는 뜻입니다.

알림이 Ignored: unknown PayU order로 응답함: 이 PayU 주문은 이 쇼핑몰이 만든 것이 아닙니다. 예를 들어 같은 판매 지점을 쓰는 다른 쇼핑몰입니다. PayU는 재시도를 중단합니다.

알림이 Busy, retry later로 응답함: 같은 순간에 다른 요청이 장바구니를 확인하고 있었습니다. PayU가 알림을 반복합니다. 이유를 보려면 Logging을 켜세요.

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

고객이 Confirm Order 후 Payment error를 봄: Logging을 켜고 확장 기능 페이지의 Log 필드를 확인하세요. 로그에는 HTTP 코드와 PayU 상태가 표시됩니다. Could not authenticate with PayU (check the OAuth client ID / secret).는 현재 모드의 OAuth 키가 잘못되었다는 뜻입니다. This payment method is not available.는 체크아웃 세션이 더 이상 주문과 일치하지 않거나, 그 사이 결제 수단이 꺼졌다는 뜻입니다. 고객은 체크아웃을 새로 고쳐야 합니다.

주문이 PayU Payment On Hold 상태임: VibeFox PayU Payment 탭의 메모를 읽고(주문 상태 참조), 주문을 처리하거나 결제를 환불하세요.

주문이 Awaiting PayU Payment Confirmation 상태임: 판매 지점의 자동 수령이 꺼져 있어서 결제가 관리자의 처리를 기다리고 있습니다. 탭에서 Receive PayU payment 또는 Cancel PayU payment를 사용하세요.

환불이 실패하거나 환불 양식이 없음: 탭에 이유가 표시됩니다. Refunds are available once PayU has completed the payment.는 PayU가 아직 주문의 결제를 완료하지 않았다는 뜻입니다. Sandbox 키 또는 Live 키가 없다는 메시지는 결제가 그 환경에서 이루어졌지만 해당 키가 설정되지 않았다는 뜻입니다. 키를 입력하고 다시 시도하세요. 확장 기능을 수정할 권한이 없으면 탭에 You do not have permission to refund (modify this extension).가 표시됩니다.

제거

Extensions > Extensions로 이동하여 유형으로 Payments를 선택하고, VibeFox PayU Payment 옆의 Uninstall(빨간색 − 버튼)을 클릭합니다. 이 확장 기능의 라이선스 키와 라이선스 상태는 항상 제거됩니다. OpenCart는 확장 기능 자체의 설정을 항상 제거합니다: Enable/Disable, Sort Order, Geo Zone, Total, 그리고 Order statuses 섹션의 주문 상태(재설치 시 기본값으로 돌아감). 확장 기능의 OpenCart 이벤트와 캐시된 PayU 액세스 토큰도 제거됩니다(OpenCart 4에서는 이벤트와 시작 액션도 제거되며, 시작 액션은 유지 보수 모드에서도 알림과 고객의 복귀를 허용합니다). Delete data on uninstall이 켜져 있으면 나머지 게이트웨이 설정(제목, 설명, 테스트 모드, 키, 자동 수령, 로깅)과 로그가 삭제됩니다. 꺼져 있으면 나중에 재설치할 때를 위해 보관됩니다. PayU 거래와 환불은 항상 보관되므로, 재설치 후에도 이전에 결제된 주문을 환불할 수 있습니다. 기존 주문은 결제 메모를 유지합니다.

OpenCart 4에서 확장 기능 파일까지 제거하려면, 제거 후 Extensions > Installer로 이동하여 설치된 확장 기능 목록에서 VibeFox PayU Payment 옆의 Uninstall(주황색 − 버튼)을 클릭한 다음, 업로드한 패키지를 삭제하려면 Delete(빨간색 휴지통 버튼)를 클릭합니다.

PayU는 해당 소유자의 상표입니다. 이 확장 기능은 PayU와 제휴하거나 PayU의 승인을 받은 것이 아닙니다.