VibeFox TrustPay for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

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

PHP: 8.0 이상.

finby(TrustPay) 계정: finby Merchant Portal에 Project ID와 Secret key가 있는 프로젝트가 필요합니다. 테스트 결제에는 별도의 테스트(playground) 프로젝트가 필요하며, 이 프로젝트도 자체 Project ID와 Secret key를 가집니다. 다른 키는 필요하지 않습니다. Secret key는 API 접근 권한을 얻는 데에도, 결제 알림의 서명을 확인하는 데에도 사용됩니다.

접근 가능한 알림 URL: finby가 인터넷을 통해 귀사의 사이트에 접근할 수 있어야 합니다. 방화벽, 유지 보수 모드 또는 사이트 비밀번호 보호는 결제 알림을 차단합니다.

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서만 사용할 수 있습니다.

설치

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

2. Activate를 클릭합니다.

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

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

5. 실서비스 프로젝트의 Project ID와 Secret key를 입력하고, 테스트를 하려면 테스트 프로젝트의 Project ID와 Secret key도 입력합니다(설정 항목 참조).

6. Enable / Disable을 켜고 저장합니다. Test mode를 켠 상태에서 테스트 결제를 한 뒤, 실제 결제를 받으려면 Test mode의 선택을 해제합니다.

버전 1.0에서 업데이트하는 경우, Project ID와 Secret key는 실서비스용 자격 증명으로 유지되고 테스트 모드는 꺼집니다. 업데이트 후 설정을 확인하십시오.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > TrustPay / finby. 게이트웨이가 활성화되어 있는데 현재 모드의 Project ID 또는 Secret key가 비어 있거나, 상점 통화가 지원되지 않으면 필드 위에 경고가 표시됩니다. 두 경우 모두 체크아웃에서 해당 결제 수단은 숨겨집니다. 결제 수단 목록에서는 현재 모드에 Project ID와 Secret key가 입력될 때까지 게이트웨이가 설정 필요 상태로 표시됩니다.

General

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

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

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

API credentials

finby(TrustPay) Merchant Portal에서 프로젝트의 Project ID와 Secret key를 복사합니다. 이 섹션에는 Merchant Portal 링크가 있습니다. 테스트 결제는 자체 Project ID와 Secret key를 가진 별도의 테스트(playground) 프로젝트를 사용합니다. 그곳에서는 실제 금액이 청구되지 않습니다.

Test mode: Use the test project (no real payments). 새 결제와 환불은 테스트 자격 증명을 사용합니다. 주문의 환불은 항상 그 주문을 결제한 프로젝트로 처리됩니다. 기본값: 켬.

Live Project ID: 실서비스 프로젝트의 숫자형 Project ID입니다.

Live Secret key: 실서비스 프로젝트의 Secret key입니다. API 접근 토큰을 얻고 결제 알림을 확인하는 데 사용됩니다.

Test Project ID: 테스트(playground) 프로젝트의 숫자형 Project ID입니다.

Test Secret key: 테스트 프로젝트의 Secret key입니다.

Project ID에는 숫자만 입력해야 합니다. 다른 값을 저장하면 페이지에 오류가 표시되고 이전 값이 유지됩니다. Secret key는 입력한 그대로 저장되며, 앞뒤 공백만 제거됩니다.

Payment notifications

주문은 finby가 서명된 알림으로 결제를 확인한 후에만 결제 완료로 표시됩니다. 플러그인은 결제할 때마다 알림 URL을 자동으로 전송하므로 따로 설정할 필요가 없습니다. 이 섹션에는 URL이 표시됩니다. 예: https://your-site/wc-api/trustpay_payment_callback/. Merchant Portal에서 프로젝트의 알림 URL로 입력할 수도 있습니다. 유효한 서명이 없는 알림은 거부됩니다.

플러그인은 스스로 finby에 결제 상태를 묻지 않습니다. 알림이 귀사의 사이트에 도달하지 못하면, finby가 알림을 다시 전달할 때까지 주문은 Pending payment 상태로 남습니다.

Advanced

Order status after payment: 결제 성공 후 설정되는 주문 상태입니다. 상태는 한 단계로 설정되므로 고객은 이메일을 한 번만 받습니다.

Debug logging: Log API requests and notifications는 로그에 자세한 내용을 추가합니다. 이 옵션이 꺼져 있어도 오류는 항상 기록됩니다. 로그는 WooCommerce > Status > Logs에 있으며, 소스는 wcp_trustpay_gateway입니다. 키, 토큰, 카드 데이터, 고객 정보는 포함되지 않습니다. 기본값: 끔.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (order data is kept). 기본값: 끔.

체크아웃

고객은 결제 수단(기본값 Card payment (TrustPay))을 선택하고 주문합니다. 테스트 모드에서는 체크아웃의 설명 아래에 Test mode: no real payment will be taken.이 표시됩니다.

카드 결제에는 청구지 주소가 필요합니다. 도로명, 도시, 우편번호 또는 국가가 빠져 있으면 고객에게 Please enter your billing address (street, city, postcode and country) — it is required for card payments.가 표시됩니다.

플러그인은 주문 금액에 대해 주문 통화로 finby에 카드 결제 요청을 생성합니다. 고객의 이름, 주소, 이메일은 3-D Secure를 위해 전송되며, 주문 ID는 참조 번호로 전송됩니다. 고객은 finby 결제 페이지로 리디렉션되어 그곳에서 카드로 결제합니다. finby가 지원하는 경우 페이지는 쇼핑몰 언어로, 지원하지 않으면 영어로 열립니다. 주문의 메모에는 결제 요청, 금액, 프로젝트(테스트 또는 실서비스)가 표시됩니다.

결제 후 고객은 쇼핑몰의 주문 접수 페이지로 돌아가고 장바구니는 비워집니다. 주문은 finby가 서명된 알림으로 확인한 후에만 결제 완료로 표시됩니다. 돌아오는 행위 자체는 결제 상태를 바꾸지 않습니다.

고객이 결제 페이지에서 취소하거나 결제 페이지가 오류를 반환하면, 고객은 Pay for order 페이지로 돌아가고 The card payment was cancelled. You can try again or choose another payment method. 또는 The card payment was not completed. Please try again or choose another payment method. 메시지를 보게 됩니다. 주문에는 메모가 추가됩니다. 고객은 이 페이지에서 다시 결제할 수 있습니다.

finby가 결제를 시작할 수 없으면 고객에게 We could not start the card payment. Please try again in a moment or choose another payment method.가 표시됩니다. 기술적인 이유는 로그에 기록됩니다.

통화: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF, USD. HUF 금액은 소수점 없이 전송됩니다. Pay for order 페이지에서는 주문 통화를 확인합니다.

이 결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다. 플러그인에는 영어, 슬로바키아어, 체코어 번역이 포함되어 있습니다.

이 플러그인은 finby 페이지에서 한 단계로 이루어지는 구매 형태로 카드 결제만 처리합니다. 계좌이체나 기타 finby 결제 수단, Apple Pay 또는 Google Pay 버튼, 카드 저장, 정기 구독이나 반복 결제, 승인과 매입의 분리, 상태 조회는 지원하지 않습니다.

주문 및 환불

주문 상태

Pending payment: 고객이 finby로 이동했지만 아직 결제하지 않았거나, 알림이 아직 도착하지 않은 상태입니다.

Processing or Completed: finby가 결제를 확인했고, 금액과 통화가 결제 요청 및 주문 합계와 일치하는 상태입니다. 상태는 Order status after payment 설정을 따릅니다. 주문 메모에는 금액, 결제 요청, 프로젝트가 표시됩니다. 거래 ID는 finby 결제 요청 ID입니다.

On hold: 세 가지 경우에 설정됩니다. 결제가 finby에서 아직 처리 중이어서 주문이 최종 결과를 기다리는 경우. 결제가 승인만 되고 매입되지 않은 경우: finby Merchant Portal에서 매입하거나 취소한 뒤 주문을 업데이트하십시오. 또는 결제된 금액이나 통화가 결제 요청이나 주문 합계와 다른 경우입니다. 예를 들어 고객이 결제 페이지로 이동한 후 주문이 수정된 경우입니다. 배송 전에 결제를 확인하십시오. 주문 메모에 자세한 내용이 설명되어 있습니다.

Failed: finby가 주문의 최근 결제를 거절한 상태입니다. finby가 사유를 보내는 경우 메모에 사유가 표시됩니다. 고객은 Pay for order에서 다시 결제할 수 있습니다.

취소되거나 환불된 주문은 늦게 도착한 결제로 다시 열리지 않습니다. 메모는 Merchant Portal에서 주문을 복원하거나 결제를 환불하라고 안내합니다. 이미 결제된 주문에 두 번째 결제가 들어오면 주문은 변경되지 않으며, 메모는 Merchant Portal에서 중복 결제를 환불하라고 안내합니다. finby가 보고한 차지백과 분쟁은 메모로 추가됩니다.

Refunds

주문을 열고 Refund를 클릭한 뒤 금액을 입력하고 Refund via Card payment (TrustPay)를 클릭합니다(버튼에는 귀사의 Title이 표시됩니다). 전액 및 부분 환불을 지원합니다. 환불은 주문을 결제한 프로젝트(테스트 또는 실서비스)로 처리됩니다. 그 이후에 모드를 바꾸었더라도 마찬가지입니다. 따라서 해당 모드의 Project ID와 Secret key가 설정되어 있어야 합니다. HUF 환불은 정수 금액이어야 합니다.

환불은 finby가 승인한 경우에만 기록됩니다. 그렇지 않으면 WooCommerce에 TrustPay refused the refund:와 사유가 표시되며 환불이 생성되지 않습니다. 성공한 환불은 주문 메모에 추가됩니다.

finby Merchant Portal에서 한 환불은 WooCommerce 환불로 기록되지 않습니다. 이와 관련한 알림을 finby가 보내면 주문 메모로 추가되며, 주문 상태는 바뀌지 않습니다.

라이선스 키

플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Payments > TrustPay / finby 상단에 있습니다. 키를 License key에 붙여넣고 Activate를 클릭합니다. 블록에는 라이선스가 유효한 날짜 등의 상태와 귀사의 도메인이 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하며, Remove key로 이 사이트에서 키를 제거합니다. Manage licenses and domains in your account 링크를 누르면 vibefox.net 계정이 열립니다.

키 하나는 도메인 하나에서만 사용할 수 있습니다. 사이트에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하십시오.

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

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

문제 해결

Card payment (TrustPay)가 체크아웃에 나타나지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 현재 모드에 Project ID와 Secret key가 있는지 확인하십시오. 테스트 모드에서는 Test Project ID와 Test Secret key, 실서비스 모드에서는 Live Project ID와 Live Secret key입니다. 상점 통화 또는 Pay for order 페이지의 주문 통화가 지원되는 통화 중 하나여야 합니다. 설정 페이지에는 두 경우 모두 경고가 표시됩니다. 개발자는 trustpay_p_supported_currencies 필터로 통화 목록을 변경할 수 있습니다.

결제는 완료되었지만 주문이 Pending payment 상태로 남음: 알림이 귀사의 쇼핑몰에 도달하지 못했습니다. https://your-site/wc-api/trustpay_payment_callback/에 인터넷에서 접근할 수 있는지 확인하십시오(방화벽, 유지 보수 모드, 비밀번호 보호가 없어야 합니다). finby는 알림을 다시 보냅니다. WooCommerce > Status > Logs를 확인하십시오. 소스는 wcp_trustpay_gateway입니다.

로그에 Notification rejected: invalid signature or unknown project가 표시됨: 알림이 Project ID가 설정에 없는 프로젝트에서 왔거나, 해당 프로젝트의 Secret key가 잘못되었습니다. 쇼핑몰은 Invalid signature로 응답하며 주문은 변경되지 않습니다. 결제가 이루어진 모드의 Project ID와 Secret key를 확인하십시오.

로그에 Notification ignored가 표시됨: 알림은 이 쇼핑몰이 해당 주문에 대해 만들지 않은 결제 요청이거나, 결제를 시작한 프로젝트와 다른 프로젝트에 속합니다. 주문은 변경되지 않습니다.

알림이 Busy, retry later 응답을 받음: 같은 시점에 다른 알림이 주문을 업데이트하고 있었습니다. finby가 다시 보냅니다.

고객이 We could not start the card payment를 봄: 로그를 여십시오. 잘못된 Project ID나 Secret key는 finby가 프로젝트 자격 증명을 거부했다는 메시지로 나타납니다. 테스트 자격 증명은 테스트 필드에, 실서비스 자격 증명은 실서비스 필드에 있는지 확인하십시오.

카드 결제를 일시적으로 사용할 수 없음: 현재 모드에 Project ID나 Secret key가 없으면 고객에게 이 메시지가 표시됩니다. 입력한 뒤 저장하십시오.

주문이 On hold이며 금액/통화 불일치 메모가 있음: 알림은 진짜였지만 결제된 금액이나 통화가 결제 요청이나 주문 합계와 다릅니다. 배송 전에 Merchant Portal에서 결제를 확인한 뒤, 주문을 처리하거나 결제를 환불하십시오.

환불이 프로젝트 관련 메시지와 함께 실패함: 주문은 테스트 또는 실서비스 프로젝트로 결제되었는데, 해당 모드의 Project ID나 Secret key가 설정되어 있지 않거나 지금 다른 Project ID가 저장되어 있습니다. 그 프로젝트의 자격 증명을 입력하거나, finby Merchant Portal에서 결제를 환불하십시오.

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

제거

플러그인을 비활성화해도 모든 데이터는 유지됩니다. 완전히 제거하려면 먼저 비활성화한 뒤 Plugins 페이지에서 삭제하십시오. 이 플러그인의 라이선스 키와 라이선스 상태, 그리고 캐시된 API 접근 토큰은 항상 삭제됩니다. 게이트웨이 설정과 플러그인 로그(이전에 교체된 파일을 포함한 로그 파일 및 데이터베이스의 로그 항목)는 Delete data on uninstall이 켜져 있을 때만 삭제됩니다. 그렇지 않으면 나중에 다시 설치할 수 있도록 유지됩니다. 주문 데이터는 유지됩니다. 기존 주문은 결제 메모, 결제 요청 ID, 거래 ID를 그대로 보존합니다.

TrustPay와 finby는 각 소유자의 상표입니다. 이 플러그인은 TrustPay 또는 finby와 제휴하거나 그들의 승인을 받은 제품이 아닙니다.