VibeFox Helcim for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: 8.0 이상. 모듈은 그보다 오래된 PHP 버전에는 설치되지 않습니다.

HTTPS 및 PCI DSS: 카드 세부 정보는 체크아웃에서 입력되고 쇼핑몰 서버에서 HTTPS를 통해 Helcim으로 전송됩니다. 카드 정보는 저장되거나 기록되지 않지만 쇼핑몰 서버를 통과하므로, 쇼핑몰에는 SSL 인증서가 필요하고 호스팅은 PCI DSS(SAQ D)를 충족해야 합니다.

Helcim 계정: 캐나다 또는 미국의 Helcim 가맹점 계정과 거래 처리 권한이 있는 API 토큰(설정 참조). Helcim은 CAD와 USD를 처리합니다. Helcim 테스트(개발자) 계정은 테스트용으로 선택 사항입니다.

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

설치

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

2. 업로드가 끝나면 Configure를 클릭합니다. 또는 나중에 모듈 목록에서 VibeFox Helcim Gateway를 찾아 Configure를 클릭합니다.

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

4. Helcim에서 All Tools > Integrations > API Access Configuration을 열고, 거래 처리 권한(구매, 사전 승인, 캡처, 환불)이 있는 API 액세스를 만든 다음 토큰을 복사합니다.

5. 토큰을 Live API token에 붙여 넣고, Helcim 테스트 계정이 있다면 그 토큰을 Test API token에 붙여 넣습니다.

6. Transaction type과 Account currencies를 선택하고 Enable / Disable을 켠 다음 Save를 클릭합니다. 먼저 테스트하려면 Test mode를 켜고 테스트 계정으로 결제합니다. 그런 다음 끕니다.

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

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Helcim Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 필드 위에서는 쇼핑몰의 기본 통화가 Account currencies에 포함되지 않은 경우, 그리고 결제 수단이 활성화된 동안 현재 모드의 API 토큰이 비어 있는 경우 페이지가 경고를 표시합니다. 이 경우 결제 수단은 체크아웃에서 숨겨집니다.

Helcim

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

Title: 체크아웃에 표시되는 결제 수단 제목입니다. 주문에 저장되는 결제 수단 이름이기도 합니다. 기본값: Credit card (Helcim). 필수.

Description: 체크아웃에 표시되는 결제 수단 설명입니다. 기본값: Pay securely with your credit card.

API 자격 증명

Helcim에서 All Tools > Integrations > API Access Configuration으로 이동하여 API 액세스를 만들고 토큰을 복사합니다. 구매, 사전 승인, 캡처, 환불에 대한 거래 처리 권한을 부여하십시오. Helcim 테스트 계정은 운영 계정과 같은 API 주소를 사용하므로, 테스트 모드에서는 Helcim 테스트 계정의 토큰을 사용하기만 하면 됩니다.

Live API token: Helcim 운영 계정의 API 토큰입니다. 테스트 모드가 꺼져 있을 때 사용됩니다.

Test mode: Test API token(Helcim 테스트 계정)을 사용합니다. 결제, 캡처, 환불은 Helcim 테스트 계정으로 전송되며 고객에게는 테스트 모드 안내가 표시됩니다. 주문의 캡처와 환불은 항상 해당 주문이 결제된 모드의 토큰을 사용합니다. 기본값: off.

Test API token: Helcim 테스트(개발자) 계정의 API 토큰입니다. 테스트 모드가 켜져 있을 때 사용됩니다.

저장된 토큰은 다시 표시되지 않습니다. 필드는 비어 있으며 Saved — leave empty to keep it.를 표시합니다. 변경하려는 경우에만 새 값을 입력하십시오.

Clear saved tokens: 토큰을 선택하고 Save를 클릭하면 삭제됩니다. 필드를 비워 두면 저장된 값이 유지됩니다.

결제

Transaction type: 카드에 청구하는 방식입니다.

Account currencies: Helcim 계정이 처리할 수 있는 통화입니다. 주문은 항상 장바구니 통화로 청구됩니다. 다른 통화의 경우 결제 수단은 체크아웃에서 숨겨집니다.

고급

Debug log: API 요청과 응답을 모듈 폴더의 logs/wc_hlg_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 카드 번호는 끝 4자리만 남기고 줄여서 기록합니다. CVC, 유효기간, 토큰, 이름, 주소, 이메일, IP 주소는 절대 기록되지 않습니다. 오류(거절되거나 실패한 결제, API 오류, 실패한 캡처와 환불)는 이 옵션이 꺼져 있어도 항상 기록됩니다. 기본값: off.

Log: 로그의 크기와 최근 항목을 표시합니다. Clear log를 클릭하면 비워집니다.

Delete data on uninstall: 켜져 있으면 모듈을 제거할 때 게이트웨이 설정과 로그 파일이 삭제됩니다. Helcim 거래, 환불, 주문 상태는 항상 유지되므로, 이전에 결제된 주문도 재설치 후 캡처하고 환불할 수 있습니다. 기본값: off.

체크아웃

결제 단계에서 고객은 결제 수단(기본값은 카드 아이콘이 있는 Credit card (Helcim))을 선택하고, 그 아래 양식에 Card Number, Expiry (MM/YY), CVC, Cardholder Name을 입력합니다. 테스트 모드에서 양식에는 TEST MODE — payments go to a Helcim test account, no real charges are made.가 표시됩니다. 고객이 주문을 하면 모듈은 카드 번호 체크섬, 유효기간이 올바르고 지나지 않았는지, CVC가 3자리 또는 4자리인지, 이름이 입력되었는지 확인합니다. 오류는 체크아웃에 표시되며 Helcim으로는 아무것도 전송되지 않습니다.

그런 다음 쇼핑몰 서버는 장바구니 통화로 장바구니 합계에 대해 카드를 구매 또는 사전 승인으로 Helcim에 보냅니다. 주소 확인을 위해 청구지 주소, 전화번호, 이메일이 전송됩니다. 결제는 Helcim에서 장바구니 번호, -PS, 짧은 코드로 이루어진 인보이스 번호와 함께 표시됩니다. Helcim은 같은 요청에서 응답합니다. 주문은 Helcim이 거래를 승인한 후에만 생성되며, 고객은 표준 주문 확인 페이지로 이동합니다. 그 전에는 주문이 존재하지 않습니다.

장바구니당 한 번에 하나의 결제 시도만 진행되며, 이미 주문이 있는 장바구니는 다시 청구되지 않습니다. 모든 시도에는 멱등성 키가 사용됩니다. Helcim이 응답하지 않으면 주문이 생성되지 않으며, 5분 이내의 재시도는 카드에 이중 청구하는 대신 원래의 Helcim 결과를 반환합니다. 결제는 승인되었지만 주문을 생성할 수 없었던 경우, 같은 장바구니의 다음 시도는 카드를 다시 청구하지 않고 주문을 생성합니다.

고객이 체크아웃에서 볼 수 있는 메시지: Helcim이 거절하면 Your card was declined. Please check the card details or use another card., 그 밖의 거절된 요청에는 Helcim의 사유와 함께 Payment failed:, Helcim이 응답하지 않으면 We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card., API 토큰이 없거나 Helcim이 거부하면 This payment method is temporarily unavailable. Please choose another payment method., 이중 제출 시 Your payment is already being processed. Please wait a moment and check your e-mail before trying again., 결제는 승인되었지만 주문을 자동으로 완료할 수 없으면 Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.가 표시됩니다. 장바구니는 유지됩니다. 기술적인 세부 정보는 로그에 기록됩니다.

모듈은 HelcimPay.js나 Helcim.js를 사용하지 않으므로 카드 정보는 쇼핑몰 서버를 통과합니다. 저장된 카드, 정기결제, ACH 또는 은행 결제, Apple Pay, Google Pay, 3-D Secure 기능이 없으며 Helcim 웹훅도 없습니다.

주문과 환불

주문 상태

No order: 카드가 거절되었거나, Helcim이 응답하지 않았거나, 고객이 아직 결제하지 않은 상태입니다. 장바구니만 존재합니다. 거절과 오류는 로그에 기록됩니다.

Payment accepted: 구매가 승인되었거나 사전 승인이 캡처된 상태입니다. 결제는 Helcim 거래 ID와 함께 기록되며, 메모에는 거래 ID, 승인 코드, 카드 종류, 끝 4자리, 모드가 표시됩니다.

Helcim payment authorized: 사전 승인이 승인된 상태입니다. 금액은 보류되어 있을 뿐입니다. 캡처하거나 전액 환불로 해제하십시오.

Helcim payment on hold: Helcim이 거래를 승인했지만, 응답의 금액, 통화 또는 거래 ID가 장바구니와 일치하지 않는 상태입니다. 예를 들어 부분 승인 후이거나 결제 중 장바구니가 변경된 경우입니다. 메모에는 Helcim response verification FAILED가 표시됩니다. 구매의 경우 결제는 Helcim이 실제로 청구한 금액으로 기록됩니다. 주문을 처리하기 전에 Helcim에서 거래를 확인하십시오.

Refunded: 결제가 모듈을 통해 전액 환불된 상태입니다.

Canceled: 캡처되지 않은 사전 승인이 해제된 상태입니다. 고객에게 청구되지 않았습니다.

이미 주문이 있는 장바구니에 대해 두 번째 거래가 승인되면 주문은 변경되지 않습니다. 메모는 Helcim에서 이를 확인하고 취소하거나 환불하라고 요청합니다.

Helcim 결제 블록

주문 페이지에는 Helcim payment 블록이 표시되며, 거래 ID(캡처 후에는 사전 승인 ID도), 거래 유형과 캡처 상태, 인보이스 번호, 카드와 승인 코드, 승인 금액, 주문 합계와 환불 금액, 테스트 결제를 위한 Test mode 배지, 환불 내역, 주문의 Helcim notes가 포함됩니다. 캡처와 환불에는 주문을 편집할 권한이 필요합니다.

캡처

Helcim payment authorized 상태의 주문에서 블록의 Capture payment를 클릭하고 Capture the pre-authorized amount through Helcim?을 확인합니다. 환불을 뺀 현재 주문 합계가 캡처됩니다. 이 금액은 사전 승인 금액보다 적을 수는 있지만 많을 수는 없습니다. 캡처는 주문이 결제된 모드의 토큰을 사용합니다. 캡처가 성공하면 주문은 결제 수락됨 상태가 되고, 결제는 캡처 거래 ID와 함께 기록됩니다. 캡처가 실패하면 블록에 사유가 표시되고 메모에 추가됩니다.

환불

블록에서 금액을 입력합니다(아직 환불되지 않은 금액이 자동으로 채워집니다). 필요하면 사유를 입력하고 Refund via Helcim을 클릭합니다. Refund this amount through Helcim? This cannot be undone.를 확인합니다. 구매 또는 캡처된 사전 승인에 대한 전액 및 부분 환불이 지원되며, Helcim이 실제로 청구한 금액까지만 가능합니다. 따라서 부분 승인 후에는 고객이 결제한 금액보다 많이 환불할 수 없습니다. 캡처되지 않은 사전 승인의 경우 버튼은 Release pre-authorization입니다. 전체 금액만 해제할 수 있으며, 보류가 제거되고 주문은 취소됨 상태가 됩니다.

환불은 주문이 결제된 모드로 전송되므로 해당 모드의 토큰이 설정되어 있어야 합니다. 환불은 Helcim이 승인한 경우에만 유효합니다. Helcim이 환불을 거절하면 블록에 오류가 표시되고 환불은 기록되지 않습니다. 성공한 환불은 Helcim 환불 거래 ID와 함께 환불 내역과 메모에 추가됩니다. 전액 환불은 주문을 Refunded로 설정합니다. 부분 환불은 상태를 바꾸지 않습니다. 시간 초과 후 재시도해도 두 번 환불되지 않습니다.

모듈은 신용 메모를 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 Helcim을 통해 돈을 돌려주지 않습니다. 모듈은 Helcim 웹훅을 받지 않습니다. Helcim 대시보드에서 수행된 캡처, 환불, 무효화는 PrestaShop에 반영되지 않으므로, 주문 페이지에서 직접 실행하십시오.

라이선스 키

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

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

키 하나는 도메인 하나에서만 작동합니다. 기본 쇼핑몰의 도메인이며, 다중 스토어 설정에서도 마찬가지입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하십시오.

활성 키가 없으면 체크아웃에서 Helcim이 고객에게 표시되지 않습니다. 그래도 결제가 시작되면 고객에게 This payment method is not available. Please choose another one.가 표시됩니다. PrestaShop 스토어프런트는 백오피스에 로그인했는지 알지 못하므로, 결제 수단은 본인에게도 숨겨집니다. 키를 구매하기 전에 모듈을 설정할 수는 있지만 체크아웃에서 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 표시됩니다. 기존 주문은 영향을 받지 않습니다. 이미 완료된 결제는 유지되며, 캡처와 환불은 계속 작동합니다.

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

문제 해결

체크아웃에 Helcim이 표시되지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 현재 모드에 API 토큰(Live API token, 또는 테스트 모드에서는 Test API token)이 있는지, 장바구니 통화가 Account currencies 중 하나인지 확인하십시오. 설정 페이지는 토큰이 없거나 쇼핑몰 통화가 허용되지 않을 때 경고를 표시합니다. Payment > Preferences에서 모듈이 장바구니 통화, 고객의 국가, 고객 그룹에 대해 허용되어 있는지 확인하십시오.

고객이 「We could not confirm your payment」를 보았음: Helcim이 응답하지 않았으므로 카드에 청구되었을 수 있습니다. Log 필드를 확인하십시오. 오류에는 장바구니와 Helcim 인보이스가 명시되어 있습니다. 고객에게 다시 청구하기 전에 Helcim에서 해당 인보이스를 확인하십시오. 5분 이내의 재시도는 원래 결과를 반환하며 이중 청구하지 않습니다.

고객이 「This payment method is temporarily unavailable」를 봄: 현재 모드의 API 토큰이 비어 있거나 Helcim이 거부했습니다. 로그에는 토큰과 그 권한을 확인하라고 나옵니다. API 액세스에 거래 처리 권한이 있는지 확인하십시오.

Helcim 사유로 결제가 실패함: 카드나 청구 정보 등의 이유로 Helcim이 요청을 거절했습니다. 자세한 내용은 로그에 있습니다.

고객이 「Your payment was received, but the order could not be completed」를 봄: Helcim은 결제를 승인했지만 PrestaShop이 주문을 생성하지 못했습니다(예: 모듈이 비활성화되어 있었던 경우). 사유는 로그에 있습니다. 고객이 같은 장바구니를 다시 제출하면, 두 번째 청구 없이 승인된 결제로 주문이 생성됩니다.

주문이 Helcim payment on hold 상태임: Helcim 블록의 메모를 읽으십시오. Helcim의 응답이 장바구니와 일치하지 않았습니다(응답 검증 실패). Helcim에서 거래를 확인한 다음 주문을 처리하거나 결제를 환불하십시오.

캡처할 수 없음: 캡처할 금액은 0보다 커야 하고 사전 승인 금액을 넘으면 안 되며, 주문이 결제된 모드의 토큰이 설정되어 있어야 합니다.

환불 실패: 메시지를 읽으십시오. 캡처되지 않은 사전 승인은 전액으로만 해제할 수 있습니다. 모드에 관한 메시지는 주문이 결제된 모드의 토큰이 비어 있다는 뜻입니다. 거절된 환불은 기록되지 않습니다.

테스트 결제: 테스트 모드는 결제, 캡처, 환불을 Helcim 테스트 계정으로 보냅니다. 주문은 결제된 모드를 유지하므로, 나중에 모드를 바꿔도 그 주문의 캡처와 환불이 다른 계정으로 옮겨지지 않습니다.

제거

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

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