VibeFox ifthenpay for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: 8.0 이상. 이전 PHP 버전에서는 모듈 설치가 거부됩니다.

통화: 유로(EUR)만 지원합니다. 장바구니 통화가 EUR이 아니면 결제 방법이 표시되지 않습니다. ifthenpay는 0.01 ~ 99,999.99 EUR 금액을 받습니다.

ifthenpay 계정: ifthenpay.com에서 가입하세요. 제공하는 방법의 키가 필요합니다: Multibanco, MB WAY 또는 Credit Card(형식 ABC-123456). 키는 ifthenpay 백오피스(backoffice.ifthenpay.com)에 표시되거나, 계정에 해당 방법이 활성화될 때 ifthenpay가 보내줍니다. ifthenpay는 또한 고객님의 키에 대해 콜백을 활성화해야 하며(설정 참조), 쇼핑몰은 인터넷에서 접근할 수 있어야 합니다.

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

설치

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

2. 업로드가 끝나면 Configure를 클릭하거나, 나중에 모듈 목록에서 VibeFox ifthenpay Gateway를 찾아 Configure를 클릭합니다. 모듈은 설치 시 피싱 방지 키를 생성합니다.

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

4. Payment Method를 선택하고 해당 ifthenpay 키를 입력한 뒤 Save를 클릭하여 Callback URL이 선택한 방법과 일치하도록 합니다.

5. 설정에 표시된 Anti-phishing Key와 Callback URL을 복사하고, ifthenpay에 고객님의 키에 대한 콜백 활성화를 요청합니다(백오피스 또는 ifthenpay 지원을 통해).

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

설치 시 모듈은 두 가지 주문 상태를 만듭니다: Awaiting ifthenpay payment와 ifthenpay payment on hold. PrestaShop은 모든 통화, 국가, 고객 그룹에 대해 새 결제 모듈을 제공합니다. Payment > Preferences에서 이를 제한할 수 있으며, EUR은 허용된 상태로 유지해야 합니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox ifthenpay Gateway > Configure. Save 버튼이 있는 각 섹션은 페이지 전체를 저장합니다. 선택한 방법의 키가 없으면 결제 시 결제 방법이 표시되지 않습니다. 그 키 없이 게이트웨이를 활성화한 상태에서는 페이지에 ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout.가 표시됩니다.

ifthenpay

Enable/Disable: Enable ifthenpay Payment는 결제 방법을 켜거나 끕니다. 기본값: off.

Title: 결제 시 표시되는 결제 방법 제목입니다. 주문에 저장되는 결제 방법 이름이기도 합니다. 기본값: ifthenpay.

Description: 결제 시 표시되는 결제 방법 설명입니다. 기본값: Pay via Multibanco, MB WAY or Credit Card. 제공하는 방법에 맞게 바꾸세요.

Payment Method: 결제 시 제공되는 방법입니다. 이 방법의 키만 필수입니다.

ifthenpay 키

키(형식 ABC-123456)는 ifthenpay 백오피스에 표시되거나, 계정에 결제 방법이 활성화될 때 ifthenpay가 보내줍니다.

Multibanco Key: 동적 참조 번호용 ifthenpay Multibanco(MB) 키입니다.

MB WAY Key: ifthenpay MB WAY 키입니다.

Credit Card Key: ifthenpay Credit Card 키입니다. 고객이 카드 페이지에서 돌아올 때 서명을 검증하는 데에도 사용됩니다.

저장된 키는 다시 표시되지 않습니다. 입력란은 비어 있으며 Saved — leave empty to keep it.가 표시됩니다. 변경하려는 경우에만 새 값을 입력하세요.

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

Callback(결제 알림)

콜백은 결제가 이루어졌음을 쇼핑몰에 알려줍니다. 사용하는 각 키에 대해, 아래의 피싱 방지 키와 콜백 URL로 ifthenpay에 콜백 활성화를 요청하세요. Multibanco와 MB WAY 주문은 콜백으로만 확인되며, 카드 결제는 카드 페이지에서 돌아오는 서명된 반환으로도 확인됩니다.

Anti-phishing Key: 모듈이 생성하며 복사할 수 있도록 표시됩니다. ifthenpay는 모든 콜백에 이 키를 함께 보냅니다. 키가 없는 콜백은 거부됩니다.

Callback URL: 선택한 결제 방법의 콜백 URL로, ifthenpay 자리표시자를 포함하며 복사할 수 있도록 표시됩니다. 친숙한 URL을 사용하는 경우 https://your-shop/module/wcp_ifthenpay_gateway/callback처럼 시작하며, /en/과 같은 언어 코드가 붙을 수 있고, 그 뒤에 방법의 매개변수가 이어집니다. 설정에 표시된 그대로 URL 전체를 복사하세요.

각 콜백의 피싱 방지 키는 고객님의 키와 비교됩니다. 키가 없거나 잘못된 경우 403 응답을 받으며 주문은 변경되지 않습니다. 콜백은 이 모듈의 결제와도 일치해야 합니다. Multibanco는 엔티티와 참조 번호, MB WAY는 장바구니와 그 장바구니의 MB WAY 요청 중 하나, Credit Card는 장바구니와 그 장바구니의 카드 요청 중 하나로 대조됩니다. 정상 작동하는 콜백이 없으면 Multibanco와 MB WAY 주문은 절대 확인되지 않으며, 카드 결제는 서명된 반환으로만 확인됩니다. 콜백은 쇼핑몰이 유지 보수 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다.

고급

Test Mode: Credit Card와 Multibanco는 ifthenpay 샌드박스 엔드포인트를 사용합니다. 실제 금액은 청구되지 않으며, ifthenpay가 제공한 테스트 키를 사용합니다. MB WAY에는 샌드박스가 없으므로 ifthenpay의 테스트 키로 테스트하세요. 결제 시 TEST MODE 배지가 표시됩니다. 기본값: off.

Order Status After Payment: 결제가 확인된 후 설정되는 주문 상태입니다. 상태는 한 번만 변경됩니다.

Debug Log: API 요청과 콜백은 모듈 폴더의 logs/ifthenpay_p_debug.log.php에 기록됩니다. 이 파일은 웹에서 열 수 없습니다. 오류는 항상 기록됩니다. 키, 피싱 방지 키, 전체 전화번호는 절대 기록되지 않습니다. 기본값: off.

Log: 로그의 크기와 최신 항목을 보여줍니다. Clear log를 클릭하면 비워집니다.

Delete Data on Uninstall: 켜져 있으면 모듈을 제거할 때 모듈 설정, 피싱 방지 키, 로그가 삭제됩니다. 주문과 ifthenpay 결제 기록은 항상 남습니다. 기본값: off.

결제

Multibanco. 결제 시 고객에게 You will receive a Multibanco reference to complete the payment.가 표시됩니다. 고객이 확인하면 모듈은 장바구니 합계에 대한 동적 Multibanco 참조 번호를 생성하고, 주문은 Awaiting ifthenpay payment 상태로 만들어집니다. 주문 확인 페이지에는 Multibanco Payment Details(엔티티, 참조 번호, 금액)와 함께 Please use these details to pay at any Multibanco ATM or through your online banking.가 표시됩니다. 같은 정보가 주문 확인 이메일에도 추가됩니다. ifthenpay가 결제 콜백을 보내면 주문이 결제 완료됩니다.

MB WAY. 고객은 MB WAY phone number(912 345 678, +351 912 345 678, 또는 다른 국가의 경우 351#912345678)를 입력합니다. 청구지 주소의 전화번호가 자동으로 채워집니다. 모듈은 해당 전화번호로 결제 요청을 보내고, 주문은 Awaiting ifthenpay payment 상태로 만들어집니다. 주문 확인 페이지에는 A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app.가 표시됩니다. ifthenpay가 콜백을 보내면 주문이 결제 완료됩니다. 마스킹된 전화번호만 저장됩니다.

신용카드. 고객에게 You will be redirected to a secure page to enter your card details.가 표시되고, ifthenpay 카드 페이지로 이동합니다. 아직 주문은 없으며 장바구니는 유지됩니다. 결제에 성공하면 고객은 쇼핑몰로 돌아옵니다. 반환은 유효한 ifthenpay 서명, 장바구니의 보안 키, 해당 시도의 비밀 값, 그리고 장바구니의 카드 요청이 모두 일치할 때만 수락됩니다. 그러면 주문이 결제 완료 상태로 생성되고, 고객은 표준 주문 확인 페이지를 봅니다. 반환을 검증할 수 없으면 아무것도 변경되지 않으며, Payment confirmation 페이지에 Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed.와 Check again 버튼이 표시됩니다. 콜백이 도착하는 즉시 주문이 생성됩니다. 카드 결제가 실패하거나 취소되면 고객은 The card payment was not completed. You can try again or choose another payment method. 또는 The card payment was cancelled. You can try again or choose another payment method.가 표시된 결제 화면으로 돌아갑니다. 장바구니의 모든 카드 시도는 보관되므로, 이전 탭에서 한 결제도 여전히 수락됩니다.

주문은 ifthenpay가 결제를 확인한 후에만 결제 완료로 표시되며, 금액은 주문 합계와 센트 단위까지 대조됩니다. 결제를 시작할 수 없으면 고객은 결제 화면에 머무르며, 예를 들어 The Multibanco reference could not be created. Please try again or choose another payment method., The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method. 또는 The payment service is temporarily unavailable. Please try again in a few minutes.와 같은 짧은 메시지를 봅니다. 기술적인 이유는 로그에 기록됩니다.

모듈은 한 번에 하나의 ifthenpay 방법만 제공합니다. Payshop, Cofidis Pay, Apple Pay, Google Pay, PIX, Pay-by-Link, 구독이나 저장된 카드, 미결제 Multibanco 참조 번호의 자동 만료나 취소, 결제 상태 조회는 지원하지 않습니다.

주문

주문 상태

No order yet: 카드 결제가 시작되었지만 아직 확인되지 않았거나, 실패하거나 취소되었습니다. 장바구니만 존재합니다.

Awaiting ifthenpay payment: Multibanco 참조 번호가 발급되었거나 MB WAY 요청이 전송되었습니다. 주문이 생성되면 PrestaShop이 재고를 차감합니다. 미결제 참조 번호와 거절된 MB WAY 요청은 주문을 자동으로 취소하지 않습니다. 필요하다면 이러한 주문은 직접 취소하세요.

Payment accepted or Delivered: 결제가 확인되었습니다. 상태는 Order Status After Payment를 따릅니다. 결제는 Multibanco 참조 번호, MB WAY 요청 ID 또는 카드 요청 ID를 거래 ID로 하여 기록되며, 메모에 확인 방법이 표시됩니다.

ifthenpay payment on hold: 받은 금액이 주문 합계와 달랐거나(예: 카드 결제가 시작된 후 장바구니가 변경된 경우), 주문이 취소된 후에 결제가 도착한 경우입니다. 메모에 그 이유가 설명되며, 고객에게 다시 결제하라고 요청하지 않습니다. ifthenpay 백오피스에서 결제를 확인한 뒤 주문을 수동으로 완료하거나 환불하세요. 이후 이 주문에 올바른 결제가 도착해도 주문 상태는 바뀌지 않습니다.

이미 결제된 주문에 대한 두 번째 결제는 ifthenpay 백오피스에서 중복 결제를 확인하라는 메모만 추가합니다. 환불된 주문과 결제 후 취소된 주문은 다시 열리지 않습니다.

ifthenpay 결제 블록

주문 페이지에는 주문의 결제 시도(날짜, 방법, 테스트 결제를 위한 Sandbox 배지, 금액, Multibanco 엔티티와 참조 번호 또는 마스킹된 MB WAY 전화번호, ifthenpay 요청 ID와 상태)가 포함된 ifthenpay payment 블록이 표시됩니다. 주문이 ifthenpay payment on hold 상태인 동안에는 Manual review 경고가, 그리고 주문의 ifthenpay notes가 표시됩니다.

환불

PrestaShop에서의 환불은 지원하지 않습니다. ifthenpay 백오피스에서 결제를 환불하고 PrestaShop에는 수동으로 기록하세요. 환불됨(DEVOLVIDO) 콜백은 메모만 추가합니다. ifthenpay가 보고하는 다른 상태도 메모만 추가합니다.

라이선스 키

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

활성 키가 없으면 결제 시 고객에게 ifthenpay가 표시되지 않습니다. 그래도 결제가 시작되면 고객에게 This payment method is not available. Please choose another one.가 표시됩니다. PrestaShop 스토어프런트는 고객님이 백오피스에 로그인되어 있는지 알지 못하므로, 결제 방법은 고객님에게도 숨겨집니다. 키를 구매하기 전에 모듈을 설정할 수는 있지만, 결제 시 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 표시됩니다. 기존 주문은 영향을 받지 않습니다: 이미 시작된 결제는 여전히 확인됩니다.

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

문제 해결

결제 시 ifthenpay가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 선택한 Payment Method의 키가 입력되어 있는지, 장바구니 통화가 EUR인지, 합계가 0.01 ~ 99,999.99 EUR 사이인지 확인하세요. Payment > Preferences에서 모듈이 EUR, 고객의 국가, 고객의 그룹에 허용되어 있는지도 확인하세요.

고객이 결제했지만 주문이 Awaiting ifthenpay payment 상태로 남아 있거나 주문이 생성되지 않음: 콜백이 쇼핑몰에 도달하지 않고 있습니다. ifthenpay가 사용하는 키에 대해 콜백 URL과 피싱 방지 키를 활성화했는지, 그리고 URL이 선택한 방법의 것인지 확인하세요. 쇼핑몰은 인터넷에서 접근할 수 있어야 하며, localhost이거나 로그인 뒤에 있으면 안 됩니다. 모듈 페이지의 Log 필드에서 Callback rejected 줄을 찾아보세요.

콜백이 403 Forbidden을 응답함: 콜백의 피싱 방지 키가 없거나 설정의 키와 다릅니다. 설정에 표시된 키를 ifthenpay에 다시 보내세요.

콜백이 503 Not configured를 응답함: 피싱 방지 키가 아직 생성되지 않았습니다. 모듈 설정을 한 번 열어 보세요. ifthenpay가 콜백을 다시 시도합니다.

콜백이 503 Busy를 응답함: 그 순간 같은 장바구니가 다른 요청에서 처리되고 있었습니다. ifthenpay가 콜백을 다시 시도합니다.

콜백이 Order not found를 응답함: 참조 번호 또는 요청이 이 모듈의 결제에 속하지 않거나, 장바구니가 다른 결제 방법으로 주문되었습니다.

결제된 주문이 보류된 이유는 무엇인가요? 받은 금액이 주문 합계와 달랐거나, 주문이 취소된 후에 결제가 도착했습니다. ifthenpay payment 블록의 메모를 읽고, ifthenpay 백오피스에서 결제를 확인한 뒤 주문을 수동으로 완료하거나 환불하세요.

MB WAY 요청을 보낼 수 없음: 전화번호가 MB WAY에 연결되어 있지 않거나 형식이 잘못되었습니다. 912 345 678을 사용하세요. 다른 국가의 번호는 351#912345678을 사용하세요.

테스트 모드와 MB WAY: ifthenpay에는 MB WAY 샌드박스가 없습니다. ifthenpay가 제공한 테스트 키를 사용하세요.

제거

Modules > Module Manager로 이동하여 VibeFox ifthenpay Gateway 옆의 메뉴를 열고 Uninstall을 선택합니다. 이 모듈의 라이선스 키와 라이선스 상태는 항상 제거됩니다. Delete Data on Uninstall이 켜져 있으면 모듈 설정, 피싱 방지 키, 로그가 삭제됩니다. 재설치 후에는 새 피싱 방지 키가 생성되며 이를 ifthenpay에 다시 보내야 합니다. 꺼져 있으면 나중에 재설치할 수 있도록 모든 설정이 유지됩니다. ifthenpay 결제 기록(참조 번호와 요청 ID)과 Awaiting ifthenpay payment 및 ifthenpay payment on hold 주문 상태는 항상 유지되므로, 이전에 발급된 참조 번호에 대한 콜백은 재설치 후에도 해당 주문을 찾을 수 있습니다. 기존 주문은 결제 메모와 거래 ID를 유지합니다.

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