VibeFox Paymob for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

Paymob 계정: 지원되는 국가 중 한 곳의 가맹점 계정: 이집트, 아랍에미리트, 사우디아라비아, 오만 또는 파키스탄. Paymob 대시보드에서 네 가지 값이 필요합니다: API key, 온라인 결제 연동의 integration ID, 결제 페이지의 iFrame ID, HMAC secret.

통화: 장바구니 통화는 Paymob 국가의 통화여야 합니다. 이집트는 EGP, 아랍에미리트는 AED, 사우디아라비아는 SAR, 오만은 OMR, 파키스탄은 PKR입니다. 다른 통화를 사용하면 체크아웃에서 결제 수단이 숨겨집니다. 다중 통화 Paymob 계정은 지원되지 않습니다.

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

설치

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

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

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

4. Paymob country를 선택하고 API key, integration ID, iFrame ID, HMAC secret을 입력합니다(설정 참조).

5. Paymob 대시보드에서 연동의 콜백 URL을 Configure 페이지에 표시된 URL로 설정합니다(Callbacks 참조).

6. Enable/Disable을 켜고 Save를 클릭합니다. Paymob 테스트 연동의 ID로 테스트 결제를 진행한 뒤 실제 연동의 ID를 입력합니다.

설치 시 모듈은 두 가지 주문 상태를 만듭니다: Awaiting Paymob payment와 Paymob payment on hold. PrestaShop은 새 결제 모듈을 모든 통화, 국가, 고객 그룹에 대해 기본적으로 활성화합니다. 이는 Payment > Preferences에서 제한할 수 있습니다. 나중에 쇼핑몰에서 활성화한 국가도 이 모듈에 대해 그곳에서 체크해야 합니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Paymob Pay > Configure. 각 섹션에는 페이지 전체를 저장하는 자체 Save 버튼이 있습니다. 필드 위에서 Paymob 값 네 가지 중 하나가 누락된 경우(그때까지 Paymob은 체크아웃에 표시되지 않습니다)와 선택한 Paymob 국가가 쇼핑몰의 기본 통화를 받지 않는 경우, 페이지가 경고를 표시합니다. Callbacks 상자에는 Copy 버튼과 함께 콜백 URL이 표시되고, 선택한 국가의 Paymob 대시보드 링크가 제공됩니다.

Paymob

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

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

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely by card or mobile wallet on the Paymob payment page. 표시하지 않으려면 비워 두십시오.

Paymob 계정

모든 값은 Paymob 가맹점 대시보드에 있습니다. 별도의 테스트 모드는 없습니다. 테스트 결제에는 테스트 모드 연동의 integration ID를 입력하십시오. 다른 설정은 변경되지 않습니다.

Paymob country: Paymob 계정의 국가입니다. API 및 결제 페이지 서버를 선택하며, 장바구니 통화는 이 국가의 통화여야 합니다. 기본값: Egypt.

API key: Paymob 대시보드의 Settings > Account info > API Key에 있습니다.

Integration ID: Paymob 대시보드의 Developers > Payment Integrations에 있는 카드 또는 지갑 온라인 연동의 숫자 ID입니다. Paymob 페이지에 제공되는 결제 수단은 이 연동의 수단입니다.

iFrame ID: Paymob 대시보드의 Developers > iframes에 있는 결제 iFrame의 숫자 ID입니다.

HMAC secret: Paymob 대시보드의 Settings > Account info > HMAC에 있습니다. 필수 항목입니다. 주문은 이 secret으로 서명된 콜백에서만 결제 완료 상태로 생성됩니다.

Integration ID와 iFrame ID에는 숫자만 입력할 수 있습니다. 공백은 제거됩니다. 그 외의 값은 저장할 때 거부되며, must contain digits only — the previous value was kept 메시지가 표시됩니다. 나머지 필드는 저장됩니다.

저장된 API key와 HMAC secret은 다시 표시되지 않습니다. 필드는 비어 있으며 Saved — leave empty to keep it.이 표시됩니다. 값을 변경하려는 경우에만 새 값을 입력하십시오.

Clear saved secrets: API key 또는 HMAC secret을 체크하고 Save를 클릭하면 삭제됩니다. 필드가 비어 있으면 저장된 값이 유지됩니다.

Callbacks

Paymob은 모든 트랜잭션을 쇼핑몰에 알립니다. Paymob 대시보드에서 Developers > Payment Integrations를 열고 연동을 선택한 뒤 Edit를 클릭하고, Transaction processed callback과 Transaction response callback을 모두 Callbacks 상자에 표시된 URL로 설정합니다. 친숙한 URL을 사용하면 https://your-shop/module/wcp_paymob_pay/callback과 같은 형태이며, /en/과 같은 언어 코드가 포함될 수 있습니다. URL은 쇼핑몰의 기본 언어로 생성됩니다. Copy 버튼으로 복사하십시오. 테스트 연동을 포함하여 사용하는 모든 연동에서 URL을 설정하십시오.

Transaction processed callback은 Paymob 서버가 보냅니다. Transaction response callback은 고객을 쇼핑몰로 돌려보냅니다. 두 가지 모두 HMAC secret으로 서명되며 모듈이 검증합니다. 유효한 서명이 없는 콜백은 거부되며 아무것도 변경하지 않습니다. 서버 콜백이 늦거나 유실되면 서명된 고객 반환도 결제를 확인합니다. 서버 콜백은 쇼핑몰이 유지 보수 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한에 막히지 않습니다.

고급

Debug log: 결제 단계와 콜백을 모듈 폴더의 logs/paymob_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류와 거부된 콜백은 꺼져 있어도 항상 기록됩니다. 키, 토큰 및 고객 데이터는 절대 기록되지 않습니다. 기본값: 끔.

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

Clean uninstall: 켜져 있으면 모듈을 제거할 때 모듈 설정과 로그가 삭제됩니다. 주문(결제 시도)에 저장된 Paymob ID와 주문 상태는 항상 유지됩니다. 기본값: 끔.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 Paymob)을 선택하고 확인합니다. 모듈은 장바구니 통화로 장바구니 합계에 대한 새 Paymob 주문을 등록하고, 고객의 이름, 이메일, 전화번호 및 청구지 주소를 Paymob에 전달한 뒤, 고객을 해당 국가의 Paymob 결제 페이지로 보냅니다. 거기서 고객은 연동에 포함된 수단(예: 카드 또는 모바일 지갑) 중 하나로 결제합니다. 이 시점에는 아직 주문이 없습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 Paymob이 서명된 트랜잭션으로 결제를 확인한 후에만 결제 완료로 표시됩니다. 그런 다음 주문이 생성되고 고객은 표준 주문 확인 페이지를 봅니다. 대기 중인 결제(예: 현금 또는 키오스크)나 승인된 결제도 대기 상태의 주문을 생성하며, 확인 페이지로 이동합니다.

같은 시점에 Paymob 콜백이 주문을 확인하는 중이라면, 고객에게는 Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. 메시지가 표시된 페이지가 나타납니다. 대기 중인 결제의 경우 텍스트는 Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment.입니다. 페이지에는 Check again 버튼과 Back to checkout 버튼이 있습니다.

결제가 거부되면 고객은 같은 장바구니로 체크아웃에 돌아가며 Your Paymob payment was not completed. Please try again or choose another payment method. 메시지를 봅니다. 새로운 시도마다 별도의 Paymob 주문이 등록되므로 고객은 장바구니를 다시 결제할 수 있습니다. Paymob의 응답을 확인할 수 없으면 고객에게 We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment.가 표시됩니다.

Paymob이 결제를 시작할 수 없으면 고객은 체크아웃에 머물며 Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. 또는 Could not connect to Paymob. Please try again in a moment.와 같은 짧은 메시지를 봅니다. 기술적인 이유는 로그에 기록됩니다.

이 모듈은 Paymob 페이지에서 일회성 결제를 처리합니다. 저장된 카드, 구독, 쇼핑몰 사이트에 내장된 카드 입력 양식, 백오피스에서의 환불은 지원되지 않습니다.

주문

주문 상태

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

Payment accepted: Paymob이 결제를 확인했습니다. 결제는 Paymob 트랜잭션 ID를 트랜잭션 ID로 하여 기록되며, 메모에는 트랜잭션, 금액, 카드 종류와 끝 4자리가 표시됩니다.

Awaiting Paymob payment: 결제가 Paymob에서 대기 중입니다(예: 현금 또는 키오스크 결제). Paymob이 결제를 확인하면 주문은 Payment accepted로 바뀝니다.

Paymob payment on hold: Paymob이 금액만 승인하고 capture하지 않았습니다(Paymob 대시보드에서 capture하십시오. capture 콜백이 도착하면 주문은 Payment accepted로 바뀝니다). 또는 결제된 금액이나 통화가 장바구니와 다릅니다(예: 결제가 시작된 후 장바구니가 변경됨). 또는 취소된 주문에 대한 결제가 도착했습니다. 메모에 이유가 설명됩니다. 주문을 확인하여 처리하거나 Paymob 대시보드에서 결제를 환불하십시오.

이미 결제 완료된 주문에 두 번째 성공 결제가 도착하면 주문은 변경되지 않습니다. 메모는 Paymob 대시보드에서 중복 결제를 환불하라고 요청합니다. 이전에 결제된 적이 있는 취소 주문이나 환불된 주문에 대한 결제는 메모만 추가하며, 주문은 다시 열리지 않습니다. 아직 결제되지 않은 주문에 대한 거부된 결제는 메모만 추가합니다.

Paymob 결제 블록

주문 페이지에는 주문의 각 Paymob 시도를 보여주는 Paymob payment 블록이 표시됩니다: Paymob 주문, 가맹점 주문 ID와 국가, Paymob 트랜잭션 ID, 상태, 요청 금액, Paymob이 카드에 대해 보고한 금액, Paymob 메시지. 그 아래에는 이 주문에 대한 모듈의 Notes가 있습니다.

환불

백오피스에서의 환불은 지원되지 않습니다. Paymob 대시보드에서 결제를 환불하거나 취소하십시오. Paymob이 환불 또는 취소를 보고하면 주문에 메모가 추가되며, 주문 상태는 변경되지 않습니다. 주문 상태나 크레딧 슬립 등 주문을 수동으로 업데이트하십시오.

라이선스 키

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

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

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

문제 해결

체크아웃에 Paymob이 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 네 가지 값(API key, integration ID, iFrame ID, HMAC secret)이 모두 입력되어 있는지, 장바구니 통화가 선택한 Paymob country의 통화인지 확인하십시오. 무언가 빠져 있으면 설정 페이지에 경고가 표시됩니다. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인하십시오.

결제는 완료되었으나 주문이 생성되지 않음: 콜백이 쇼핑몰에 도달하지 않습니다. 사용 중인 연동의 Transaction processed callback과 Transaction response callback이 Callbacks 상자에 표시된 URL과 정확히 일치하는지, 그리고 HMAC secret이 같은 Paymob 계정의 것인지 확인하십시오. 거부된 콜백은 Debug log가 꺼져 있어도 경고로 로그에 기록됩니다. 모듈 페이지의 Log 필드를 확인하십시오.

콜백이 Invalid signature를 응답함: 설정의 HMAC secret이 Paymob 계정과 일치하지 않거나, 다른 국가의 계정이 선택되어 있습니다. HMAC secret을 다시 복사하십시오.

콜백이 Not configured를 응답함: HMAC secret이 비어 있습니다. secret을 입력하십시오. Paymob이 콜백을 다시 시도합니다.

콜백이 locked 또는 retry를 응답함: 고객 반환과 같은 다른 요청이 동시에 주문을 업데이트하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). Paymob이 콜백을 다시 시도합니다. 이유는 로그에 기록됩니다.

브라우저에서 콜백 URL을 열면 could not verify 메시지와 함께 체크아웃으로 이동함: 정상입니다. 이 URL은 Paymob의 서명된 요청만 받습니다.

고객이 Paymob을 선택할 때 오류가 표시됨: Debug log를 켜고 로그를 확인하십시오. Paymob payments are temporarily unavailable은 잘못된 API key 또는 누락된 값을 의미합니다. Paymob could not start the payment는 잘못된 integration ID나 불완전한 청구 정보 등으로 Paymob이 요청을 거부했음을 의미합니다. This order cannot be paid with Paymob는 주문 합계가 0임을 의미합니다. 통화가 뒤따르는 Paymob does not accept payments in는 장바구니 통화가 선택한 Paymob 국가의 통화가 아님을 의미합니다.

결제 후 주문이 Paymob payment on hold 또는 Awaiting Paymob payment 상태임: Paymob payment 블록의 메모를 읽어 보십시오. 결제가 대기 중(현금 또는 키오스크)이거나, 트랜잭션이 승인만 되었거나(Paymob 대시보드에서 capture하십시오), 금액 또는 통화가 일치하지 않았거나, 주문이 취소된 후에 결제가 도착했습니다.

테스트 결제: Integration ID에 Paymob 테스트 연동의 ID를 입력하고 그 연동에서 콜백 URL을 설정하십시오. 실제 결제의 경우 실제 연동의 ID를 다시 입력하십시오.

제거

Modules > Module Manager로 이동하여 VibeFox Paymob Pay 옆의 메뉴를 열고 Uninstall을 선택합니다. 이 모듈의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Clean uninstall이 켜져 있으면 모듈 설정과 로그가 삭제됩니다. 꺼져 있으면 나중에 다시 설치할 수 있도록 모든 설정이 유지됩니다. 주문의 Paymob 결제 시도와 Awaiting Paymob payment 및 Paymob payment on hold 주문 상태는 항상 유지됩니다. 기존 주문은 결제 메모, 트랜잭션 ID, Paymob ID를 그대로 유지합니다.

Paymob은 해당 소유자의 상표입니다. 이 모듈은 Paymob과 제휴 관계가 없으며 Paymob의 승인을 받지 않았습니다.