VibeFox PayU LATAM for WooCommerce — 도움말

요구 사항

WordPress: 5.8 이상.

WooCommerce: 7.0 이상이 설치되고 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인을 활성화할 수 없습니다. 이후 WooCommerce를 비활성화하면 플러그인은 아무 작업도 하지 않고 관리 영역에 알림을 표시합니다.

PHP: 8.0 이상.

Currency: 주문은 ARS, BRL, CLP, COP, MXN, PEN 또는 USD 통화여야 합니다. 이는 PayU Latam이 아르헨티나, 브라질, 칠레, 콜롬비아, 멕시코, 파나마, 페루에서 처리하는 통화입니다. 다른 통화에서는 체크아웃에 결제 수단이 표시되지 않습니다.

PayU Latam account: PayU 상점의 세 가지 값, 즉 가맹점 ID, 판매 국가의 계정 ID, API 키가 필요합니다. PayU 모듈(PayU 가맹점 패널)의 Settings > Technical configuration(가맹점 ID, API 키) 및 Accounts(계정 ID)에서 확인할 수 있습니다. PayU는 개발자 문서의 "Test your solution" 페이지에 공개 샌드박스 자격 증명과 테스트 카드를 제공합니다. 결제는 PayU가 호스팅하는 페이지에서 이루어지므로 API Login 및 기타 API 자격 증명은 필요하지 않습니다.

Internet access to your site: PayU는 자체 서버에서 쇼핑몰로 결제 결과를 전송하므로 인터넷에서 사이트에 접근할 수 있어야 합니다(로컬 사이트이거나 비밀번호 보호 또는 유지보수 페이지로 차단되어 있으면 안 됩니다).

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

설치

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

2. Activate를 클릭합니다.

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

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

5. 샌드박스 및 운영 자격 증명을 입력합니다(구성 참조). PayU에 확인 URL을 설정할 필요는 없습니다.

6. Enable/Disable를 켜고 저장합니다. 테스트 결제를 완료할 때까지 Sandbox를 켜 두고, 이후 선택을 해제하여 운영 자격 증명으로 실제 결제를 받습니다.

구성

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > PayU LATAM. 샌드박스 모드가 켜져 있을 때(Sandbox mode. 결제는 PayU 샌드박스로 전송되며 실제 금액은 청구되지 않습니다.), 현재 환경의 가맹점 ID, 계정 ID 또는 API 키가 누락되었을 때, PayU LATAM이 쇼핑몰 통화를 처리하지 않을 때 필드 위에 경고가 표시됩니다. 마지막 두 경우에는 체크아웃에 PayU LATAM이 표시되지 않습니다. 결제 수단 목록에서 PayU LATAM은 현재 환경의 자격 증명 세 가지가 모두 입력될 때까지 설정 필요로 표시됩니다. 자격 증명의 앞뒤 공백은 무시됩니다.

일반

Enable/Disable: Enable PayU LATAM는 결제 수단을 켜거나 끕니다. 기본값: off.

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

Description: 체크아웃 시 고객에게 표시되는 결제 수단 설명입니다. 기본값: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

환경

Sandbox: Enable the PayU sandbox (test mode). 아래의 샌드박스 자격 증명으로 PayU 샌드박스에 결제가 전송되며 실제 금액은 청구되지 않습니다. 비활성화하면 운영 자격 증명과 PayU 운영 체크아웃이 사용됩니다. 기본값: on.

운영 자격 증명

PayU 모듈의 Settings > Technical configuration(가맹점 ID, API 키) 및 Accounts(판매 국가의 계정 ID)에서 확인합니다. 이 섹션에는 PayU 가맹점 패널 링크가 있습니다.

Merchant ID: PayU 상점의 숫자 식별자입니다.

Account ID: PayU 계정의 식별자입니다. 국가별로 계정이 하나씩 있습니다.

API Key: 결제에 서명하고 PayU 알림을 검증하는 데 사용하는 비밀 키입니다.

샌드박스 자격 증명

PayU는 샌드박스용 공개 테스트 자격 증명과 테스트 카드를 제공합니다. 이 섹션에는 PayU 문서의 "Test your solution" 페이지 링크가 있습니다.

Sandbox merchant ID: PayU 샌드박스의 가맹점 ID입니다.

Sandbox account ID: PayU 샌드박스의 계정 ID입니다.

Sandbox API key: PayU 샌드박스의 API 키입니다.

각 결제 시도는 해당 환경을 기억합니다. 샌드박스 결제의 확인은 샌드박스 API 키와 가맹점 ID로, 운영 결제의 확인은 운영 값으로 검증하므로 환경을 전환해도 대기 중인 결제는 계속 작동합니다. 자격 증명 세트가 하나였던 버전 1.0에서 업데이트할 때 샌드박스가 켜져 있었다면 기존 값이 샌드박스 필드로 복사됩니다. 업데이트 후 설정을 확인하세요.

확인 URL

이 섹션에는 PayU가 각 결제 결과를 보고하는 URL이 표시됩니다. 형식은 https://your-site/wc-api/payu_lp/와 같습니다. 플러그인이 결제마다 이를 PayU에 전송하므로 PayU에서 설정할 것은 없습니다. 인터넷에서 해당 페이지에 접근할 수 있어야 합니다. PayU는 API 키로 확인에 서명합니다. 유효한 서명이 없거나, 가맹점 ID가 다르거나, 이 쇼핑몰이 해당 주문에 발급하지 않은 결제 참조를 포함한 확인은 거부됩니다. 플러그인은 다음 PayU 거래 상태를 처리합니다.

4 (approved): 결제가 이루어졌습니다. 금액과 통화가 일치하면 주문이 결제 완료로 표시됩니다.

6 (declined), 5 (expired), 104 (error): 결제가 실패했습니다. 최근 시도에 해당하는 미결제 주문은 실패로 표시됩니다.

7 and other pending states: 결제가 대기 중입니다. 예를 들어 고객이 아직 완료하지 않은 현금 또는 은행 결제가 해당합니다. 주문은 보류됩니다.

그 밖의 상태는 주문 메모로만 추가됩니다. 확인 없이는 주문이 결제 완료로 표시되지 않으며 결제 대기 중 상태로 유지됩니다.

고급

Debug log: Log payment requests and PayU notifications는 키나 개인 데이터 없이 WooCommerce > Status > Logs의 소스 wcp_payu_latam_payment에 세부 정보를 기록합니다. 오류와 거부된 알림은 항상 기록됩니다. 기본값: off.

Delete data: Delete the settings and logs when the plugin is deleted. 플러그인을 비활성화해도 아무것도 삭제되지 않습니다. 주문에 저장된 PayU 데이터는 유지됩니다. 기본값: off.

체크아웃

고객은 결제 수단(기본값 PayU LATAM)을 선택하고 주문합니다. 샌드박스 모드의 체크아웃 블록에는 Sandbox mode: no real payment is made.가 표시됩니다. 주문은 결제 대기 중 상태로 유지되고 고객은 Thank you for your order. You are being redirected to PayU LATAM to complete the payment… 문구가 있는 쇼핑몰 결제 페이지로 이동합니다. 페이지는 서명된 양식을 PayU WebCheckout 페이지로 자동 전송합니다. 자동 전송되지 않으면 고객은 Pay with PayU LATAM를 클릭하거나 Cancel order를 클릭하여 주문을 취소합니다.

양식에는 주문 총액과 통화, 주문 세금과 과세 기준액(비과세 주문에서는 둘 다 0으로 보내 PayU가 기본 부가가치세를 추가하지 않도록 함), 주문 번호와 쇼핑몰 이름을 포함하는 Order # 설명, 고객의 이메일, 이름, 전화번호 및 청구 주소가 포함됩니다. PayU 페이지는 쇼핑몰 언어에 따라 스페인어, 포르투갈어 또는 영어로 열립니다. 고객은 PayU 페이지에서 PayU 계정에 활성화된 결제 수단으로 결제합니다.

결제 페이지에 방문할 때마다 고유 참조(주문 번호와 타임스탬프)를 가진 새 결제 시도가 시작됩니다. 주문의 최근 30개 시도를 기억하므로 고객이 이전 PayU 탭에서 결제해도 결제가 수락됩니다.

주문은 PayU의 서명된 확인을 받은 뒤에만 결제 완료로 표시됩니다. 고객이 PayU에서 돌아오는 것만으로 주문이 결제 완료가 되지는 않습니다. 고객이 돌아오면 다음과 같이 처리됩니다.

서명된 거절, 만료 또는 오류 후: 주문이 즉시 실패로 표시되고 WooCommerce는 다시 결제할 수 있는 표준 결제 실패 페이지를 보여 줍니다.

PayU 거래가 없는 경우(고객이 PayU 페이지를 떠남): 고객은 Pay for order 페이지로 이동하며 Your PayU LATAM payment was not completed. You can try again or choose another payment method. 메시지가 표시됩니다.

그 밖의 경우: 고객은 주문 접수 페이지를 봅니다. 주문이 결제 대기 중이면 We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed.가 표시됩니다. 보류 중인 주문에는 Your PayU LATAM payment is pending (for example, a cash or bank payment that has not been completed yet). We will process the order as soon as PayU confirms the payment.가 표시됩니다.

현재 환경의 자격 증명이 없으면 고객에게 PayU LATAM is not available right now. Please choose another payment method.가 표시됩니다. 지원하지 않는 주문 통화라면 PayU LATAM does not accept payments in 뒤에 통화가 표시됩니다. 이미 결제한 주문은 다시 결제되지 않으며 결제 페이지에 This order has already been paid.가 표시됩니다.

이 결제 수단은 클래식 체크아웃, 체크아웃 블록 및 Pay for order 페이지에서 작동합니다. WooCommerce High-Performance Order Storage(HPOS)와 호환됩니다.

플러그인은 쇼핑몰 내 결제 양식, WooCommerce에서의 환불, 저장된 카드, 구독, 할부 설정을 제공하지 않습니다(할부는 PayU 페이지에 표시됩니다). PayU API에 결제 상태를 조회하지 않으며 서명된 확인만 주문을 업데이트합니다.

주문

주문 상태

Pending payment: 고객이 PayU로 이동했지만 아직 결제하지 않았거나 PayU가 아직 확인을 보내지 않았습니다.

Processing: PayU가 결제를 확인했고 금액과 통화가 일치합니다. 주문 메모에는 PayU 거래, 금액, 결제 수단이 표시되며 샌드박스 결제에는 [sandbox]가 표시됩니다. 주문의 거래 ID는 PayU 거래 ID입니다. 가상 다운로드 상품만 있는 주문은 WooCommerce의 기본 동작에 따라 완료됨 상태가 됩니다.

On hold: PayU가 결제를 대기 중으로 보고하거나(현금 또는 은행 결제), 결제 금액 또는 통화가 주문 총액과 일치하지 않거나, 취소된 주문의 결제가 승인된 경우입니다. 주문 메모에 해당 사유가 표시됩니다. PayU 모듈에서 결제를 확인한 후 주문을 처리하거나 복원하거나 결제를 환불하세요.

Failed: 최근 결제 시도가 거절되거나 만료되거나 오류로 끝났습니다. 메모에는 PayU 메시지가 표시됩니다. 고객은 다시 결제할 수 있습니다. 이전 시도의 거절이나 이미 승인된 결제가 있는 주문의 거절은 메모로만 추가됩니다.

각 알림은 주문별 잠금하에 한 번만 처리됩니다. 반복되는 PayU 알림은 메모, 재고 차감 또는 이메일 발송을 중복시키지 않습니다. 다른 요청이 주문을 너무 오래 업데이트하고 있으면 확인에 오류로 응답하고 PayU가 나중에 다시 보냅니다. 결제 완료, 완료 또는 환불된 주문은 다시 열리지 않습니다. 이미 결제한 주문에 또 다른 승인 결제가 도착하면 메모로 알립니다. 고객이 두 번 결제했다면 PayU 모듈에서 중복 결제를 환불하세요.

환불

WooCommerce에서는 환불하지 않습니다. PayU 모듈에서 거래를 환불하고 필요하면 WooCommerce에 환불을 수동으로 기록하세요.

라이선스 키

플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Payments > PayU LATAM 상단에 있습니다. License key에 키를 붙여 넣고 Activate를 클릭합니다. 블록에는 라이선스 유효 종료일과 도메인 등 상태가 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하고, Remove key로 이 사이트에서 키를 제거합니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

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

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

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

문제 해결

체크아웃에 PayU LATAM이 표시되지 않음: 라이선스가 활성화되어 있고 Enable/Disable가 켜져 있으며 현재 환경의 가맹점 ID, 계정 ID 및 API 키가 입력되어 있는지 확인하세요. Sandbox가 켜져 있으면 샌드박스 자격 증명, 꺼져 있으면 운영 자격 증명입니다. 쇼핑몰 통화(주문 결제 페이지에서는 주문 통화)가 ARS, BRL, CLP, COP, MXN, PEN 또는 USD인지 확인하세요. 설정 페이지는 각 문제에 대해 경고를 표시합니다.

결제는 이루어졌지만 주문이 Pending payment로 유지됨: PayU 확인이 쇼핑몰에 도착하지 않았거나 거부되었습니다. 설정의 확인 URL에 인터넷에서 접근할 수 있는지 확인하세요(로컬 사이트, 유지보수 모드, 방화벽 또는 비밀번호 보호로 막히면 안 됨). WooCommerce > Status > Logs의 소스 wcp_payu_latam_payment에서 거부된 확인을 살펴보세요. PayU는 오류 응답을 받으면 확인을 다시 보냅니다.

확인 응답이 Invalid signature임: 결제 환경의 API 키로 확인이 서명되지 않았습니다. 운영 결제는 API Key, 샌드박스 결제는 Sandbox API key를 확인하세요.

확인 응답이 Merchant mismatch임: 확인의 가맹점 ID가 결제 환경의 Merchant ID 또는 Sandbox merchant ID와 다릅니다. 결제를 처리하는 PayU 계정의 가맹점 ID를 입력하세요.

확인 응답이 Gateway not configured임: 결제 환경의 API 키 또는 가맹점 ID가 없습니다. 예를 들어 샌드박스 결제가 대기 중일 때 샌드박스 자격 증명이 제거된 경우입니다. 다시 입력하면 PayU가 확인을 재시도합니다.

확인 응답이 Busy, retry later임: 다른 요청이 동시에 주문을 업데이트하고 있었습니다. 아무것도 변경되지 않았으며 PayU가 확인을 다시 보냅니다.

확인 응답이 Unknown reference임: 결제 참조가 이 쇼핑몰의 PayU LATAM 주문에 속하지 않습니다. 예를 들어 주문의 결제 수단이 바뀌었거나 주문이 삭제된 경우입니다.

주문이 On hold임: 주문 메모를 읽어 보세요. PayU에서 결제가 아직 대기 중이거나(현금 또는 은행 결제), 결제 금액이나 통화가 주문과 달랐거나, 주문 취소 후 결제가 도착한 경우입니다. PayU 모듈에서 거래를 확인하세요.

기타 통화 또는 양식 필드: 개발자는 payu_lp_supported_currencies 필터로 통화 목록을, payu_lp_icon 필터로 체크아웃 아이콘을, payu_lp_payment_fields 필터로 WebCheckout 양식 필드를 변경할 수 있습니다.

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

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화하고 삭제합니다. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 제거됩니다. 게이트웨이 설정과 로그는 Delete data가 켜져 있었을 때만 제거됩니다. 그렇지 않으면 이후 재설치를 위해 유지됩니다. 기존 주문에는 결제 메모, PayU 참조 및 거래 ID가 남습니다.

PayU는 해당 소유자의 상표입니다. 이 플러그인은 PayU와 제휴되어 있지 않으며 PayU의 보증을 받지 않습니다.