VibeFox PayU India for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0~9.x.

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

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

전화번호: PayU는 모든 결제에 전화번호를 요구합니다. 체크아웃에서 주소의 전화번호 필드를 필수로 설정하거나, 최소한 보이도록 설정하십시오.

PayU India 계정: PayU Dashboard > Payment Gateway > Key Salt Details에서 Merchant Key와 Merchant Salt (v1)을 가져와야 합니다. 테스트 키 쌍을 보려면 대시보드를 Test Mode로 전환하십시오. Salt v2가 아닌 Salt v1을 사용하십시오.

쇼핑몰의 인터넷 접근: 선택 사항인 웹훅에 필요합니다. 웹훅이 없으면 고객이 PayU에서 돌아올 때 주문이 확인됩니다.

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

설치

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

2. 업로드가 완료되면 Configure를 클릭하거나, 나중에 모듈 목록에서 VibeFox PayU India Payment Gateway를 찾아 Configure를 클릭합니다.

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

4. Test Merchant Key와 Salt, 그리고 Live Merchant Key와 Salt를 입력합니다(설정 항목 참조).

5. 권장: PayU Dashboard > Webhooks에서 Configure 페이지에 표시된 웹훅 URL을 성공 및 실패 결제에 대해 추가합니다.

6. Mode를 선택하고 Enable/Disable을 켠 후 Save를 클릭합니다. 테스트 모드에서 결제를 시험한 다음 운영 모드로 전환합니다.

설치 시 모듈은 두 가지 주문 상태를 만듭니다: Awaiting PayU India payment와 PayU India payment on hold. PrestaShop은 모든 통화, 국가 및 고객 그룹에 대해 새 결제 모듈을 제공합니다. Payment > Preferences에서 제한할 수 있으나, INR 통화는 모듈에 대해 허용된 상태로 유지되어야 합니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure. 각 섹션에는 자체 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. 필드 위에서 페이지는 현재 모드의 키 또는 Salt가 없으면 경고하고, 테스트 모드에서는 Test mode is active: payments go to test.payu.in and no real money is charged.를 표시하며, 쇼핑몰의 기본 통화가 INR이 아니면 오류를 표시합니다(이 경우 게이트웨이는 체크아웃에서 숨겨집니다).

저장할 때 키와 Salt에서 공백과 줄바꿈이 제거됩니다. 붙여넣은 Salt에 공백이 있으면 PayU의 모든 응답이 검증에 실패하기 때문입니다.

PayU India

Enable/Disable: Enable PayU India Payment Gateway는 결제 수단을 켜거나 끕니다. 기본값: 꺼짐. 현재 모드의 키와 Salt 없이 켜면 저장 후 페이지가 경고합니다.

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로 전환하십시오. 이 섹션에는 Open the PayU Dashboard 링크가 있습니다.

Mode: 새 결제에서 사용하는 PayU 환경입니다.

이미 시작된 결제는 시작될 때의 모드를 유지합니다. 모드를 전환한 후에도 그 결제의 결과는 해당 모드의 키와 Salt로 확인되며, 환불도 해당 모드의 키와 Salt로 전송됩니다.

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

Live Merchant Salt (v1): 운영용 PayU Merchant Salt (v1)입니다. 요청에 서명하고 PayU 응답을 검증합니다. 비밀로 유지하십시오.

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

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

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

Clear saved salts: Salt를 체크하고 Save를 클릭하면 삭제됩니다. 빈 필드는 저장된 값을 유지합니다.

반환 및 웹훅 URL

Return URL: https://your-shop/module/wcp_payu_india_payment/return 형태이며, /en/ 같은 언어 코드가 포함될 수 있습니다. 모든 결제에 대해 자동으로 PayU에 전송되므로 따로 설정할 필요가 없습니다.

Webhook URL: https://your-shop/module/wcp_payu_india_payment/webhook 형태이며, 언어 코드가 포함될 수 있습니다. 선택 사항이지만 권장됩니다. 고객이 돌아오기 전에 브라우저를 닫더라도 결제를 확인합니다. PayU Dashboard > Webhooks에서 성공 및 실패 결제에 대해 추가하십시오. Configure 페이지에 표시된 URL을 정확히 복사하십시오. 인터넷에서 접근 가능해야 합니다(기본 인증이나 방화벽 차단이 없어야 함). 쇼핑몰의 유지 보수 모드와 국가 제한은 이를 차단하지 않습니다.

웹훅은 고객의 반환과 같은 서명된 결과를 전달합니다. 유효한 PayU 해시가 없는 웹훅은 거부됩니다.

고급

Verify Payment: 성공한 모든 결제를 PayU verify_payment API로 다시 확인합니다. 권장됩니다. 확인을 완료할 수 없으면 주문은 결제 완료로 표시되지 않고 보류 상태가 됩니다. 기본값: 켜짐.

Enable Logging: 문제 해결을 위해 게이트웨이 이벤트를 모듈 폴더의 logs/payu_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류와 경고는 항상 기록됩니다. 이 옵션은 모든 결제 양식과 PayU 결과 등 다른 이벤트를 추가로 기록합니다. 키, Salt 및 고객의 개인정보는 절대 기록되지 않습니다. 기본값: 꺼짐.

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

Delete data on uninstall: 모듈을 제거할 때 모듈 설정과 로그를 삭제합니다. 주문과 PayU 거래 기록은 절대 삭제되지 않습니다. 기본값: 꺼짐.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 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 호스팅 체크아웃으로 보냅니다. 브라우저가 자동으로 진행되지 않으면 페이지에 Pay with PayU 버튼과 Back to checkout 버튼이 있습니다. PayU 페이지에서 고객은 카드, NetBanking, UPI 또는 지갑으로 결제합니다. 이 시점에는 아직 주문이 없습니다.

결제 시도마다 장바구니 번호로 시작하는 고유한 PayU 거래 ID가 발급되며, 금액 및 모드와 함께 저장됩니다. 같은 장바구니에 대해 이전에 열린 아직 유효한 결제 페이지에서 한 결제도 여전히 수락됩니다. 이미 주문이 있는 장바구니에는 새 결제 양식이 제공되지 않으므로, 브라우저의 뒤로 가기 버튼으로 두 번째 결제를 시작할 수 없습니다.

PayU는 결과를 고객과 함께 반환하며, 설정된 경우 웹훅으로도 보냅니다. 결과는 결제가 시작된 모드의 키와 Salt로 생성된 유효한 PayU 해시가 있고, 해당 장바구니에 대해 발급된 거래 ID인 경우에만 수락됩니다. Verify Payment가 켜져 있으면 성공한 결과는 PayU verify_payment API로도 확인됩니다. 결제 금액은 시도 금액 및 장바구니 총액과 INR 기준으로 파이사(paisa) 단위까지 정확히 일치해야 합니다. PayU가 이 방식으로 확인한 후에만 주문이 결제 완료로 표시됩니다. 모듈은 다음 PayU 결과를 처리합니다:

결제가 성공하거나 대기 중이면 고객은 표준 주문 확인 페이지를 보게 됩니다. 대기 중인 결제는 Your PayU payment is pending. The order will be updated as soon as PayU confirms the result — there is no need to pay again.를 추가로 표시하고, 보류 중인 주문은 Your payment is being reviewed. We will contact you if anything else is needed.를 추가로 표시하며, Payment error 또는 Canceled 상태의 주문은 Your PayU payment was not completed. Please contact us about this order.를 표시합니다.

결제가 완료되지 않으면 고객은 다음 메시지와 함께 체크아웃으로 돌아옵니다: 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. 고객이 돌아올 때 결과가 아직 처리 중이면, We are confirming your PayU payment. If you completed the payment, your order will be created shortly — please do not pay again.와 Check again 버튼이 있는 페이지가 표시됩니다.

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

주문 및 환불

주문 상태

No order yet: 고객이 PayU로 이동했지만 아직 결제하지 않았거나, 결제가 실패했거나 취소되었습니다. 장바구니만 존재합니다.

Payment accepted: 결제가 확인되었습니다. 결제는 PayU 거래 ID(mihpayid)를 거래 ID로 하여 기록되며, 메모에 PayU payment successful. Transaction ID: …, Mode: …, Bank: …가 표시됩니다.

Awaiting PayU India payment: UPI 또는 NetBanking 결제가 PayU에서 아직 대기 중입니다. PayU가 확인하면 주문은 Payment accepted가 됩니다.

PayU India payment on hold: 결제된 금액 또는 통화가 장바구니와 다르거나, verify_payment API에 연결할 수 없었거나 아직 결제를 확인하지 못했거나, 이미 취소된 주문에 대한 결제가 도착했습니다. 메모에 사유가 표시됩니다. PayU Dashboard에서 거래를 확인한 다음 주문을 Payment accepted로 설정하거나 주문을 취소하고 결제를 환불하십시오. 검증만 실패한 경우에는 다음번 결과 전달 시 주문이 자동으로 결제 완료됩니다.

Payment error: 대기 중이던 결제가 나중에 거절되었거나 취소되었습니다. 이후에 도착한 성공 결과는 여전히 주문을 결제 완료로 처리합니다.

Refunded: 결제된 전액이 모듈을 통해 환불되었습니다.

이미 결제 완료된 주문에 대해 PayU가 다른 성공 결제를 보고하면, 주문은 변경되지 않으며 중복 결제를 PayU Dashboard에서 환불하라는 메모가 표시됩니다. 다른 결제 수단으로 주문된 장바구니에 대한 PayU 결제는 메모가 붙으며 해당 주문을 결제 완료로 처리하지 않습니다.

PayU India 결제 블록

주문 페이지에는 PayU 거래 ID(mihpayid), 쇼핑몰 거래 ID(txnid), 환경, PayU 상태, 결제 모드와 은행, 결제 금액과 환불 요청 금액, 테스트 결제용 Test mode 배지, 환불 내역 및 모듈 메모를 포함한 PayU India payment 블록이 표시됩니다. 보류 중인 주문의 경우 결제를 검토하라는 알림이 표시됩니다.

환불

PayU India payment 블록에서 금액을 입력하고(아직 환불되지 않은 금액이 자동으로 채워집니다), 필요하면 사유를 입력한 다음 Refund via PayU를 클릭합니다. Refund this amount through PayU? This cannot be undone. 질문을 확인합니다. 전액 및 부분 환불을 지원하며, 금액은 0보다 커야 하고 PayU가 청구한 금액의 남은 금액을 넘을 수 없습니다. 주문을 편집할 권한이 필요하며, 모듈 페이지에 대한 접근 권한은 필요하지 않습니다. 환불은 결제가 이루어진 모드의 키와 Salt를 사용해 PayU 환불 API를 통해 전송되므로, 해당 인증 정보가 설정되어 있어야 합니다. PayU가 환불을 거절하면 블록에 PayU 메시지와 함께 PayU refund failed:가 표시되며, 환불은 기록되지 않습니다.

PayU는 환불을 대기열에 추가하고 비동기로 처리합니다. 고객은 보통 5~7영업일 내에 입금을 받습니다. 환불 내역과 메모에는 금액, PayU 요청 ID 및 사유가 표시됩니다. 전액 환불은 주문을 Refunded로 설정하며, 부분 환불은 상태를 변경하지 않습니다. 환불은 PayU가 결제의 거래 ID를 보고한 후에 가능합니다. 모듈은 나중에 환불 상태를 확인하지 않으며 크레딧 슬립(credit slip)을 생성하지 않습니다. 주문 페이지의 기본 PrestaShop 환불 버튼은 PayU를 통해 돈을 돌려보내지 않습니다.

라이선스 키

모듈은 vibefox.net에서 발급받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록 License — VibeFox PayU India Payment Gateway는 Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure의 첫 번째 블록으로, 설정 위에 있습니다. 키를 License key에 입력하고 Activate를 클릭하십시오. 그러면 블록에 키가 마스킹되어 표시되고, 상태(라이선스 유효 기간 날짜와 도메인 등)와 함께 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key 버튼이 나타납니다. 그 아래에는 Product: presta-payment-payu-india 줄과 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 계정에서 슬롯을 해제하십시오.

활성 키가 없으면 체크아웃에서 고객에게 PayU India가 표시되지 않습니다. 그래도 결제가 시작되면 고객에게 This payment method is not available. Please choose another one.가 표시됩니다. PrestaShop 스토어프런트는 백오피스에 로그인한 사실을 알지 못하므로, 결제 방식은 귀하에게도 숨겨집니다. 키를 구매하기 전에 모듈을 설정할 수는 있지만, 체크아웃에서 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 나타납니다. 기존 주문은 영향을 받지 않습니다. 이미 시작된 결제는 알림을 통해 계속 확인되며, 환불도 작동합니다.

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

문제 해결

체크아웃에 PayU India가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 선택한 Mode의 키와 Salt가 입력되어 있는지 확인하십시오. 장바구니 통화가 INR인지, 그리고 Payment > Preferences에서 해당 통화, 고객의 국가 및 고객 그룹에 대해 모듈이 허용되어 있는지 확인하십시오. Configure 페이지는 누락된 인증 정보와 INR이 아닌 쇼핑몰 통화에 대해 경고를 표시합니다.

결제는 완료되었으나 주문이 생성되지 않음: 고객이 쇼핑몰로 돌아오지 않았고 웹훅도 도착하지 않았습니다. Configure 페이지의 웹훅 URL을 성공 및 실패 결제에 대해 PayU Dashboard > Webhooks에 추가하고, 인터넷에서 접근 가능한지 확인하십시오.

웹훅이 invalid_signature를 반환: PayU 해시가 일치하지 않았습니다. 결제 모드의 키와 Salt가 올바른지, 그리고 Salt v2가 아닌 Salt v1을 사용하고 있는지 확인하십시오. 테스트 Salt로 서명된 운영 결제 결과나 그 반대의 경우도 거부됩니다. 아무것도 변경되지 않습니다.

웹훅이 not_configured를 반환: 결제가 시작된 모드의 키 또는 Salt가 없습니다. 입력하십시오. PayU가 웹훅을 다시 시도합니다.

웹훅이 verify_unavailable을 반환: verify_payment API가 아직 결제를 확인하지 못했습니다. 주문은 보류 상태이며, 다음 전달 때 다시 검증합니다.

웹훅이 busy 또는 retry를 반환: 같은 장바구니에 대한 고객의 반환이 같은 순간에 처리되고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). PayU가 웹훅을 다시 시도합니다. 사유는 로그에 기록됩니다.

웹훅이 ignored_unknown_txnid를 반환: 이 쇼핑몰이 시작하지 않은 거래입니다. 예를 들어 같은 PayU 계정을 사용하는 다른 쇼핑몰입니다. 아무것도 변경되지 않습니다.

고객에게 PayU India requires a phone number가 표시됨: 체크아웃에서 주소의 전화번호 필드를 필수 또는 표시되도록 설정하십시오. 청구지 주소가 먼저 사용되고, 그다음 배송지 주소가 사용됩니다.

주문이 PayU India payment on hold 상태: PayU India payment 블록의 메모를 읽으십시오. 사유는 금액 또는 통화 불일치, 실패했거나 대기 중인 검증, 또는 취소된 주문에 대한 결제입니다.

환불 실패: PayU transaction ID not found for this order.는 주문에 아직 PayU 결제가 없다는 뜻입니다. This payment was made in Test mode, but the Merchant Key/Salt of that mode are not set.(또는 Live mode)는 먼저 해당 모드의 인증 정보를 입력해야 한다는 뜻입니다. Invalid refund amount: at most … INR can be refunded.는 금액이 결제의 남은 금액보다 많다는 뜻입니다.

로그 정보가 부족함: 오류와 경고는 항상 기록됩니다. 모든 결제 양식과 PayU 결과까지 보려면 Enable Logging을 켜십시오.

개발자 훅: actionPayuPRequestFields는 결제 요청 필드를 서명하기 전에 변경합니다. 키, 거래 ID, 금액 및 반환 URL은 이 훅으로 변경할 수 없습니다.

제거

Modules > Module Manager로 이동하여 VibeFox PayU India Payment Gateway 옆의 메뉴를 열고 Uninstall을 선택합니다. 이 모듈의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Delete data on uninstall이 켜져 있으면 모듈 설정과 로그가 삭제됩니다. 꺼져 있으면 나중에 재설치할 수 있도록 모든 설정이 유지됩니다. PayU 거래 기록과 환불 요청, 그리고 주문 상태 Awaiting PayU India payment와 PayU India payment on hold는 항상 유지되므로, 이전에 결제된 주문은 재설치 후에도 환불할 수 있습니다. 기존 주문은 결제 메모와 PayU 거래 ID를 유지합니다.

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