VibeFox Quickpay for WooCommerce — 도움말

요구 사항

WordPress: 6.2 이상.

WooCommerce: 7.1 이상, 설치 및 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인이 활성화되지 않습니다.

PHP: 8.0 이상.

Quickpay 계정: Quickpay 관리자에서 두 가지 값이 필요합니다. 결제 생성, 캡처 및 환불에 사용하는 API 사용자의 API 키와, Quickpay 콜백의 서명을 확인하는 데 사용하는 계정의 개인 키입니다. Quickpay에서는 그 밖에 설정할 것이 없습니다. Quickpay 콜백이 도착할 수 있도록 사이트는 인터넷에서 접근 가능해야 하며, 비밀번호 보호나 유지 보수 모드가 걸려 있으면 안 됩니다.

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

설치

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

2. Activate를 클릭합니다.

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

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

5. Quickpay 관리자에서 API 키와 개인 키를 붙여넣고 Test API key를 클릭합니다(설정 참조).

6. 캡처 방식과 결제 후 주문 상태를 선택하고, Enable/Disable을 켠 뒤 저장합니다. Quickpay 계정이 테스트 모드인 동안에는 Test payments를 켜고 Quickpay 테스트 카드로 결제합니다.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Quickpay. API 키와 개인 키를 모두 입력하기 전까지 Quickpay는 결제 수단 목록에서 설정이 필요한 것으로 표시되고, 결제를 생성하거나 확인할 수 없으므로 체크아웃에서 숨겨집니다.

일반

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

Title: 고객이 체크아웃에서 보는 결제 수단 이름입니다. 기본값: Quickpay.

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely by card or MobilePay on the Quickpay payment page.

Quickpay API 자격 증명

Quickpay 관리자(manage.quickpay.net)에서 Settings > Integration을 엽니다. API 사용자의 API 키(Settings > Users)와 계정의 개인 키를 복사합니다. 이 섹션에는 쇼핑몰의 콜백 URL도 표시되며, https://your-site/wc-api/qpg_quickpay/처럼 생겼습니다. 이 URL은 모든 결제에 자동으로 전송되므로 Quickpay에서 설정할 것은 없습니다.

API key: Quickpay API 사용자의 API 키입니다. 결제 생성, 캡처 및 환불에 사용됩니다.

필드 아래의 Test API key 버튼은 필드에 입력한 키(필드가 비어 있으면 저장된 키)를 인증된 요청으로 Quickpay에 확인합니다. 응답은 Connection successful — the API key is valid., Quickpay rejected the API key., API key is not configured. 또는 Connection failed: 뒤에 이유가 표시됩니다.

Private key: 계정의 개인 키입니다. Quickpay 콜백의 서명(HMAC-SHA256)을 확인하는 데 사용됩니다. 이 키가 없으면 어떤 결제도 확인되지 않으며 콜백은 거부됩니다.

Test payments: Accept payments made with Quickpay test cards. Quickpay에는 별도의 샌드박스가 없습니다. Quickpay 계정이 테스트 모드인 동안에는 결제가 테스트 카드로 이루어지고 테스트로 표시됩니다. 테스트하는 동안에만 켜십시오. 꺼져 있으면 테스트 결제로는 주문이 결제 완료로 표시되지 않고, 대신 주문에 메모가 남습니다. 켜져 있으면 체크아웃에 Test mode: Quickpay test cards are accepted.가 표시됩니다. 기본값: 끔.

결제

Capture: 카드에서 돈이 인출되는 시점입니다.

Order status after payment: Quickpay가 캡처된 결제를 확인한 후의 주문 상태입니다. 상태는 한 번에 설정되며, 상태 변경은 한 번, 이메일은 한 세트만 발송됩니다.

고급

Debug log: Enable logging. 로그는 WooCommerce > Status > Logs에 있으며, 소스는 wcp_quickpay_gateway입니다. 거부된 콜백, Quickpay API 오류와 같은 오류 및 경고는 항상 기록됩니다. 켜면 모든 요청과 콜백도 기록됩니다. API 키, 카드 데이터, 고객 정보는 절대 기록되지 않습니다. 기본값: 끔.

Delete data: Delete the gateway settings and logs when the plugin is deleted. 플러그인을 비활성화해도 아무것도 삭제되지 않습니다. 주문 데이터(Quickpay 결제 ID, 메모)는 항상 보존됩니다. 기본값: 끔.

체크아웃

고객은 결제 수단을 선택하고(기본값 Quickpay, Visa 및 Mastercard 아이콘과 함께 표시됨) 주문을 합니다. 플러그인은 주문 통화로 주문용 Quickpay 결제를 만들고, 주문 총액에 대한 결제 링크를 생성한 뒤, 고객을 Quickpay 결제 창으로 보냅니다. 고객은 Quickpay 결제 창에서 활성화된 방법 중 하나로 결제합니다. 청구 이메일은 Quickpay에 전달됩니다. Quickpay가 지원하는 경우 결제 창은 쇼핑몰 언어로 열립니다(덴마크어, 독일어, 영어, 스페인어, 핀란드어, 프랑스어, 이탈리아어, 네덜란드어, 노르웨이어, 폴란드어, 스웨덴어). 그 밖의 경우에는 영어로 열립니다.

결제 후 고객은 쇼핑몰의 주문 접수 페이지로 돌아갑니다. 돌아오는 것만으로는 아무것도 결제 완료로 표시되지 않습니다. 주문은 Quickpay가 서명된 콜백으로 확인하고 금액과 통화가 주문과 일치할 때에만 결제 완료로 표시됩니다. Authorize only를 사용하면 주문은 대신 보류 상태가 되며, 결제는 나중에 캡처합니다.

체크아웃 중 고객이 결제 창에서 취소하면, 결제되지 않은 주문은 WooCommerce 표준 방식으로 취소되고 장바구니가 복원됩니다. Pay for order 페이지에서 취소하면 고객은 그 페이지로 돌아가므로 주문은 여전히 결제 가능한 상태입니다. 실패했거나 취소된 결제는 다시 시도할 수 있습니다. 새 시도는 주문의 기존 Quickpay 결제를 새 링크와 함께 재사용하므로, 이전 링크로 병렬 결제가 이루어질 수 없습니다. 결제되지 않은 주문이 취소되면 그 결제 링크는 Quickpay에서 삭제됩니다.

결제를 시작할 수 없으면 고객은 The Quickpay payment could not be started. Please try again or choose another payment method.를 봅니다. 기술적인 이유는 주문 메모와 로그에 추가됩니다. 키가 없으면 고객은 Quickpay is not available at the moment. Please choose another payment method.를 봅니다.

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

이 플러그인은 일회성 결제만 지원합니다. 구독이나 정기 결제, 저장된 카드, 결제 수수료가 없으며, 장바구니나 청구서 항목을 Quickpay로 보내지 않습니다. 별도의 MobilePay, Apple Pay, Klarna 방식도 없습니다. 고객은 Quickpay 결제 창의 방식 중에서 선택합니다.

주문 및 환불

주문 상태

Pending payment: 고객이 Quickpay로 이동했지만 아직 결제하지 않았습니다. 자동 캡처에서는 캡처를 기다리는 승인된 결제가 주문에 기록됩니다.

Processing or Completed: Quickpay가 올바른 금액과 통화로 캡처된 결제를 확인했습니다. 상태는 Order status after payment를 따릅니다. 주문 메모에는 Quickpay 결제 ID가 표시되며(테스트 결제는 TEST로 표시), 주문의 거래 ID로 저장됩니다.

On hold: 결제는 승인만 된 상태이며 Capture Quickpay payment를 기다리고 있습니다. 또는 Quickpay가 주문 총액과 다른 금액이나 통화를 보고했습니다(예: 결제 시작 후 주문이 수정되었거나, Quickpay 관리자에서 다른 금액이 캡처된 경우). 또는 캡처가 실패해 금액이 여전히 예약 상태에만 있습니다. 주문 메모가 이를 설명하며, 주문이 이미 보류 상태였던 경우에도 마찬가지입니다.

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

Cancelled: 고객이 결제 창에서 취소했거나, 주문이 귀하 또는 WooCommerce 재고 보유 시간 초과로 취소되었거나, 결제가 Quickpay 관리자에서 취소되었습니다.

이미 결제 완료, 취소 또는 환불된 주문에 대해 들어온 결제는 주문을 변경하지 않습니다. 메모는 예를 들어 이중 결제를 환불하기 위해 Quickpay 관리자에서 결제를 확인하라고 알려 줍니다.

캡처

Authorize only를 사용한 경우 주문을 열고, 주문 작업에서 Capture Quickpay payment를 선택한 뒤 업데이트 버튼을 클릭합니다. 주문 총액이 캡처됩니다. 부분 캡처는 사용할 수 없습니다. Quickpay가 즉시 확인하면 주문은 결제 완료로 표시됩니다. 그렇지 않으면 메모에 캡처가 요청되었다고 표시되며, Quickpay 콜백이 확인하면 주문이 결제 완료로 표시됩니다. 거부된 캡처는 주문 화면에 표시되고 주문 메모에 기록됩니다.

승인된 주문을 취소해도 예약된 금액은 자동으로 해제되지 않습니다. 주문 메모는 Quickpay 관리자에서 결제를 취소하라고 알려 줍니다. 그렇지 않으면 승인이 만료될 때 예약이 끝납니다.

환불

주문을 열고 Refund를 클릭한 뒤 금액을 입력하고 Refund via Quickpay를 클릭합니다. 캡처된 결제에 대해 전액 및 부분 환불을 지원합니다. Quickpay는 환불을 비동기로 처리합니다. 메모는 환불이 요청되었다고 알려 주고, 콜백이 최종 결과인 confirmed 또는 사유가 포함된 FAILED를 추가합니다. Quickpay가 환불을 즉시 거부하면 WooCommerce가 오류를 표시하고 환불이 기록되지 않습니다. 한 번도 캡처되지 않은 승인된 결제는 환불할 수 없으며, 이 경우 Quickpay 관리자에서 취소하십시오.

Quickpay 관리자에서 직접 이루어진 결제와 환불은 주문에 메모로만 기록됩니다. WooCommerce 환불로 자동 기록되지는 않습니다. 필요하면 Refund via Quickpay 없이 WooCommerce에서 수동 환불을 만드십시오.

라이선스 키

이 플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Payments > Quickpay 상단에 있습니다. 키를 License key에 붙여넣고 Activate를 클릭합니다. 블록에는 상태가 표시되며, 예를 들어 라이선스가 유효한 날짜와 도메인이 나타납니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하고, Remove key로 이 사이트에서 키를 제거할 수 있습니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

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

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

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

문제 해결

Quickpay가 체크아웃에 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, API key와 Private key가 모두 입력되었는지 확인하십시오. 두 키가 모두 없으면 결제 수단이 숨겨집니다.

결제는 완료되었지만 주문이 Pending payment 상태로 남아 있음: Quickpay 콜백이 쇼핑몰에 도달하지 않았거나 거부되었습니다. 사이트가 인터넷에서 접근 가능한지(비밀번호 보호나 유지 보수 모드가 아닌지)와, Private key가 같은 Quickpay 계정의 개인 키인지 확인하십시오. 거부된 콜백은 항상 WooCommerce > Status > Logs에 소스 wcp_quickpay_gateway로 기록됩니다. 모든 콜백을 보려면 Debug log를 켜십시오.

로그에 Callback rejected: invalid checksum.이 표시됨: 설정의 개인 키가 콜백을 보낸 계정의 것이 아닙니다. Quickpay 관리자의 Settings > Integration에서 다시 복사하십시오.

로그에 Callback rejected: the private key is not configured.이 표시됨: 개인 키를 입력하십시오. 개인 키 없이는 콜백이 절대 수락되지 않습니다.

로그에 Callback: no order found for payment …이 표시됨: 이 콜백은 이 쇼핑몰의 어떤 주문도 알지 못하는 Quickpay 결제에 속합니다. 예를 들어 WooCommerce 외부에서 만들어졌거나 삭제된 주문에 대한 결제입니다.

로그에 Callback: order #… is locked by another request.이 표시됨: 같은 주문의 다른 콜백이 그 순간 적용되고 있었습니다. 이 콜백에는 오류 응답이 전달되므로 처리된 것으로 간주되지 않습니다. 주문이 그대로라면 Quickpay 관리자에서 결제를 확인하십시오.

테스트 결제가 주문을 결제 완료로 표시하지 않음: Test payments가 꺼져 있습니다. 주문 메모에 테스트 결제가 수락되지 않았다고 표시됩니다. 테스트할 때는 설정을 켜고, 계정이 실서비스로 전환되면 끄십시오.

결제 후 주문이 On hold 상태임: 주문 메모를 읽으십시오. 결제가 승인만 되었고 Capture Quickpay payment를 기다리는 중일 수 있습니다. 결제된 금액이나 통화가 주문과 다를 수 있거나, 캡처가 실패했을 수 있습니다. Quickpay 관리자에서 캡처하거나, 주문을 처리하거나, 결제를 환불하십시오.

Test API key가 Quickpay rejected the API key.라고 표시함: 키가 잘못되었거나 API 접근 권한이 없는 사용자의 키입니다. Quickpay 관리자에서 API 사용자의 API 키를 복사하십시오.

고객이 The Quickpay payment could not be started.를 봄: 주문 메모나 로그를 여십시오. 메모에 Quickpay 오류가 표시됩니다. 예를 들어 Quickpay 계정이 허용하지 않는 통화일 수 있습니다.

환불이 실패함: 주문에 캡처된 Quickpay 결제가 있어야 합니다. The Quickpay payment of this order has not been captured — there is nothing to refund. 메시지는 결제가 승인만 되었다는 뜻입니다. 대신 Quickpay 관리자에서 취소하십시오.

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

삭제

플러그인을 비활성화하면 모든 데이터가 보존됩니다. 완전히 제거하려면 Plugins 페이지에서 비활성화한 뒤 삭제하십시오. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 제거됩니다. 게이트웨이 설정과 플러그인 로그(로테이션된 파일을 포함한 로그 파일과 데이터베이스 로그 항목)는 Delete data가 켜져 있었을 때만 제거됩니다. 그렇지 않으면 나중에 재설치할 수 있도록 보존됩니다. 기존 주문은 결제 메모와 거래 ID를 유지합니다.

Quickpay는 해당 소유자의 상표입니다. 이 플러그인은 Quickpay와 제휴하거나 Quickpay의 승인을 받은 것이 아닙니다.