VibeFox Paytrail for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

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

PHP: 8.0 이상.

쇼핑몰 통화: EUR. Paytrail은 유로만 지원합니다. 다른 통화의 경우 체크아웃 시 결제 수단이 숨겨집니다. 금액은 센트 단위로 전송됩니다.

사이트 인터넷 접속: Paytrail은 서버 간 콜백으로 모든 결제를 확인하므로, 사이트가 인터넷에서 접근 가능해야 합니다. 콜백이 없더라도 고객이 Paytrail에서 복귀할 때 주문이 확인됩니다.

Paytrail 계정: Paytrail Merchant Panel(계정 또는 연동 상세 정보)에 표시되는 Merchant ID와 Secret key가 필요합니다. 테스트에는 별도의 계정이 필요하지 않으며, 테스트 모드는 Paytrail의 공개 테스트 계정을 사용합니다. 실제 결제 수단은 귀하의 Paytrail 계정에서 활성화합니다.

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

설치

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

2. Activate를 클릭하세요.

3. 설정을 엽니다: WooCommerce > Settings > Payments > Paytrail > Manage로 이동하거나, 플러그인 페이지의 플러그인 이름 아래에서 Settings를 클릭하세요.

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

5. 플러그인을 먼저 시험해보려면 Test mode를 체크하세요. 실제 결제를 받으려면 체크를 해제하고 Merchant ID와 Secret key를 입력하세요. Paytrail에서 콜백 URL을 따로 설정할 필요는 없습니다.

6. Enable/Disable을 켜고 저장하세요.

설정

모든 설정은 WooCommerce > Settings > Payments > Paytrail 한 페이지에 있습니다. 테스트 모드가 켜져 있는 동안 필드 상단에 Test mode is active.가 표시됩니다. 라이브 모드에서는 Merchant ID 또는 Secret key가 누락되었을 때 경고가 표시되며, 쇼핑몰 통화가 EUR이 아닌 경우에도 경고가 표시됩니다. 두 경우 모두 체크아웃 시 Paytrail이 표시되지 않습니다. 결제 수단 목록에서 라이브 모드의 자격 증명이 없는 동안 Paytrail은 설정 필요로 표시됩니다.

저장 시 숫자 이외의 문자가 포함된 Merchant ID는 저장되지 않으며, 오류가 표시되고 이전 값이 유지됩니다.

General

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

Title: 체크아웃 시 고객에게 표시되는 제목입니다. 기본값: Paytrail.

Description: 체크아웃 시 고객에게 표시되는 안내 문구입니다. 기본값: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

API credentials

Merchant ID와 Secret key는 Paytrail Merchant Panel(계정 또는 연동 상세 정보)에 표시됩니다. EUR 결제만 지원됩니다.

Test mode: Use the Paytrail test account. 새로운 결제는 자체 자격 증명 대신 Paytrail의 공개 테스트 계정(Merchant ID 375917)을 사용합니다. 실제 금액은 청구되지 않습니다. 고객은 체크아웃 시 Test mode: no real payment will be made. 문구를 보게 됩니다. 테스트 계정의 Secret key는 공개되어 있으므로 누구나 테스트 모드 주문에 대해 결제를 시뮬레이션할 수 있습니다. 운영 중인 쇼핑몰에서는 테스트 모드를 켜두지 마세요. 기본값: 끔.

Merchant ID: 귀하의 Paytrail 가맹점 ID(숫자만 입력). 테스트 모드가 꺼져 있을 때 사용됩니다.

Secret key: 귀하의 Paytrail 비밀 키. 테스트 모드가 꺼져 있을 때 사용됩니다.

콜백과 환불은 항상 결제가 이루어진 당시 모드의 자격 증명을 사용하므로, 테스트 모드와 라이브 모드를 전환해도 이전 주문 처리에 문제가 발생하지 않습니다.

Orders

이 섹션에는 https://your-site/wc-api/ptg_paytrail/ 형태의 콜백 URL이 표시됩니다. Paytrail은 이 URL로 서버 간 호출을 보내 모든 결제를 확인합니다. 매 결제 시마다 URL이 함께 전송되므로 Paytrail 관리자 패널에서 별도로 구성할 필요는 없지만, 사이트가 인터넷에서 접속 가능해야 합니다.

Order status after payment: 결제 완료된 주문의 상태입니다. 상태가 한 번에 설정되므로 고객은 이메일을 한 세트만 받게 됩니다.

Advanced

Debug log: Log API requests and callbacks. 개인정보나 키를 제외하고 WooCommerce > Status > Logs(소스: wcp_paytrail_gateway)에 기록됩니다. 오류는 항상 기록됩니다. 기본값: 끔.

Delete data on uninstall: Delete settings, logs and Paytrail order data when the plugin is deleted. 플러그인을 비활성화해도 데이터는 삭제되지 않습니다. Paytrail 거래 데이터가 없으면 이전 주문의 환불을 WooCommerce에서 더 이상 진행할 수 없습니다. 기본값: 끔.

체크아웃

고객은 결제 수단(기본값 Paytrail)을 선택하고 주문을 진행합니다. 플러그인은 유로화 주문 합계에 대해 Paytrail 결제를 생성하고 주문 항목(상품, 배송비, 수수료)을 소수점 한 자리 부가가치세율과 함께 전송합니다. 항목들의 합계는 항상 결제 금액과 일치하며, 반올림 차이는 특정 항목에 합산되거나 Rounding 항목으로 전송됩니다. 청구지 및 배송지 주소는 완전히 입력된 경우에만 전송되며, 길이가 긴 값은 Paytrail의 제한에 맞게 축소됩니다. 결제 페이지 언어는 쇼핑몰 언어 설정에 따라 핀란드어, 스웨덴어 또는 영어로 설정됩니다.

고객은 Paytrail 결제 페이지로 이동하여 귀하의 Paytrail 계정에 활성화된 결제 수단을 선택하고 결제합니다. 그런 다음 Paytrail은 고객을 쇼핑몰로 돌려보내고 서버 간 콜백 URL을 호출하는 두 가지 방식으로 결제를 확인합니다. 둘 다 해당 결제 시도의 자격 증명으로 생성된 유효한 서명이 있고, 해당 주문을 위해 생성된 시도인 경우에만 수락됩니다. 결제된 금액은 주문 합계와 대조됩니다. Paytrail이 이러한 방식으로 확인한 후에만 주문이 결제 완료로 표시됩니다. 플러그인은 다음과 같은 Paytrail 상태를 처리합니다:

결제가 성공하면 고객에게 주문 완료 페이지가 표시됩니다. 취소되거나 실패한 결제 후에는 The Paytrail payment was cancelled or failed. You can try again or choose another payment method. 메시지와 함께 Pay for order 페이지로 이동합니다. 결제가 아직 완료되지 않은 경우 The Paytrail payment has not been completed yet. You can try again or choose another payment method. 메시지가 표시됩니다.

Paytrail이 결제를 시작할 수 없는 경우, 고객에게 Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method.(잘못된 자격 증명) 또는 Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method.와 같은 간단한 메시지가 표시됩니다. 기술적인 원인은 주문 메모와 로그에 기록됩니다. Paytrail의 최대 한도를 초과하는 주문은 Paytrail로 결제할 수 없습니다.

Paytrail 결제는 API를 통해 취소할 수 없습니다. 고객이 새 결제를 시작한 후 아직 열려 있는 이전 결제 페이지에서도 결제를 완료한 경우, 두 번째 결제는 환불 대상 중복 결제로 주문 메모에 보고됩니다.

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

고객은 쇼핑몰 체크아웃이 아닌 Paytrail 페이지에서 결제 수단을 선택합니다. 이 플러그인은 카드 토큰화 및 카드 저장, WooCommerce Subscriptions, 숍인숍, 수동 청구서 활성화 및 정산 보고서를 지원하지 않습니다.

주문 및 환불

주문 상태

Pending payment: Paytrail 결제가 생성되었으며 고객이 아직 결제하지 않았습니다. 주문 메모에는 Paytrail 거래 ID, 금액 및 모드가 표시됩니다.

Processing or Completed: 결제가 확인되었습니다. 상태는 Order status after payment 설정을 따릅니다. 주문 메모에는 거래, Paytrail에서 사용된 결제 수단 및 금액이 표시됩니다. 거래 ID는 Paytrail 거래 ID입니다.

On hold: 대행사에서 결제 대기 중(청구서 또는 지연 결제), 결제 금액이 주문 합계와 불일치, 주문 취소 후 결제 도착, 또는 쇼핑몰 운영 중에 테스트 결제 수신(실제 금액 아님)된 경우입니다. 주문 메모에 이유가 설명됩니다. 주문을 확인한 후 처리하거나 결제를 환불하세요.

Failed: 가장 최근의 결제 시도가 실패했거나 고객에 의해 취소되었습니다. 고객은 다시 결제할 수 있습니다.

반복되거나 병렬로 들어오는 콜백이 중복 메모, 재고 감소 또는 이메일을 생성하지 않습니다. 이미 결제 완료된 주문의 두 번째 시도가 결제된 경우, 주문은 다시 변경되지 않으며 Duplicate payment 메모를 통해 Paytrail Merchant Panel에서 환불하도록 안내합니다.

환불

주문을 열고 Refund를 클릭한 후 금액을 입력하고 Refund via Paytrail을 클릭하세요(버튼에는 설정한 Title이 표시됩니다). 전액 및 부분 환불이 지원되며 금액에 대해서만 환불됩니다(환불 품목 행 없음). 이 버튼은 확인된 Paytrail 결제가 있는 주문에서만 사용할 수 있습니다. 환불은 결제가 진행된 모드의 자격 증명을 사용하므로 라이브 결제 환불을 위해서는 라이브 자격 증명이 설정되어 있어야 합니다.

결제 수단이 직접 환불을 지원하지 않는 경우, 플러그인이 자동으로 이메일 환불을 시작합니다. Paytrail이 고객에게 은행 계좌를 입력하도록 이메일을 보냅니다. 이를 위해 주문에 청구지 이메일이 필요합니다. 주문 메모에 어떤 종류의 환불이 시작되었는지 표시됩니다.

환불은 즉시 완료되거나 나중에 처리될 수 있습니다. Paytrail의 후속 확인은 메모로 추가됩니다. Paytrail이 환불을 완료하지 못한 경우 고객에게 금액이 반환되지 않았다는 메모가 남으므로, 다른 방법으로 환불하고 WooCommerce 환불 내역을 삭제하세요. Paytrail이 환불을 즉시 거부하면 WooCommerce에 오류가 표시되고 환불이 기록되지 않습니다.

Paytrail Merchant Panel에서 진행한 환불은 WooCommerce로 동기화되지 않습니다.

라이선스 키

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

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

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

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

문제 해결

체크아웃 시 Paytrail이 나타나지 않음: 라이선스가 활성화되어 있는지, Enable/Disable이 켜져 있는지, Test mode가 켜져 있거나 Merchant ID 및 Secret key가 입력되어 있는지 확인하세요. 상점 통화(또는 Pay for order 페이지의 주문 통화)가 EUR인지 확인하세요. 설정 페이지에는 이러한 각 문제에 대한 경고가 표시됩니다.

결제는 완료됐지만 주문이 Pending payment 상태로 남아 있음: 콜백이 사이트에 도달하지 못했고 고객이 상점으로 돌아오지 않았습니다. Orders 섹션에 표시된 콜백 URL이 인터넷에서 접속 가능해야 합니다(유지보수 모드, 기본 인증 또는 방화벽 차단 없음).

콜백 또는 복귀 시 Payment verification failed. 응답: 서명이 유효하지 않거나 결제가 해당 주문의 결제 시도에 속하지 않습니다. 주문은 변경되지 않습니다. Secret key가 올바르고 Merchant ID에 해당하는지 확인하세요.

결제가 생성되지 않음: 잘못된 자격 증명의 경우 주문 메모 및 로그에 Paytrail API error (401): …과 같은 Paytrail 오류가 표시됩니다. Debug log를 켜고 WooCommerce > Status > Logs(소스: wcp_paytrail_gateway)를 확인하세요.

Merchant ID가 저장되지 않음: 숫자만 포함되어야 합니다. Paytrail Merchant Panel에서 다시 복사해 오세요.

주문이 On hold 상태임: 주문 메모를 확인하세요. 대기 중 또는 지연된 결제, 일치하지 않는 결제 금액, 취소 후 결제 또는 라이브 모드에서의 테스트 결제가 원인입니다.

환불 실패: 메시지를 확인하세요. This order has no confirmed Paytrail payment. Refund it manually.는 환불할 확인된 Paytrail 결제가 없음을 의미합니다. 라이브 자격 증명 누락에 대한 메시지는 결제가 라이브 모드에서 이루어졌으나 라이브 자격 증명이 설정되지 않았음을 의미합니다. 결제 수단이 이메일 환불만 지원하는 경우 주문에 청구지 이메일이 필요합니다.

개발자 훅: ptg_payment_request 필터는 결제 요청이 서명되어 전송되기 전에 요청을 수정하며, ptg_icon 필터는 체크아웃 아이콘을 수정합니다.

라이선스 블록에 오류가 표시됨: 블록의 안내 메시지를 따르세요. 예를 들어 키가 이미 다른 도메인에서 사용 중인 경우 vibefox.net 계정에서 슬롯을 비우고 Check now를 클릭하세요. 사이트 주소가 변경된 경우 Check now를 클릭하여 새 도메인에 키를 활성화하세요. 라이선스 서버에 연결할 수 없는 경우 플러그인은 마지막으로 알려진 상태를 기준으로 계속 작동합니다.

제거

플러그인을 비활성화해도 모든 데이터가 유지됩니다. 완전히 제거하려면 Plugins 페이지에서 비활성화한 후 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정, 이 플러그인의 로그, 주문에 저장된 Paytrail 데이터(결제 시도, 거래 데이터, 환불 기록)는 Delete data on uninstall이 켜져 있었던 경우에만 삭제됩니다. 그렇지 않은 경우 추후 재설치를 위해 보존됩니다. 기존 주문은 결제 메모와 거래 ID를 유지하지만, Paytrail 데이터가 없으면 이전 주문을 WooCommerce에서 더 이상 환불할 수 없습니다.

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