VibeFox PayU India for WooCommerce — 도움말

요구 사항

WordPress: 5.8 이상.

WooCommerce: 6.0 이상, 설치 및 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인이 활성화되지 않으며, 나중에 WooCommerce가 비활성화되면 플러그인은 아무 작업도 수행하지 않고 관리자 영역에 알림을 표시합니다.

PHP: 8.0 이상.

Store currency: 인도 루피(INR). PayU India는 루피로만 청구합니다. 다른 통화의 경우 체크아웃 시 결제 수단이 숨겨집니다.

Phone number: PayU는 모든 결제에 전화번호를 요구합니다. 체크아웃에서 전화번호 필드를 필수로 설정하거나 최소한 표시되도록 설정하세요.

PayU India account: PayU Dashboard > Payment Gateway > Key Salt Details에서 Merchant Key 및 Merchant Salt (v1)를 확인해야 합니다. 대시보드를 Test Mode로 전환하면 테스트 쌍을 볼 수 있습니다. Salt v2가 아닌 Salt v1을 사용하세요.

Internet access to your site: 옵션 웹훅에 필요합니다. 웹훅이 없으면 고객이 PayU에서 돌아올 때 주문이 확인됩니다.

VibeFox license key: vibefox.net에서 구매합니다. 키 1개는 도메인 1개에서 작동합니다.

설치

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

2. Activate를 클릭하세요.

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

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

5. 테스트용 Merchant Key와 Salt, 그리고 운영용 Merchant Key와 Salt를 입력하세요(설정 참조).

6. 권장 사항: PayU Dashboard > Webhooks에서 성공 및 실패한 결제에 대해 설정 페이지에 표시된 웹훅 URL을 추가하세요.

7. Mode를 선택하고 Enable/Disable을 켜세요. Test 모드에서 결제를 테스트한 다음 Live로 전환하세요.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > PayU India. 현재 모드의 키나 Salt가 누락된 경우 필드 위에 경고가 표시되며, Test 모드에서는 Test mode is active: payments go to test.payu.in and no real money is charged.가 표시되고, 상점 통화가 INR이 아닌 경우 경고가 표시됩니다(이 경우 체크아웃에서 게이트웨이가 숨겨집니다).

공백이 포함된 Salt는 모든 PayU 응답 확인을 실패하게 만들므로, 저장 시 키와 Salt에서 공백 및 줄바꿈이 자동으로 제거됩니다.

일반

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

Title: 체크아웃 시 고객에게 표시되는 결제 수단 이름입니다. 기본값: PayU India.

Description: 체크아웃 시 고객에게 표시되는 결제 수단 설명입니다. 기본값: Pay securely via Credit/Debit Card, NetBanking, UPI, or Wallets through PayU.

API 자격 증명

PayU Dashboard > Payment Gateway > Key Salt Details에서 Merchant Key 및 Merchant Salt (v1)를 복사하세요. 테스트 쌍을 얻으려면 대시보드를 Test Mode로 전환하세요.

Mode: 새 결제에 사용할 PayU 환경을 선택합니다.

환불은 항상 결제가 이루어진 원래 모드로 전송됩니다.

Live Merchant Key: 운영용 PayU Merchant Key입니다.

Live Merchant Salt (v1): 운영용 PayU Merchant Salt (v1)입니다. 요청에 서명하고 PayU 응답을 확인합니다. 비밀로 유지하세요.

Test Merchant Key: Test 모드에서만 사용되는 PayU 테스트용 Merchant Key입니다.

Test Merchant Salt (v1): Test 모드에서만 사용되는 PayU 테스트용 Merchant Salt (v1)입니다.

반환 및 웹훅 URL

Return URL: https://your-site/wc-api/payu_p_callback/ 형식입니다. 결제할 때마다 자동으로 PayU에 전송되므로 별도로 설정할 필요가 없습니다.

Webhook URL: https://your-site/wc-api/payu_p_webhook/ 형식입니다. 선택 사항이지만 권장됩니다. 고객이 상점으로 돌아오기 전에 브라우저를 닫더라도 결제를 확인합니다. PayU Dashboard > Webhooks에서 성공 및 실패한 결제에 추가하세요. 설정 페이지에 표시된 그대로 URL을 정확히 복사하세요.

고급

Verify Payment: Double-check every successful payment with the PayU verify_payment API. 권장 사항입니다. 확인을 완료할 수 없는 경우 주문은 결제 완료로 표시되지 않고 보류 중 상태가 됩니다. 기본값: 켜짐.

Enable Logging: Log gateway events for troubleshooting. WooCommerce > Status > Logs에서 소스 wcp_payu_india_payment로 기록됩니다. 오류 및 경고는 항상 기록되며, 이 옵션을 켜면 다른 이벤트도 추가됩니다. 키, Salt, 고객의 개인정보는 절대 기록되지 않습니다. 기본값: 꺼짐.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted (orders are never deleted). 기본값: 꺼짐.

체크아웃

고객은 결제 수단(기본값 PayU India)을 선택하고 주문을 접수합니다. 주문에 청구지 전화번호(또는 배송지 전화번호)가 없는 경우, 고객에게 PayU India requires a phone number. Please enter your phone number and try again.가 표시됩니다. 그렇지 않으면 고객은 짧은 페이지인 Thank you for your order. You will be redirected to PayU to complete your payment.로 이동하며, 이 페이지에서 PayU 호스팅 체크아웃으로 서명된 결제 요청을 보냅니다. 그곳에서 고객은 카드, NetBanking, UPI 또는 지갑으로 결제합니다.

각 결제 페이지는 고유한 PayU 거래 ID를 받으며, 해당 금액 및 모드와 함께 주문에 저장됩니다. 동일한 주문에 대해 이전에 열려 있던 이전 결제 페이지에서 수행된 결제도 계속 수락됩니다. 결제 완료, 보류 중 또는 취소된 주문에는 새로운 결제 양식이 절대 제공되지 않으므로 브라우저의 뒤로 가기 버튼으로 두 번째 결제가 시작될 수 없습니다.

PayU는 고객 복귀 시 결과를 전송하고 설정된 경우 웹훅을 통해서도 결과를 전송합니다. 결제가 시작된 모드의 키와 Salt로 생성된 유효한 PayU 해시가 있고 해당 주문에 대해 발급된 거래 ID인 경우에만 결과가 수락됩니다. Verify Payment가 켜져 있으면 성공적인 결과는 PayU verify_payment API를 통해서도 확인됩니다. 결제 금액은 INR 기준으로 파이사 단위까지 주문 총액과 일치해야 합니다. 주문은 PayU가 이러한 방식으로 확인한 후에만 결제 완료로 표시됩니다. 플러그인은 다음과 같은 PayU 결과를 처리합니다:

성공 또는 보류 중인 결제 후 고객은 주문 접수 페이지를 보게 됩니다. 실패한 결제 후 고객은 다음과 같은 메시지와 함께 체크아웃으로 돌아옵니다: Payment was not completed. Please try again or choose a different payment method., Payment was cancelled. You may try again., 또는 결과를 확인할 수 없는 경우 We could not confirm the payment result. If your account was charged, please contact us before paying again. 메시지가 표시됩니다. 이 메시지들은 클래식 체크아웃과 체크아웃 블록 모두에서 작동합니다.

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

플러그인은 INR로만 청구되며 다중 통화 처리(MCP)를 지원하지 않습니다. 저장된 카드 및 토큰화, WooCommerce Subscriptions, 사이트 내 심리스(seamless) 카드 양식, EMI(할부) 또는 프로모션 관리, PayU 원클릭 체크아웃을 지원하지 않습니다.

주문 및 환불

주문 상태

Pending payment: 고객이 PayU로 이동했으며 아직 결제하지 않았습니다.

Processing: 결제가 확인되었습니다. 주문 메모에는 PayU 거래 ID(mihpayid), 결제 모드, 은행 코드가 표시됩니다. 주문의 거래 ID는 PayU mihpayid입니다. 가상 다운로드 상품만 포함된 주문은 WooCommerce 기본 동작에 따라 완료됨 상태가 됩니다.

On hold: PayU에서 결제가 아직 보류 중이거나(UPI 또는 NetBanking), 결제 금액 또는 통화가 주문과 다르거나, verify_payment API에 연결할 수 없거나 아직 결제를 확인하지 못했거나, 이미 취소된 주문에 대해 결제가 도착한 경우입니다. 주문 메모에 이유가 표시됩니다. PayU Dashboard에서 거래를 확인하고 완료하거나 환불하세요. 검증에 실패한 경우 다음번에 결과가 전달될 때 주문이 자동으로 확인됩니다.

Failed: 결제가 거부되었거나 취소되었습니다. 고객은 다시 결제할 수 있습니다.

이미 결제 완료된 주문에 대해 PayU가 또 다른 성공적인 결제를 보고하는 경우, 메모를 통해 PayU Dashboard에서 중복 건을 환불하도록 안내합니다.

환불

주문을 열고 Refund를 클릭한 다음 금액을 입력하고 Refund via PayU India를 클릭하세요(버튼에는 지정한 Title이 표시됩니다). 전액 및 부분 환불을 지원하며, 금액은 0보다 커야 합니다. 환불은 결제가 이루어진 모드의 키와 Salt를 사용하여 PayU 환불 API를 통해 전송되므로 해당 자격 증명이 설정되어 있어야 합니다. PayU가 환불을 거부하면 WooCommerce에 PayU의 메시지가 표시되고 환불은 기록되지 않습니다.

PayU는 환불을 대기열에 추가하고 비동기식으로 처리하며, 고객은 대개 영업일 기준 5~7일 이내에 환불을 받습니다. 주문 메모에는 금액, PayU 요청 ID, 이유가 표시됩니다. 플러그인은 나중에 환불 상태를 다시 확인하지 않습니다.

라이선스 키

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

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

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

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

문제 해결

PayU India does not appear at checkout: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 선택한 Mode의 키와 Salt가 입력되어 있는지 확인하세요. 상점 통화(또는 Pay for order 페이지의 주문 통화)가 INR인지 확인하세요. 설정 페이지에는 이러한 문제 각각에 대한 경고가 표시됩니다.

The payment went through, but the order stays Pending payment: 고객이 상점으로 돌아오지 않았고 웹훅도 도착하지 않았습니다. 성공 및 실패한 결제에 대해 설정에 있는 웹훅 URL을 PayU Dashboard > Webhooks에 추가하고 인터넷에서 접근 가능한지 확인하세요.

Webhook answers invalid_signature: PayU 해시가 일치하지 않았습니다. 결제 모드의 키와 Salt가 올바른지, Salt v2가 아닌 Salt v1을 사용하고 있는지 확인하세요. 주문은 변경되지 않습니다.

Webhook answers not_configured: 결제가 시작된 모드의 키 또는 Salt가 누락되었습니다. 이를 입력하면 PayU가 웹훅을 다시 시도합니다.

Webhook answers verify_unavailable: verify_payment API가 아직 결제를 확인하지 못했습니다. 주문은 보류 중 상태가 되며 다음 전송 시 다시 검증합니다.

The customer sees PayU India requires a phone number: 체크아웃에서 전화번호 필드를 필수로 설정하거나 표시되도록 설정하세요. 청구지 전화번호가 사용되며, 배송지 전화번호만 입력된 경우 해당 번호가 사용됩니다.

The order is On hold: 주문 메모를 확인하세요. 원인은 대기 중인 UPI 또는 NetBanking 결제, 금액 또는 통화 불일치, 확인 실패 또는 대기, 혹은 취소된 주문에 대한 결제입니다.

Refund fails: PayU transaction ID not found for this order. 메시지는 주문에 PayU 결제가 없음을 의미합니다. 결제 모드의 Merchant Key/Salt가 설정되지 않았다는 메시지는 해당 모드의 자격 증명을 먼저 입력해야 함을 의미합니다.

Too little in the log: 오류와 경고는 항상 기록됩니다. 모든 PayU 요청과 결과까지 확인하려면 Enable Logging을 켜세요.

Developer hooks: payu_p_request_fields 필터는 결제 요청 필드가 서명되기 전에 이를 변경하며, payu_p_icon 필터는 체크아웃 아이콘을 변경합니다.

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

제거

플러그인을 비활성화해도 모든 데이터가 보존됩니다. 플러그인을 완전히 제거하려면 Plugins 페이지에서 비활성화하고 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정 및 이 플러그인의 로그(로그 파일 및 WooCommerce 데이터베이스 로그 행)는 Delete data on uninstall이 켜져 있는 경우에만 삭제됩니다. 그렇지 않은 경우 나중에 재설치할 수 있도록 보존됩니다. 기존 주문에는 결제 메모, PayU 거래 ID, 환불 요청 ID가 그대로 유지됩니다.

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