VibeFox PayU for WooCommerce — 도움말

요구 사항

WordPress: 5.8 이상.

WooCommerce: 7.0 이상(설치 및 활성화 필수). WooCommerce가 없으면 플러그인이 활성화되지 않으며, 나중에 WooCommerce를 비활성화하면 플러그인이 작동하지 않고 관리자 영역에 알림이 표시됩니다.

PHP: 8.0 이상.

상점 통화: PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH 중 하나. 해당 통화는 PayU의 판매 시점에서도 활성화되어 있어야 합니다. 다른 통화의 경우 체크아웃에서 결제 수단이 숨겨집니다.

사이트 인터넷 접근: 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에서 구매. 키 하나는 도메인 하나에서 작동합니다.

설치

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

2. Activate를 클릭하세요.

3. 설정을 엽니다: WooCommerce > Settings > Payments > PayU > Manage를 열거나 플러그인 페이지의 플러그인 이름 아래에서 Settings를 클릭하세요.

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

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

6. Enable/Disable을 켜세요. 테스트 결제를 진행할 때까지 Test Mode를 켜 둔 후, Live 키로 실제 결제를 받으려면 체크를 해제하세요.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > PayU. 샌드박스 모드가 켜져 있는 동안, 현재 모드의 4개 키 중 하나가 누락되었거나 PayU가 상점 통화를 지원하지 않는 경우 필드 상단에 경고가 표시됩니다. 후자의 두 경우 PayU는 체크아웃에 표시되지 않습니다.

저장할 때 모든 키에서 공백과 줄 바꿈이 자동으로 제거됩니다. PayU 패널에서 복사할 때 자주 포함되기 때문입니다.

일반

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

Title: 고객에게 표시되는 결제 수단 제목입니다. 기본값: PayU.

Description: 고객에게 표시되는 결제 수단 설명입니다. 기본값: Pay securely via PayU.

API 자격 증명

PayU 가맹점 패널에서 키를 찾으세요: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. 샌드박스 키는 별도의 PayU 샌드박스 계정에서 가져옵니다. 한 모드의 4개 키를 모두 입력해야 합니다.

Test Mode: Enable sandbox (test) mode. PayU 샌드박스와 아래의 Sandbox 키를 사용합니다. 실제 금액은 청구되지 않습니다. 클래식 체크아웃과 체크아웃 블록에서 고객에게 Sandbox mode — no real money is charged가 표시됩니다. 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입니다.

모든 결제는 해당 환경을 기억합니다. 결제의 알림, 상태 확인 및 환불은 항상 해당 환경의 키를 사용하므로 모드를 전환한 후에도 이전 결제가 계속 작동합니다. 샌드박스 키로 서명된 알림은 실제 결제에 절대 허용되지 않습니다.

결제 알림

이 섹션에는 https://your-site/wc-api/wc_pu_payment/ 형태의 알림 URL이 표시됩니다. 플러그인이 모든 결제마다 이를 PayU로 전송하므로 PayU 패널에서 설정할 필요가 없습니다. 인터넷에서 접근 가능한지 확인하세요(방화벽, 유지보수 모드 또는 HTTP 인증으로 차단되지 않아야 함).

고급

Receive payments automatically: Automatically receive payments waiting for confirmation. 이 설정은 PayU 패널에서 해당 POS의 자동 수취가 꺼져 있는 경우에만 유효합니다. 결제가 확인 대기(WAITING_FOR_CONFIRMATION) 상태가 됩니다. 이 옵션이 켜져 있으면 플러그인이 이러한 결제를 즉시 수취합니다. 꺼져 있으면 해당 주문은 보류 상태가 되며, 주문 작업 Receive PayU payment 및 Cancel PayU payment로 결제를 수취하거나 취소합니다. 기본값: 켜짐.

Logging: Enable logging은 기술적 이벤트(주문 번호, PayU 주문 ID, 상태, 오류; 키나 개인정보는 제외)를 WooCommerce > Status > Logs(소스 wcp_payu_payment)에 기록합니다. 기본값: 꺼짐.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. 주문 및 결제 데이터는 절대 삭제되지 않습니다. 플러그인을 비활성화해도 모든 데이터가 유지됩니다. 기본값: 꺼짐.

체크아웃

고객은 결제 수단(기본값: PayU)을 선택하고 주문을 완료합니다. 플러그인은 주문 통화 기준 주문 총액에 대해 설명 Order #, 주문 번호, 상점 이름과 함께 PayU 페이지에 표시할 주문 품목, 배송비, 수수료를 포함한 PayU 주문을 생성합니다. PayU 페이지 언어는 PayU에서 지원하는 경우 상점 언어를 따르고, 그렇지 않으면 영어가 사용됩니다. 고객은 PayU 결제 페이지로 이동하여 결제 수단을 선택하고 결제합니다.

각 결제 시도마다 고유한 PayU 주문이 생성됩니다. 고객이 다시 결제할 때(결제 실패 또는 취소 후, 또는 Pay for order 페이지에서), 해당 주문의 이전 미완료 PayU 결제는 PayU에서 취소되므로 이전 결제 링크로 두 번 결제할 수 없습니다.

상점으로 돌아오는 것만으로는 주문이 결제 완료로 처리되지 않습니다. 결제 환경의 Second Key로 서명된 알림을 받거나 고객이 돌아올 때 서버에서 PayU 주문 상태 확인을 거쳐(알림이 지연될 때 유용함) PayU가 확인한 후에만 주문이 결제 완료로 표시됩니다. PayU 주문은 해당 주문에 대해 생성된 것이어야 하며 금액과 통화가 일치해야 합니다. 플러그인은 다음 PayU 상태를 처리합니다:

COMPLETED: 결제가 완료되었습니다. 금액과 통화가 일치하면 주문이 결제 완료로 표시됩니다.

WAITING_FOR_CONFIRMATION: 결제가 승인되었으며 수취 대기 중입니다. 자동으로 수취되거나 주문 작업으로 수취됩니다(Receive payments automatically 참조).

CANCELED: 결제가 취소되었거나 거부되었습니다. 마지막 시도의 미결제 주문은 실패로 표시됩니다. 이전 시도 및 결제 완료된 주문은 변경되지 않습니다.

NEW, PENDING: PayU에서 결제가 진행 중입니다. 주문 상태는 변경되지 않습니다.

주문 접수 페이지에서 주문이 아직 결제 대기 중인 동안 고객에게 We have not received the payment confirmation from PayU yet. If the payment was interrupted, you can try again:가 표시되거나 결제 실패 후 The payment was not completed. You can try again:가 표시되며, 각각 Pay again 버튼이 함께 제공됩니다. 보류 중인 주문의 경우 메시지는 Your payment is being verified. We will send you an e-mail as soon as it is confirmed.입니다.

PayU에서 결제를 시작할 수 없는 경우 고객에게 Payment error. Please try again or choose another payment method.가 표시됩니다. 기술적 원인(HTTP 코드 및 PayU 상태)은 로그와 주문 메모 PayU payment could not be started:에 기록됩니다. 현재 모드의 키가 누락된 경우 메시지는 Payment gateway is not configured properly. Please contact the administrator.입니다.

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

고객은 상점 체크아웃이 아닌 PayU 페이지에서 결제 수단을 선택합니다. 이 플러그인은 상점 내 카드 양식, 저장된 카드 또는 원클릭 결제, 정기결제, PayU 할부 또는 신용 위젯을 포함하지 않습니다. 환경당 하나의 판매 시점을 사용합니다(통화별 판매 시점 없음).

주문 및 환불

주문 상태

Pending payment: 고객이 PayU로 이동했으며 아직 결제하지 않았습니다. 주문 메모에 PayU 주문 ID와 환경(sandbox 또는 live)이 표시됩니다.

Processing: 결제가 확인되었습니다. 주문 메모에 PayU 주문 ID, 금액 및 환경이 표시됩니다. 거래 ID는 결제된 PayU 주문 ID입니다. 가상 다운로드 상품만 포함된 주문은 WooCommerce 기본 동작에 따라 완료됨으로 변경됩니다.

On hold: 결제된 금액 또는 통화가 주문과 일치하지 않거나, 취소된 주문에 대해 결제가 완료되었거나, 결제가 관리자 확인을 대기 중인 경우(자동 수취 꺼짐 또는 수취 실패). 주문 메모에 원인과 대처 방법이 설명됩니다.

Failed: 최신 PayU 결제가 취소되었거나 거부되었습니다. 고객이 결제를 다시 시도할 수 있습니다.

각 알림은 주문별 잠금 하에 한 번만 처리됩니다. 반복된 알림으로 인해 메모가 추가되거나 재고가 두 번 차감되거나 이메일이 중복 발송되지 않습니다. 이미 결제되었거나 환불된 주문에 대해 다른 결제가 완료되면 메모를 통해 PayU 패널에서 환불하도록 안내합니다. 이미 결제되었거나 닫힌 주문에서 확인 대기 중인 결제는 자동으로 취소되어 금액이 이중으로 청구되지 않습니다.

확인 대기 중인 결제

확인 대기 중인 결제가 있는 미결제 주문의 경우 주문 화면에서 두 가지 주문 작업을 제공합니다: Receive PayU payment (waiting for confirmation) 및 Cancel PayU payment (release the funds). 하나를 선택하고 업데이트 버튼을 클릭하세요. 해당 작업은 사용자 이름과 함께 주문 메모에 추가되며 새 PayU 상태가 즉시 적용됩니다.

환불

주문을 열고 Refund를 클릭한 후 금액을 입력하고 Refund via PayU를 클릭하세요(버튼에 설정한 Title이 표시됨). 전액 및 부분 환불을 지원합니다. 환불은 실제로 결제된 PayU 주문에 대해 해당 결제 환경의 키로 전송되므로 해당 키가 설정되어 있어야 합니다. 환불 사유는 환불 설명으로 전송됩니다. PayU가 환불을 거부하면 WooCommerce에 PayU의 오류가 표시되고 환불이 기록되지 않습니다.

PayU에서 환불은 비동기식으로 처리됩니다. 플러그인은 PayU 환불 ID와 상태가 포함된 메모를 즉시 추가하며, 최종 상태는 나중에 PayU 알림으로 수신되어 메모로 추가됩니다. PayU가 환불을 취소하면 고객에게 금액이 반환되지 않았다는 메모가 기록됩니다.

금액 또는 통화 불일치로 인해 보류된 주문은 PayU 주문 ID를 거래 ID로 유지하므로 WooCommerce뿐만 아니라 PayU 패널에서도 환불할 수 있습니다.

라이선스 키

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

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

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

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

문제 해결

체크아웃에 PayU가 나타나지 않음: 라이선스가 활성화되어 있는지, Enable/Disable이 켜져 있는지, 현재 모드의 4개 키가 모두 입력되었는지 확인하세요(샌드박스 모드에서는 Sandbox 키, 라이브 모드에서는 Live 키). 상점 통화(또는 Pay for order 페이지의 주문 통화)가 지원되는 통화 중 하나인지 확인하세요. 설정 페이지에 각 문제에 대한 경고가 표시됩니다.

결제는 완료됐지만 주문이 결제 대기 중 상태로 남아 있음: PayU가 아직 알림을 전달하지 않았고 복귀 페이지의 상태 확인에서 완료된 결제를 감지하지 못했습니다. 설정에 표시된 알림 URL이 인터넷에서 접근 가능한지 확인하세요. 수신되는 데이터를 확인하려면 Logging을 켜세요.

알림 응답으로 Invalid signature가 반환됨: 알림이 어느 환경의 Second Key로도 서명되지 않았습니다. Live Second Key (MD5) 및 Sandbox Second Key (MD5)를 확인하세요. Invalid signature for this payment 응답은 알림이 해당 결제와 다른 환경의 키로 서명되었음을 의미합니다.

알림 응답으로 Ignored가 반환됨: PayU 주문이 이 상점에서 PayU로 결제된 주문에 속하지 않습니다(예: 동일한 POS의 다른 상점). PayU는 재시도를 중단합니다.

결제가 생성되지 않음: Logging을 켜고 WooCommerce > Status > Logs에서 소스 wcp_payu_payment를 확인하세요. 로그에 HTTP 코드와 PayU 상태가 표시됩니다. Could not authenticate with PayU (check the OAuth client ID / secret).는 현재 모드의 OAuth 키가 잘못되었음을 의미합니다.

주문이 보류 중 상태임: 주문 메모를 읽어보세요. 원인은 금액 또는 통화 불일치, 취소 후 결제 또는 확인 대기 중인 결제입니다. 마지막 경우 주문 작업 Receive PayU payment 또는 Cancel PayU payment를 사용하세요.

환불 실패: This order has no completed PayU payment. Cannot process refund.는 주문에 결제된 PayU 주문이 없음을 의미합니다. Sandbox 키 또는 Live 키가 누락되었다는 메시지는 해당 환경에서 결제가 이루어졌고 해당 키가 설정되지 않았음을 의미합니다. 키를 입력하고 다시 시도하세요.

기타 통화: 개발자는 wc_pu_supported_currencies 필터로 통화 목록을 변경하고 wc_pu_icon 필터로 체크아웃 아이콘을 변경할 수 있습니다.

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

제거

플러그인을 비활성화해도 모든 설정이 유지되며 캐시된 PayU 액세스 토큰만 삭제됩니다. 플러그인을 제거하려면 Plugins 페이지에서 비활성화한 후 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 캐시된 토큰과 함께 항상 삭제됩니다. 게이트웨이 설정과 이 플러그인의 로그는 Delete data on uninstall이 켜져 있었던 경우에만 삭제됩니다. 그렇지 않으면 나중에 재설치할 때를 위해 유지됩니다. 기존 주문은 결제 메모, PayU 주문 ID 및 거래 ID를 그대로 유지합니다.

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