VibeFox Paytrail for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

통화: EUR. Paytrail은 유로만 받습니다. 다른 통화의 장바구니에서는 체크아웃에서 해당 결제 수단이 표시되지 않습니다. 금액은 센트 단위로 전송됩니다.

쇼핑몰의 인터넷 접근: Paytrail은 서버 간 콜백으로 모든 결제를 확인하므로, 쇼핑몰은 인터넷에서 접근 가능해야 합니다. 콜백이 없더라도 고객이 Paytrail에서 돌아오면 주문은 생성됩니다.

Paytrail 계정: Paytrail 가맹점 패널(계정 또는 연동 정보)에 표시되는 Merchant ID와 Secret key가 필요합니다. 테스트에는 계정이 필요하지 않습니다. 테스트 모드는 Paytrail의 공개 테스트 계정을 사용합니다. 결제 수단 자체는 Paytrail 계정에서 활성화합니다.

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

설치

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

2. 업로드가 끝나면 Configure를 클릭합니다. 나중에 모듈 목록에서 VibeFox Paytrail Gateway를 찾아 Configure를 클릭해도 됩니다.

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

4. 먼저 모듈을 시험해 보려면 Test mode를 켭니다. 실제 결제를 하려면 끄고 Merchant ID와 Secret key를 입력합니다. Paytrail에서 콜백 URL을 설정할 필요는 없습니다.

5. Enable/Disable을 켜고 Save를 클릭합니다.

설치 시 모듈은 두 가지 주문 상태, Awaiting Paytrail payment와 Paytrail payment on hold를 생성합니다. PrestaShop은 모든 통화, 국가 및 고객 그룹에 대해 새 결제 모듈을 제공합니다. Payment > Preferences에서 이를 제한할 수 있습니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Paytrail Gateway > Configure. 각 섹션에는 개별 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. 테스트 모드가 켜져 있는 동안에는 입력란 위에 Test mode is active. Payments use the public Paytrail test account — no real money is charged.가 표시됩니다. 실결제 모드에서는 Merchant ID 또는 Secret key가 없거나 Merchant ID가 공개 테스트 계정 375917인 경우 경고합니다. 쇼핑몰 통화가 EUR가 아닌 경우에도 경고합니다. 이러한 모든 경우 체크아웃에 Paytrail이 표시되지 않습니다.

저장 시 숫자 이외의 문자가 포함된 Merchant ID는 저장되지 않으며, Paytrail merchant ID must contain digits only. The previous value was kept. 오류가 표시됩니다. Title은 비워 둘 수 없습니다.

Paytrail

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

Title: 체크아웃에서 고객에게 표시되는 제목입니다. 주문에 저장되는 결제 수단 이름이기도 합니다. 기본값: Paytrail. 필수.

Description: 체크아웃에서 결제 수단 아래에 고객에게 표시되는 텍스트입니다. 기본값: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

API 자격 증명

Merchant ID와 Secret key는 Paytrail 가맹점 패널(계정 또는 연동 정보)에 표시됩니다. 이 섹션에는 가맹점 패널 링크가 있습니다. EUR 결제만 지원됩니다.

Test mode: 새 결제에 귀하의 자격 증명 대신 Paytrail의 공개 테스트 계정(Merchant ID 375917)을 사용합니다. 실제 금액은 청구되지 않으며 키도 필요하지 않습니다. 고객은 결제 수단 아래에서 Test mode: no real payment will be made.를 보게 됩니다. 테스트 계정의 Secret key는 공개되어 있으므로 누구든 테스트 모드의 결제를 흉내낼 수 있습니다. 실운영 쇼핑몰에서는 테스트 모드를 절대 켜 두지 마십시오. 기본값: off.

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

Secret key: 귀하의 Paytrail Secret key. 테스트 모드가 꺼져 있을 때 사용됩니다. 저장된 키는 다시 표시되지 않습니다. 입력란은 비어 있으며 Saved — leave empty to keep it.를 표시합니다. 변경하려는 경우에만 새 값을 입력하십시오.

Clear saved secret key: Secret key를 체크하고 Save를 클릭하면 저장된 키가 삭제됩니다. 입력란이 비어 있으면 저장된 값이 유지됩니다.

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

주문

Callback URL: Paytrail이 모든 결제를 서버 간에 확인하는 URL을 표시합니다. 친숙한 URL을 사용하는 경우 다음과 같습니다: https://your-shop/module/wcp_paytrail_gateway/callback. 매 결제와 함께 전송되므로 Paytrail 패널에서 따로 설정할 것은 없지만, 쇼핑몰은 인터넷에서 접근 가능해야 합니다.

Order status after payment: 결제 완료된 주문의 상태입니다.

대기 중인 결제는 Awaiting Paytrail payment에서 기다립니다. 금액 불일치 및 기타 문제는 항상 Paytrail payment on hold로 갑니다.

고급

Debug log: API 요청과 콜백을 모듈 폴더 안의 logs/ptg_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 개인정보와 키는 기록되지 않습니다. 오류와 경고는 항상 기록됩니다. 기본값: off.

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

Delete data on uninstall: 켜져 있으면 모듈을 제거할 때 설정과 로그가 삭제됩니다. 모듈을 비활성화해도 아무것도 삭제되지 않습니다. 주문의 Paytrail 거래 데이터는 이전 주문의 환불에 필요하므로 항상 보관됩니다. 기본값: off.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 Paytrail)을 선택하고 확인합니다. 모듈은 장바구니 합계에 대해 유로 기준 Paytrail 결제를 생성하고 주문 항목을 함께 전송합니다. 항목은 장바구니 규칙 적용 후의 상품, 배송비 및 선물 포장비이며, 각각 소수점 한 자리까지의 부가가치세율이 적용됩니다. 항목 금액의 합계는 항상 결제 금액과 정확히 일치하며, 반올림 차이는 한 항목에 합산되거나 Rounding 항목으로 전송됩니다. 청구지 주소와 배송지 주소는 완전한 경우에만 전송되며, 너무 긴 값은 Paytrail의 제한에 맞게 줄여집니다. 결제 페이지 언어는 장바구니 언어에 따라 핀란드어, 스웨덴어 또는 영어입니다. 이 시점에는 아직 주문이 존재하지 않습니다.

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

결제가 성공하면 고객은 Your Paytrail payment has been received. 문구가 있는 표준 주문 확인 페이지를 보게 됩니다. 대기 중인 결제의 경우 페이지에 Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again.가 표시됩니다. 콜백이 정확히 같은 순간에 결제를 기록하고 있다면, Payment confirmation 페이지가 고객에게 다시 결제하지 말 것을 요청하고 Check again 버튼을 제공합니다.

결제가 취소되거나 실패하면 고객은 체크아웃으로 돌아가 The Paytrail payment was cancelled or failed. You can try again or choose another payment method. 메시지를 보게 됩니다. 결제가 아직 완료되지 않은 경우 메시지는 The Paytrail payment has not been completed yet. You can try again or choose another payment method.입니다. 장바구니는 유지됩니다. 검증할 수 없는 복귀는 Payment verification failed.를 표시하며 아무것도 변경하지 않습니다.

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 제한을 벗어난 합계는 This order total cannot be paid with Paytrail. Please choose another payment method.를 표시합니다.

Paytrail 결제는 API를 통해 취소할 수 없습니다. 장바구니에 대한 새 시도마다 새로운 Paytrail 결제가 됩니다. 고객이 아직 열려 있는 이전 결제 페이지에서도 결제하면, 두 번째 결제는 주문에 환불 대상 중복 결제로 보고됩니다.

콜백은 쇼핑몰이 유지보수 모드일 때도 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다.

고객은 귀하의 체크아웃이 아닌 Paytrail 페이지에서 결제 수단을 선택합니다. 이 모듈에는 카드 토큰화나 저장된 카드, 정기결제, 숍인숍, 수동 청구서 활성화 및 정산 보고서가 없습니다.

주문 및 환불

주문 상태

아직 주문 없음: 고객이 Paytrail로 이동했지만 아직 결제하지 않았거나, Paytrail이 아직 결제를 확인하지 않았습니다. 장바구니만 존재합니다.

Payment accepted or Delivered: 결제가 확인되었습니다. 상태는 Order status after payment를 따릅니다. 결제는 Paytrail 거래 ID와 함께 기록되며, 메모에는 거래, Paytrail에서 사용된 결제 수단 및 금액이 표시됩니다.

Awaiting Paytrail payment: 결제가 제공업체에서 대기 중입니다(청구서 또는 지연 결제). Paytrail이 결제를 확인하면 주문은 결제 완료 상태로 이동하고, 실패하면 Payment error로 이동합니다.

Paytrail payment on hold: 결제된 금액이 주문 합계와 다르거나(실제로 결제된 금액이 기록됩니다), 주문이 취소된 후 결제가 도착했거나, 쇼핑몰이 실운영 상태일 때 테스트 결제를 받은 경우입니다(실제 금액 없음, 아무것도 기록되지 않음). 메모에 이유가 설명됩니다. 주문을 확인한 후 처리하거나 결제를 환불하십시오.

Payment error: 대기 중인 결제가 실패했거나 취소되었습니다.

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

반복되거나 동시에 들어오는 콜백은 두 번째 주문이나 중복 메모를 절대 만들지 않습니다. 이미 결제된 장바구니의 두 번째 시도가 결제되더라도 주문은 변경되지 않으며, Duplicate payment 메모가 Paytrail 가맹점 패널에서 환불하라고 안내합니다.

Paytrail 결제 블록

주문 페이지에는 거래 ID, 모드(테스트 결제의 경우 TEST mode 배지), 결제 수단, Paytrail 상태, 결제 및 환불된 금액, 환불 양식, 환불 내역, 장바구니의 결제 시도, 주문의 Paytrail notes가 포함된 Paytrail payment 블록이 표시됩니다.

환불

Paytrail payment 블록에 금액을 입력하고(아직 환불되지 않은 금액이 자동으로 채워집니다), 필요하면 주문 메모에 남길 사유를 입력한 다음 Refund via Paytrail을 클릭합니다. Refund this amount through Paytrail? This cannot be undone. 확인 질문에 동의하십시오. 전액 및 부분 환불을 지원하며, 금액 기준으로만 가능합니다. 주문을 편집할 권한이 필요하며, 모듈 페이지에 대한 접근은 필요하지 않습니다. Paytrail이 실제로 받은 금액까지만 환불할 수 있으므로, 금액 불일치가 있는 경우 한도는 주문 합계가 아니라 고객이 결제한 금액입니다. 환불은 결제가 이루어진 모드의 자격 증명을 사용하므로, 실결제의 경우 실운영 자격 증명이 설정되어 있어야 합니다. 환불은 Paytrail이 결제를 확인한 후에만 가능합니다.

결제 수단이 직접 환불을 지원하지 않는 경우, 모듈은 이메일 환불을 자동으로 시작합니다. Paytrail이 고객에게 은행 계좌를 입력하라는 이메일을 보냅니다. 이를 위해 주문에 고객의 이메일 주소가 있어야 합니다. 메모에는 시작된 환불 유형이 표시됩니다.

환불은 즉시 완료되거나 나중에 처리될 수 있습니다. Paytrail의 이후 확인 결과는 메모로 추가됩니다. Paytrail이 환불을 완료하지 못한 경우, 메모에 고객에게 돈이 반환되지 않았다고 표시되며, 해당 환불은 더 이상 환불된 것으로 간주되지 않습니다. 다른 방법으로 고객에게 환불하십시오. Paytrail이 환불을 즉시 거부하면 블록에 오류가 표시되며 환불은 기록되지 않습니다. 전액 환불은 주문을 Refunded로 설정합니다. 부분 환불은 상태를 바꾸지 않습니다.

모듈은 크레딧 슬립을 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 Paytrail을 통해 돈을 돌려보내지 않습니다. Paytrail 가맹점 패널에서 처리된 환불은 PrestaShop으로 동기화되지 않습니다.

라이선스 키

이 모듈은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록 License — VibeFox Paytrail Gateway는 Modules > Module Manager > VibeFox Paytrail Gateway > Configure 페이지의 첫 번째 블록으로, 설정 위에 있습니다. License key에 키를 붙여 넣고 Activate를 클릭합니다. 그 후 블록에는 마스킹된 키, 상태(예: 라이선스가 유효한 날짜와 도메인), 그리고 다음 버튼이 표시됩니다: Check now(상태 다시 확인), Change key(다른 키 입력), Remove key(이 쇼핑몰에서 키 제거). 그 아래에는 Product: presta-payment-paytrail 줄과 Manage licenses and domains in your account 링크가 있으며, 이 링크는 vibefox.net 계정을 엽니다. 이 모듈의 Configure 권한이 있는 직원만 키를 변경할 수 있습니다. 블록의 텍스트는 백오피스 언어를 따릅니다(영어와 러시아어 포함).

키가 허용되지 않으면 블록에 이유가 표시됩니다. 예: Key not found, This key belongs to another product, Domain limit reached 또는 날짜와 함께 License expired on. 쇼핑몰 주소를 변경한 후 또는 계정에서 도메인 슬롯을 비운 후에는 Check now를 클릭하십시오. 라이선스 서버에 연결할 수 없으면 모듈은 마지막으로 확인된 상태로 계속 작동합니다.

키 1개는 도메인 1개에서만 작동합니다. 다중 쇼핑몰 구성에서도 마찬가지로 메인 쇼핑몰의 도메인에 해당합니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하십시오.

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

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

문제 해결

체크아웃에 Paytrail이 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 그리고 Test mode가 켜져 있거나 Merchant ID와 Secret key가 입력되어 있는지(공개 테스트 계정 375917이 아님) 확인하십시오. 장바구니 통화가 EUR인지 확인하십시오. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인하십시오. 설정 페이지에는 자격 증명 누락 및 잘못된 쇼핑몰 통화에 대한 경고가 표시됩니다.

결제는 완료되었지만 주문이 생성되지 않음: 콜백이 쇼핑몰에 도달하지 못했고 고객도 쇼핑몰로 돌아오지 않았습니다. 주문 섹션에 표시된 Callback URL은 인터넷에서 접근 가능해야 합니다(기본 인증이나 방화벽이 가로막지 않아야 합니다).

콜백 또는 복귀에서 Payment verification failed.가 표시됨: 서명이 올바르지 않거나, 결제가 해당 장바구니의 결제 시도에 속하지 않습니다. 아무것도 변경되지 않습니다. Secret key가 올바르고 Merchant ID에 속하는지 확인하십시오.

콜백이 Temporarily unavailable로 응답함: 같은 시점에 다른 요청이 주문을 확인하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). Paytrail이 다시 호출합니다. 이유는 Log 필드에서 확인하십시오.

고객이 Paytrail을 선택할 때 오류가 표시됨: 모듈 페이지의 Log 필드를 확인하십시오. 예를 들어 Paytrail API error (401)는 잘못된 자격 증명을 뜻합니다. 자세한 내용은 Debug log를 켜십시오.

Merchant ID가 저장되지 않음: 숫자만 포함해야 합니다. Paytrail 가맹점 패널에서 다시 복사하십시오.

주문이 Paytrail payment on hold 상태임: Paytrail payment 블록의 메모를 읽으십시오. 이유는 결제 금액 불일치, 취소 후의 결제, 또는 실운영 모드에서의 테스트 결제입니다.

환불이 실패함: 메시지를 읽으십시오. This order has no confirmed Paytrail payment. Refund it manually.는 환불할 확인된 Paytrail 결제가 없다는 뜻입니다. The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings.는 결제가 실운영 모드에서 이루어졌으나 실운영 자격 증명이 설정되지 않았다는 뜻입니다. Invalid refund amount: at most …는 금액이 환불 가능한 잔액을 초과했다는 뜻입니다. 결제 수단이 이메일 환불만 지원하는 경우, 주문에 고객의 이메일 주소가 필요합니다.

개발자 훅: actionWcpPaytrailPaymentRequest 훅은 결제 요청이 서명되어 전송되기 전에 이를 변경합니다.

제거

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

Paytrail은 해당 소유자의 상표입니다. 이 모듈은 Paytrail과 제휴하거나 Paytrail의 승인을 받은 것이 아닙니다.