VibeFox HyperPay for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: OpenSSL 확장이 포함된 8.0 이상(웹훅 복호화에 사용됨). 이 확장이 없으면 모듈이 설치되지 않습니다.

HyperPay 계정: HyperPay는 가맹점 계정을 설정할 때 Access Token과 Entity ID를 발급합니다. 테스트 자격 증명과 운영 자격 증명은 서로 다릅니다. 또한 HyperPay 대시보드에서 결제 웹훅을 추가하고, 그 복호화 키(webhook key)를 준비해야 합니다. 이 키는 Administration > Webhooks에 표시됩니다(설정 참조).

카드 정보: 카드는 HyperPay 위젯에만 입력되므로 카드 정보는 쇼핑몰 서버에 전달되지 않습니다(PCI DSS SAQ A).

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

설치

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

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

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

4. HyperPay가 발급한 테스트용 Access Token, Entity ID, 웹훅 키를 입력하고 Test Mode를 켜 둡니다.

5. HyperPay 대시보드(Administration > Webhooks)에서 Webhook 섹션에 표시된 URL로 결제 웹훅을 추가하고, 그 복호화 키를 같은 모드의 웹훅 키 필드에 복사합니다.

6. Enable/Disable을 켜고 Save를 클릭한 다음, HyperPay 테스트 카드로 테스트 결제를 진행합니다. 그런 다음 운영 자격 증명을 입력하고 Test Mode를 끕니다.

설치 시 모듈은 세 가지 주문 상태를 만듭니다: Awaiting HyperPay payment, HyperPay payment authorized, HyperPay payment on hold. PrestaShop은 새 결제 모듈을 그 시점에 활성화된 통화, 국가, 고객 그룹과 연결합니다. 나중에 활성화하는 국가는 Payment > Preferences에서 허용해야 합니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 개별 Save 버튼이 있습니다. 테스트 모드가 켜져 있는 동안 페이지는 입력란 위에 Test mode is on: payments go to the HyperPay test system and no real money is charged.를 표시합니다. 현재 모드의 Access Token 또는 Entity ID가 없으면 경고가 표시되며(이 경우 체크아웃에 결제 방법이 나타나지 않음), 현재 모드에 유효한 웹훅 키가 없으면 경고가 표시됩니다(이 경우 고객이 쇼핑몰로 돌아와야만 결제가 확인됨). 저장할 때 자격 증명의 공백은 제거되며, 웹훅 키가 64자리 16진수 키가 아니면 페이지에서 경고합니다.

HyperPay

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

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

Description: 고객이 체크아웃에서 보는 설명입니다. 기본값: Pay securely using your credit or debit card.

API 자격 증명

Access Token, Entity ID, 웹훅 키는 가맹점 계정을 설정할 때 HyperPay가 발급합니다. 테스트 자격 증명과 운영 자격 증명은 서로 다릅니다. 웹훅 키는 HyperPay 대시보드의 Administration > Webhooks에 표시됩니다.

Test Mode: HyperPay 테스트 시스템(eu-test.oppwa.com)과 테스트 자격 증명을 사용합니다. 실제 금액은 청구되지 않습니다. 운영 자격 증명(eu-prod.oppwa.com)으로 실제 결제를 받으려면 끕니다. 기본값: 켬. 켜져 있는 동안 고객에게는 결제 방법 아래에 Test mode: no real payment will be made.가 표시됩니다.

Test Access Token: HyperPay 테스트 계정의 bearer token입니다.

Test Entity ID: 테스트 결제 채널의 Entity ID입니다.

Test Webhook Key: 테스트 시스템의 웹훅 알림을 복호화하는 데 사용되는 64자리 16진수 키입니다.

Live Access Token: HyperPay 운영 계정의 bearer token입니다.

Live Entity ID: 운영 결제 채널의 Entity ID입니다.

Live Webhook Key: 운영 시스템의 웹훅 알림을 복호화하는 데 사용되는 64자리 16진수 키입니다.

저장된 access token과 웹훅 키는 다시 표시되지 않습니다. 입력란은 비어 있으며 Saved — leave empty to keep it.를 표시합니다. 변경하려는 경우에만 새 값을 입력합니다.

저장된 비밀 값 삭제: 토큰이나 키를 체크한 다음 Save를 클릭하면 삭제됩니다. 입력란을 비워 두면 저장된 값이 유지됩니다.

Webhook

웹훅은 고객이 쇼핑몰로 돌아오기 전에 브라우저를 닫더라도 결제 정보를 쇼핑몰에 알려 줍니다. HyperPay 대시보드(Administration > Webhooks)에서 이 섹션의 Webhook URL에 표시된 URL로 결제용 웹훅을 추가합니다. 친숙한 URL을 사용하는 경우 https://your-shop/module/wcp_hyperpay_payment_gateway/webhook와 같은 형태이며, /en/처럼 언어 코드가 포함될 수도 있습니다. 설정에 표시된 URL을 정확히 그대로 복사하십시오. 그다음 웹훅 복호화 키를 같은 모드의 Test Webhook Key 또는 Live Webhook Key에 복사합니다.

HyperPay 웹훅은 암호화되어 있습니다(AES-256-GCM). 귀하의 키로 복호화할 수 없는 웹훅은 거부됩니다. 결제 알림만 처리되며, 결제는 귀하의 장바구니 중 하나의 결제 세션에 속해야 하고, 그 세션은 웹훅을 복호화한 키와 같은 모드에서 생성되어야 합니다. HyperPay 테스트 알림은 승인 처리됩니다. 웹훅은 HyperPay 대시보드에서 이루어진 캡처, 역분개, 환불, 차지백도 알려 줍니다(주문 및 환불 참조). 웹훅이 없으면 결제는 고객이 결제 후 쇼핑몰로 돌아왔을 때에만 확인됩니다.

Payment

Transaction Type: 카드를 청구하는 방식입니다.

Debit (DB): 카드에 즉시 청구합니다(기본값).

Pre-Authorization (PA): 금액만 예약합니다. Capture payment로 주문의 HyperPay 블록 또는 HyperPay 대시보드에서 캡처하기 전까지 주문은 HyperPay payment authorized 상태로 남습니다.

Payment Brands: 결제 위젯에 표시되는 브랜드입니다: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. 기본값: VISA와 Mastercard. 선택된 브랜드가 없으면 페이지가 경고하고 위젯에는 VISA와 Mastercard가 표시됩니다. 귀하의 Entity ID에 대해 HyperPay가 활성화한 브랜드만 선택하십시오. mada, STC Pay, Apple Pay는 보통 자체 entity를 사용하며, 이 모듈은 이를 지원하지 않습니다.

Advanced

Enable Logging: API 요청과 응답을 모듈 폴더의 logs/hyperpay_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류와 경고는 항상 기록됩니다. 로그에는 카드 정보, 키, 고객 데이터가 포함되지 않습니다. 기본값: 끔.

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

Delete Data on Uninstall: 켜져 있으면 모듈을 제거할 때 설정, HyperPay 결제 시도 테이블, 로그 파일이 삭제됩니다. 주문과 모듈의 주문 상태는 유지됩니다. 기본값: 끔.

체크아웃

결제 단계에서 고객은 결제 방법(기본값 Credit/Debit Card (HyperPay))을 선택하고 주문을 확정합니다. 모듈은 장바구니 합계와 장바구니 통화로 HyperPay 결제 세션을 준비하고, HyperPay 위젯과 Please complete your payment below: 안내가 포함된 쇼핑몰의 HyperPay payment 페이지를 엽니다. HyperPay가 지원하는 경우 위젯은 고객의 언어를 사용합니다. 테스트 모드에서는 페이지에 Test mode: use a HyperPay test card, no real payment will be made.가 표시됩니다. 고객은 위젯에 카드 정보를 입력하거나 Choose another payment method를 따라 체크아웃으로 돌아갈 수 있습니다. 이 단계에서는 아직 주문이 없습니다. 장바구니가 바뀌지 않는 한, 페이지를 새로고침해도 최대 25분 동안 같은 결제 세션이 재사용됩니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 모듈은 결제가 이 장바구니의 결제 세션 중 하나에 속하는지 확인하고, 결제 세션이 생성된 모드에서 서버 간 요청으로 HyperPay에 결과를 조회합니다. 주문은 HyperPay가 이 요청으로든 웹훅으로든 결제를 확인한 후에만 결제 완료로 표시됩니다. 금액과 통화는 장바구니와 일치해야 합니다. 반환과 웹훅이 동시에 도착하면 하나씩 순서대로 처리되므로 주문이 두 번 생성되지 않습니다. 결제가 확인되면 주문이 생성되고, 고객은 표준 주문 확인 페이지를 봅니다.

결제가 완료되지 않았다면 고객은 메시지와 함께 체크아웃으로 돌아갑니다: Payment failed: 와 HyperPay가 알려 준 이유, Payment was not completed. Please try again. 또는 We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. 장바구니는 유지되며 고객은 다시 결제할 수 있습니다. 새로운 시도마다 새로운 HyperPay 결제 세션이 발급됩니다. 결제 양식을 준비할 수 없는 경우 고객은 체크아웃에 머무르며 짧은 메시지를 봅니다. 예를 들어 일부 청구 정보가 결제 제공업체에서 승인되지 않았다는 메시지, 또는 결제 설정 오류로 결제 양식을 사용할 수 없다는 메시지가 표시됩니다. 기술적인 이유는 로그에 기록됩니다.

HyperPay API의 요구에 따라 금액은 소수점 두 자리로 전송됩니다. 소수점 세 자리를 사용하는 통화(KWD, BHD, JOD, OMR)의 경우 장바구니 합계는 소수점 두 자리로 반올림됩니다.

웹훅은 쇼핑몰이 유지 보수 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한의 영향을 받지 않습니다.

이 모듈은 PrestaShop에서의 환불이나 무효화, 카드 저장이나 토큰화, 구독, Apple Pay 도메인 인증, 브랜드별 개별 Entity ID, Tabby, Tamara 또는 기타 후불결제 방식을 지원하지 않습니다.

주문 및 환불

주문 상태

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

Payment accepted: 즉시 청구 결제가 확인되었거나 사전 승인이 캡처되었습니다. 결제는 HyperPay 결제 ID를 거래 ID로 하여 기록되며, 비공개 메모에 HyperPay 결과 코드, 설명, 결제 ID가 표시됩니다. HyperPay가 결제를 수동 검토 대상으로 표시한 경우 메모에 그 내용이 나타나며, 배송 전에 HyperPay 대시보드에서 확인해야 합니다.

HyperPay payment authorized: 사전 승인으로 금액이 예약되었습니다. 주문의 HyperPay 블록 또는 HyperPay 대시보드에서 캡처하십시오. 캡처 웹훅이 주문을 Payment accepted로 옮깁니다.

Awaiting HyperPay payment: HyperPay가 결제를 대기 중으로 보고했습니다. HyperPay가 결제를 확인하면 주문은 Payment accepted로 바뀝니다.

HyperPay payment on hold: HyperPay가 장바구니나 주문과 다른 금액 또는 통화를 보고했거나(예: 결제 페이지를 연 후 장바구니가 변경됨), 주문이 취소된 후에 결제가 도착했습니다. 메모에 이유가 설명되어 있습니다. HyperPay 대시보드에서 결제를 확인한 다음 주문을 처리하거나 결제를 환불하십시오.

Canceled: 사전 승인이 HyperPay 대시보드에서 역분개되었고, 역분개 웹훅이 승인된 주문을 취소합니다.

거절된 결과는 기존 주문을 절대 변경하지 않습니다. 이미 결제 완료된 주문에 다른 성공 결제가 도착해도 주문은 변경되지 않습니다. 메모에서 중복 결제를 HyperPay 대시보드에서 환불하라고 안내합니다. 환불된 주문에 대한 성공 결제는 메모만 추가합니다.

HyperPay 결제 블록

주문 페이지에는 HyperPay payment 블록이 표시되며, 결제 ID(캡처 후에는 캡처 ID도), 거래 유형, 결제 세션 ID, 가맹점 거래 ID, HyperPay로 보낸 금액, 결과, 테스트 결제의 Test mode 배지가 포함됩니다. 모듈의 메모는 주문의 비공개 메시지에 있습니다.

캡처

HyperPay payment authorized 상태의 주문에는 블록에 금액과 함께 Capture payment가 표시됩니다. 클릭한 다음 Capture the pre-authorized amount through HyperPay?를 확인하십시오. 사전 승인이 이루어진 모드에서 현재 주문 합계가 캡처되므로, 해당 모드의 Access Token과 Entity ID가 설정되어 있어야 합니다. 주문을 편집할 권한이 필요하며, 모듈 페이지에 대한 접근 권한은 필요하지 않습니다. 캡처가 성공하면 주문은 Payment accepted가 되고, 캡처 ID가 결제와 메모에 추가됩니다. HyperPay가 캡처를 거부하면 결과 코드와 설명이 표시되어 메모에 추가되며, 주문은 승인 상태로 남습니다. 두 번 클릭해도 두 번 캡처되지 않습니다. 사전 승인의 무효화(void)는 HyperPay 대시보드에서 합니다.

환불

PrestaShop에서의 환불은 지원되지 않으며, PrestaShop의 표준 환불 버튼은 HyperPay를 통해 돈을 돌려보내지 않습니다. HyperPay 대시보드에서 결제를 환불하고, 필요한 경우 PrestaShop에서 부분 환불이나 크레딧 슬립으로 기록하십시오. HyperPay에서 이루어진 환불과 차지백은 웹훅에 의해 메모로 주문에 추가되며, 주문 상태는 변경되지 않습니다.

라이선스 키

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

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

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

문제 해결

체크아웃에 HyperPay가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 Access Token과 Entity ID가 있는지 확인하십시오. 테스트 모드에서는 테스트 자격 증명, 운영 모드에서는 운영 자격 증명이 필요합니다. 없으면 설정 페이지에 경고가 표시됩니다. Payment > Preferences에서 모듈이 장바구니 통화, 고객의 국가, 고객 그룹에 대해 허용되어 있는지 확인하십시오.

결제는 완료되었지만 주문이 생성되지 않음: 웹훅이 작동하지 않으며 고객이 쇼핑몰로 돌아오지 않았습니다. HyperPay 대시보드에서 사용 중인 모드의 결제 웹훅이 존재하는지, URL이 Webhook URL에 표시된 것과 정확히 같은지, 복호화 키가 같은 모드의 웹훅 키 필드에 있는지 확인하십시오. Enable Logging을 켜고 모듈 페이지의 Log 필드를 확인하십시오.

웹훅이 Decryption failed로 응답함: 웹훅 키가 다른 웹훅 또는 다른 모드의 것입니다. HyperPay 대시보드에서 키를 다시 복사하십시오.

웹훅이 Webhook key not configured로 응답함: 유효한 웹훅 키가 설정되지 않았습니다. 64자리 키를 설정에 붙여 넣으십시오. HyperPay는 웹훅을 다시 시도합니다.

웹훅이 Busy, retry later로 응답함: 같은 순간 다른 요청이 주문을 처리하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). HyperPay는 웹훅을 다시 시도합니다. 이유는 로그에 있습니다.

로그에 Webhook ignored가 표시됨: 결제가 이 쇼핑몰의 장바구니에 속하지 않거나, 다른 모드에서 이루어졌습니다. 테스트 결제와 운영 결제는 분리되어 관리됩니다.

브라우저에서 웹훅 URL이 Method not allowed를 표시함: 정상입니다. 이 URL은 HyperPay의 POST 요청만 받습니다.

결제 양식이 로드되지 않음: 로그를 확인하십시오. 설정 오류는 보통 현재 모드의 Access Token 또는 Entity ID가 잘못되었음을 뜻합니다. 청구 정보에 관한 메시지는 HyperPay가 일부 고객 데이터를 받아들이지 않았다는 뜻입니다. 선택한 Payment Brands가 귀하의 Entity ID에 대해 활성화되어 있는지 확인하십시오.

주문이 HyperPay payment on hold 상태임: 주문의 메모를 읽고(주문 상태 참조), HyperPay 대시보드에서 결제를 확인한 다음 주문을 처리하거나 결제를 환불하십시오.

캡처가 실패함: 블록과 메모에 표시된 결과 코드와 설명을 확인하십시오. 캡처는 사전 승인과 같은 모드로 전송되므로 그 모드의 자격 증명이 설정되어 있어야 합니다. 그렇지 않으면 블록에 해당 모드의 Access Token / Entity ID가 비어 있다고 표시됩니다.

제거

Modules > Module Manager로 이동한 다음 VibeFox HyperPay Payment Gateway 옆의 메뉴를 열고 Uninstall을 선택합니다. 이 모듈의 라이선스 키와 라이선스 상태는 항상 제거됩니다. Delete Data on Uninstall이 켜져 있으면 설정, HyperPay 결제 시도 테이블, 로그 파일이 삭제됩니다. 꺼져 있으면 나중에 다시 설치할 수 있도록 모두 유지됩니다. 주문 상태 Awaiting HyperPay payment, HyperPay payment authorized, HyperPay payment on hold는 항상 유지됩니다. 기존 주문은 결제 메모와 거래 ID를 그대로 유지합니다.

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