VibeFox Cardcom for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

HTTPS: Cardcom이 결제 알림을 보낼 수 있도록 쇼핑몰은 인터넷에서 HTTPS로 접근할 수 있어야 합니다.

통화: 장바구니 통화는 ILS, USD, EUR 또는 GBP여야 합니다. 그 외 통화에서는 체크아웃에서 해당 결제 수단이 숨겨집니다.

Cardcom 계정: 실제 결제를 하려면 터미널 번호, API 사용자 이름, API 비밀번호가 있는 Cardcom 가맹점 계정이 필요합니다. 결제에는 터미널 번호와 API 사용자 이름만 필요합니다. API 비밀번호는 PrestaShop에서 하는 환불에만 사용됩니다. 테스트 모드는 Cardcom 계정 없이도 작동합니다.

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

설치

1. 관리 패널에서 Modules > Module Manager로 이동하여 Upload a module을 클릭하세요. 모듈의 ZIP 파일을 선택하세요.

2. 업로드가 끝나면 Configure를 클릭하거나, 나중에 모듈 목록에서 VibeFox Cardcom Payment Gateway를 찾아 Configure를 클릭하세요.

3. Configure 페이지 상단의 라이선스 블록에서 License key 항목에 VibeFox 라이선스 키를 입력하고 Activate를 클릭하세요(라이선스 키 섹션 참조).

4. Enable/Disable을 켜고, Test Mode는 켜 둔 채로 Save를 클릭하세요. 카드 4580 0000 0000 0000, 임의의 미래 만료일, CVV 123으로 테스트 주문을 하세요.

5. 실제 결제를 받으려면 Test Mode를 끄고, Cardcom에서 받은 Terminal Number, API Username, API Password를 입력한 뒤 Save를 클릭하세요.

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

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 테스트 모드가 켜져 있는 동안 페이지는 입력란 위에 경고를 표시합니다. 운영 모드에서는 단말기 번호나 API 사용자 이름이 비어 있으면 경고하며(이 경우 체크아웃에서 Cardcom이 숨겨집니다), 운영 입력란에 공개 테스트 단말기 1000 / CardTest1994가 들어 있으면 경고합니다(실제 금액이 청구되지 않으므로 이 경우에도 체크아웃에서 Cardcom이 숨겨집니다). 또한 API 비밀번호가 없으면 PrestaShop에서 환불할 수 없다는 점을 알려 줍니다. 쇼핑몰의 기본 통화가 지원되지 않는 경우에도 경고합니다. 자격 증명이 비어 있거나 테스트용인 상태로 운영 모드를 저장하면, 자신의 단말기 번호와 API 사용자 이름을 입력할 때까지 체크아웃에서 게이트웨이가 숨겨진 상태로 유지된다는 오류 메시지가 표시됩니다.

Cardcom

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

Title: 고객이 체크아웃에서 보는 결제 수단 이름입니다. 주문에 저장되는 결제 수단 이름이기도 합니다. 기본값: Credit Card (Cardcom). 필수.

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely with your credit card via Cardcom.

테스트 모드

테스트 모드는 공개 Cardcom 테스트 단말기 1000(API 사용자 CardTest1994)을 사용합니다. 실제 금액은 청구되지 않으며 Cardcom 계정도 필요하지 않습니다. 테스트 카드: 4580 0000 0000 0000, 임의의 미래 만료일, CVV 123. 테스트 모드에서는 체크아웃에 이 테스트 카드를 안내하는 줄도 표시됩니다.

Test Mode: 테스트 모드(단말기 1000, 실제 금액 없음)를 켭니다. 기본값: 켬. 아래의 운영 자격 증명으로 실제 결제를 받으려면 끄세요. 환불은 항상 주문이 결제된 모드의 자격 증명으로 전송됩니다.

운영 자격 증명

단말기 번호, API 사용자 이름, API 비밀번호는 가맹점 계정과 함께 Cardcom에서 제공합니다. Cardcom 대시보드의 API 설정에서 확인하거나 Cardcom 고객 지원에 문의하세요. 이 항목들은 운영 모드에서만 사용됩니다.

Terminal Number: Cardcom 단말기 번호입니다. 숫자만 포함해야 합니다. 다른 값을 입력하면 오류가 표시되고 이전 값이 유지됩니다.

API Username: 이 단말기의 Cardcom API 사용자 이름(ApiName)입니다. 저장할 때 공백은 제거됩니다.

API Password: Cardcom API 비밀번호입니다. PrestaShop에서 하는 환불에만 필요합니다. 저장된 비밀번호는 다시 표시되지 않습니다. 입력란은 비어 있고 Saved — leave empty to keep it.이 표시됩니다. 변경하려는 경우에만 새 값을 입력하세요.

Clear the saved API password: 체크박스를 선택하고 Save를 클릭하면 비밀번호가 삭제됩니다. 입력란이 비어 있으면 저장된 값이 유지됩니다.

결제 페이지

Notification URL: Cardcom은 결제 알림(IndicatorUrl)을 이 주소로 보냅니다. 친숙한 URL을 사용하면 https://your-shop/module/wcp_cardcom_payment_gateway/webhook처럼 보이며, /en/ 같은 언어 코드가 붙을 수도 있습니다. 이 주소는 결제할 때마다 장바구니 ID와 함께 Cardcom에 자동으로 전달되므로 Cardcom에서 따로 설정할 것은 없습니다. HTTPS로 인터넷에서 접근할 수 있어야 합니다.

Operation: Cardcom 결제 페이지에서 수행할 작업입니다.

Charge only: 카드에 청구합니다(기본값).

Charge + Save token: 카드에 청구하고, Cardcom이 카드 토큰도 생성합니다. 토큰은 결제와 함께 저장되며, Cardcom 도구에서 사용할 수 있도록 주문 페이지에 표시됩니다. 모듈은 저장된 토큰에 직접 청구하지 않습니다.

Max Installments: 고객이 Cardcom 페이지에서 선택할 수 있는 최대 할부 횟수(결제 횟수)로, 1–36회입니다. 1은 할부 없음을 뜻합니다. 기본값: 1.

Success Order Status: 결제 확인 후의 주문 상태입니다. 주문은 이 상태로 바로 생성됩니다.

Payment accepted (Processing): 결제된 주문에 대한 PrestaShop의 표준 상태입니다(기본값).

Delivered (Completed): 결제된 모든 주문이 배송 완료가 됩니다.

Cardcom payment on hold (On Hold): 결제된 모든 주문은 관리자의 수동 검토를 기다립니다. 결제는 주문에 그대로 기록됩니다.

주문과 일치하지 않는 결제는 항상 Cardcom payment on hold로 갑니다.

고급

Debug log: API 요청과 알림을 모듈 폴더의 logs/cardcom_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류는 항상 기록됩니다. 자격 증명, 카드 토큰, 카드 소유자 정보는 절대 기록되지 않습니다. 기본값: 끔.

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

Delete on Uninstall: 켜면 모듈을 제거할 때 설정과 로그가 영구적으로 삭제됩니다. 주문, Cardcom 거래 및 환불, Cardcom payment on hold 주문 상태는 항상 유지되므로, 재설치 후에도 이전 주문을 환불할 수 있습니다. 기본값: 끔.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 Credit Card (Cardcom))을 선택하고 You will be redirected to the secure Cardcom payment page. 안내를 봅니다. 확인하면 모듈은 장바구니 통화로 된 장바구니 합계에 대해 Cardcom 결제 페이지를 만들고 고객을 그곳으로 보냅니다. 이 시점에는 아직 주문이 없습니다. 고객의 언어가 히브리어이면 히브리어로, 그 밖의 경우에는 영어로 열립니다. 장바구니의 상품은 상품명으로 Cardcom에 전달됩니다. 고객은 카드 정보를 입력하고, 할부가 허용된 경우 결제 횟수를 선택합니다.

결제를 마치면 고객은 쇼핑몰로 돌아옵니다. 주문은 Cardcom이 결제를 확인한 후에만 결제 완료로 표시됩니다. Cardcom은 알림 주소를 호출하고, 모듈은 그 호출에서 결제 페이지 코드만 가져옵니다. 그 코드가 이 장바구니에 대해 쇼핑몰이 발급한 것인지 확인한 다음, 서버 간 통신으로 Cardcom에 실제 결과를 요청합니다. 알림이 늦게 도착하면 고객이 돌아올 때 같은 확인이 수행됩니다. 그러면 주문이 생성되고, 고객은 표준 주문 확인 페이지에서 Your payment with Cardcom has been received.를 보게 됩니다. 고객이 돌아왔을 때 Cardcom이 아직 결제를 확인하지 않았다면, Payment confirmation 페이지에 Your payment is being confirmed by Cardcom. You will receive an e-mail as soon as it is confirmed.가 표시되고 Check again 버튼이 나타납니다. 알림이 도착하는 즉시 주문이 생성됩니다.

결제가 완료되지 않았거나 Cardcom이 결제를 거부하면, 고객은 체크아웃으로 돌아가 The card payment was not completed. Please try again or choose a different payment method.를 보게 됩니다. 주문은 생성되지 않으며 장바구니는 유지됩니다. 고객은 다시 시도할 수 있습니다. 시도할 때마다 새로운 Cardcom 결제 페이지가 생성됩니다. 같은 장바구니의 이전 결제 페이지에서 이루어진 결제는 여전히 인식되며, 이전 페이지에서의 거절이 새 시도에 영향을 주지는 않습니다.

Cardcom이 결제 페이지를 열 수 없으면, 고객은 체크아웃에 머물면서 Could not connect to Cardcom. Please try again in a moment. 같은 짧은 메시지를 보거나, Cardcom 코드와 함께 Cardcom이 결제 페이지를 열 수 없었다는 메시지를 보게 되며, 다른 결제 수단을 선택할 수 있습니다.

알림은 쇼핑몰이 점검 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다.

모듈은 카드 결제를 Cardcom 페이지에서만 받습니다. 저장된 카드나 원클릭 결제, 구독을 지원하지 않으며, 저장된 토큰에 청구하지 않고, Cardcom 인보이스나 영수증 설정이 없으며, Cardcom을 통한 Bit, Apple Pay, Google Pay, PayPal도 없고, iframe 모드와 나중 캡처 거래도 없습니다.

주문 및 환불

주문 상태

No order yet: 고객이 Cardcom으로 이동했지만 아직 결제하지 않았거나, 결제가 거부되었거나, Cardcom이 아직 결제를 확인하지 않은 상태입니다. 장바구니만 존재합니다.

Payment accepted, Delivered or Cardcom payment on hold: 결제가 확인되었습니다. 상태는 Success Order Status를 따릅니다. 결제는 Cardcom 거래(deal) 번호를 거래 ID로 하여 기록됩니다. 주문의 비공개 메시지에는 Cardcom 거래가 표시되며, Cardcom이 제공하는 경우 카드 끝 4자리, 인보이스 번호, 할부 횟수도 표시됩니다. 테스트 결제에는 Test mode — no real money was charged.가 표시됩니다.

Cardcom payment on hold after payment: Cardcom이 주문과 일치하지 않는 결제를 확인했습니다. 예를 들어 결제 페이지를 연 뒤 장바구니가 변경되었거나, 다른 금액이나 통화가 청구된 경우입니다. 메시지에 이유가 설명되며, Cardcom 블록에는 Needs review 아래에 표시됩니다. 통화가 주문과 일치하면 결제는 Cardcom이 청구한 금액으로 기록됩니다. Cardcom 대시보드에서 결제와 주문을 비교한 뒤, 주문을 처리하거나 결제를 환불하세요.

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

이미 주문이 있는 장바구니에 대해 두 번째 성공 결제가 들어오면(예: 고객이 브라우저 탭 두 개에서 결제한 경우), 주문은 변경되지 않습니다. 고객이 이중으로 청구되었을 수 있다는 메시지가 표시되며, Cardcom 대시보드에서 환불하라는 안내가 나옵니다.

Cardcom 결제 블록

주문 페이지에는 Cardcom payment 블록이 표시되며, 거래, 결제 페이지 코드, 상태, 카드, 할부, 인보이스, 카드 토큰(Charge + Save token 사용 시), 청구 금액, 주문 합계, 환불 금액, 테스트 결제용 Test mode 배지, 환불 내역이 포함됩니다.

환불

Cardcom payment 블록에 금액을 입력하세요(아직 환불되지 않은 금액이 자동으로 채워집니다). 필요하면 사유를 입력한 뒤 Refund via Cardcom을 클릭하세요. Refund this amount through Cardcom? This cannot be undone. 질문을 확인하세요. 전액 및 부분 환불을 지원하며, 한 주문에 여러 번 부분 환불을 할 수 있습니다. 주문을 편집할 권한이 있어야 하며, 모듈 페이지에 접근할 권한은 필요하지 않습니다. 환불은 Cardcom이 청구한 금액과 통화로 이루어지므로, 금액이나 통화가 일치하지 않은 경우에는 주문 합계가 아니라 고객이 실제로 결제한 금액까지만 환불할 수 있습니다. 환불은 주문이 결제된 모드의 자격 증명으로 전송됩니다. 운영 모드로 전환한 뒤에도 테스트 주문은 Cardcom 테스트 단말기에서 환불되며, 운영 주문은 항상 운영 자격 증명을 사용합니다. 운영 환불에는 API Username과 API Password가 필요합니다. Cardcom이 환불을 수락하지 않으면 블록에 오류가 표시되며 환불은 기록되지 않습니다. 성공한 환불은 Cardcom 환불 거래와 사유와 함께 환불 내역 및 주문 메시지에 추가됩니다. 전액 환불은 주문을 Refunded로 설정합니다. 부분 환불은 상태를 바꾸지 않습니다.

모듈은 크레딧 전표를 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 Cardcom을 통해 돈을 돌려보내지 않습니다. Cardcom 대시보드에서 한 환불은 쇼핑몰에 보고되지 않습니다.

라이선스 키

모듈은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. License — VibeFox Cardcom Payment Gateway 라이선스 블록은 Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure 페이지에서 설정 위에 있는 첫 번째 블록입니다. 키를 License key에 붙여 넣고 Activate를 클릭하세요. 그러면 블록에 키가 마스킹되어 표시되고, 상태(예: 라이선스가 유효한 날짜와 도메인)와 함께 Check now(상태 다시 확인), Change key(다른 키 입력), Remove key(이 쇼핑몰에서 키 제거) 버튼이 나타납니다. 그 아래에는 Product: presta-payment-cardcom 줄과 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 계정에서 슬롯을 해제하세요.

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

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

문제 해결

체크아웃에 Cardcom이 나타나지 않습니다: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 장바구니 통화가 ILS, USD, EUR 또는 GBP인지 확인하세요. 운영 모드에서는 Terminal Number와 API Username에 테스트 단말기 1000 / CardTest1994가 아니라 본인의 자격 증명이 입력되어 있는지 확인하세요. 설정 페이지는 무언가 빠져 있으면 경고를 표시합니다. Payment > Preferences에서 모듈이 장바구니 통화, 고객의 국가, 고객 그룹에 대해 허용되어 있는지 확인하세요.

결제는 완료되었지만 주문이 생성되지 않았습니다: 방화벽, 비밀번호 보호, 로컬 개발 사이트 등으로 인해 Cardcom이 쇼핑몰에 접속하지 못했을 수 있습니다. 알림 주소는 HTTPS로 인터넷에서 접근할 수 있어야 합니다. 주문은 고객이 결제 후 쇼핑몰로 돌아올 때도 생성됩니다. Debug log를 켜고 모듈 페이지의 Log 필드를 확인하세요.

알림 응답이 Missing or invalid lowprofilecode or Unknown lowprofilecode for this order입니다: 호출에 이 장바구니에 대해 쇼핑몰이 발급한 결제 페이지 코드가 없었습니다. 아무것도 변경되지 않습니다.

알림 응답이 Gateway not configured or Indicator check failed입니다: 결제 페이지가 생성된 모드의 자격 증명이 없거나, 확인을 위해 Cardcom에 연결할 수 없었습니다. 아무것도 변경되지 않으며, 고객이 쇼핑몰로 돌아올 때 결제가 다시 확인됩니다.

알림 응답이 Busy, retry입니다: 같은 시점에 다른 요청이 장바구니를 확인하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). 이유를 보려면 Debug log를 켜세요.

알림 응답이 ReturnValue mismatch or Terminal mismatch입니다: Cardcom이 다른 장바구니나 다른 단말기에 대한 결제를 보고했습니다. 아무것도 변경되지 않습니다. Terminal Number가 본인 계정의 단말기인지 확인하세요.

고객이 Payment error: this currency is not supported by Cardcom.:를 봅니다: 장바구니 통화가 ILS, USD, EUR 또는 GBP가 아닙니다.

고객이 Card payment is temporarily unavailable. Please choose another payment method.:를 봅니다: 운영 모드가 켜져 있지만 단말기 번호나 API 사용자 이름이 없거나, 운영 입력란에 공개 테스트 단말기가 들어 있습니다.

고객이 Cardcom을 선택할 때 오류를 봅니다: Debug log를 켜고 Log 필드를 확인하세요. 연결 문제와 Cardcom 오류 코드가 거기에 기록됩니다.

주문이 결제 후 Cardcom payment on hold 상태입니다: 주문 메시지 또는 Cardcom payment 블록의 Needs review를 확인하세요. 결제된 금액 또는 통화가 주문과 달랐습니다. 주문을 처리하거나 결제를 환불하세요.

API username and API password are required for refunds 오류로 환불이 실패합니다: 설정에서 API Password(및 API Username)를 입력한 뒤 다시 시도하세요.

Could not connect to Cardcom 오류로 환불이 실패합니다: 환불이 이루어졌을 수도, 아닐 수도 있으므로 다시 시도하기 전에 Cardcom 대시보드를 확인하세요.

개발자를 위해 README에는 통화 목록을 확장하는 훅 actionCardcomSupportedCurrencies(Cardcom 단말기에서 활성화된 통화만 추가하세요)와, 결제 페이지의 매개변수를 변경하는 훅 actionCardcomLowProfileParams가 나와 있습니다.

제거

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

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