VibeFox Paymob for WooCommerce — 도움말

요구 사항

WordPress: 6.2 이상.

WooCommerce: 8.0 이상, 설치되어 있고 활성화된 상태여야 합니다. WooCommerce가 없으면 플러그인이 활성화되지 않습니다.

PHP: 8.0 이상.

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

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

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서 사용할 수 있습니다.

설치

1. WordPress에서 Plugins > Add New > Upload Plugin으로 이동하여 플러그인 ZIP 파일을 선택하고 Install Now를 클릭하세요. FTP로 wcp_paymob_pay 폴더를 /wp-content/plugins/에 업로드할 수도 있습니다.

2. Activate를 클릭하세요.

3. 설정을 여세요: WooCommerce > Settings > Payments > Paymob > Manage, 또는 Plugins 페이지에서 플러그인 이름 아래의 Settings를 클릭하세요.

4. 페이지 상단의 라이선스 블록에 VibeFox 라이선스 키를 입력하고 Activate를 클릭하세요.

5. Paymob country를 선택하고 API 키, 연동 ID, iFrame ID, HMAC 비밀키를 입력하세요(설정 항목 참고).

6. Paymob 대시보드에서 연동의 콜백 URL을 설정 페이지에 표시된 URL로 지정하세요(Callbacks 참고).

7. Enable/Disable을 켜세요. Paymob 테스트 연동의 ID로 결제를 테스트한 다음, 실제 연동의 ID를 입력하세요.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Paymob. 입력란 위에서 페이지는 Paymob 값 네 개 중 하나라도 비어 있으면(그때까지 체크아웃에 Paymob이 표시되지 않습니다), 쇼핑몰 통화를 선택한 Paymob 국가가 받지 않으면 경고를 표시합니다. 상자에는 Copy 버튼이 있는 콜백 URL과 선택한 국가의 Paymob 대시보드 링크가 표시됩니다.

일반

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

Title: 체크아웃에서 고객에게 보이는 결제 수단 이름입니다. 기본값: Paymob.

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely by card or mobile wallet on the Paymob payment page.

Paymob 계정

모든 값은 Paymob 가맹점 대시보드에 있습니다. 별도의 테스트 모드는 없습니다. 테스트 결제에는 테스트 모드 연동의 연동 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에 있습니다. 필수입니다. 주문은 이 비밀키로 서명된 콜백을 통해서만 결제 완료로 표시됩니다.

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

Callbacks

Paymob은 각 거래를 쇼핑몰에 알려줍니다. Paymob 대시보드에서 Developers > Payment Integrations를 열고 연동을 선택한 뒤 Edit를 클릭하고, Transaction processed callback과 Transaction response callback을 모두 설정 페이지에 표시된 URL로 지정하세요. URL은 https://your-site/wc-api/paymob_pay/와 같은 형식입니다. Copy 버튼으로 복사하세요. 테스트 연동을 포함하여 사용하는 모든 연동에 URL을 설정하세요.

거래 처리 완료 콜백은 Paymob 서버가 보냅니다. 거래 응답 콜백은 고객을 쇼핑몰로 돌려보냅니다. 두 콜백 모두 HMAC 비밀키로 서명되며 플러그인이 검증합니다. 유효하지 않은 서명의 콜백은 거부되며 아무것도 변경하지 않습니다. 서버 콜백이 늦거나 유실되면, 서명된 고객의 복귀도 결제를 확인합니다.

고급

Debug log: Log payment steps and callbacks는 결제 단계와 콜백을 WooCommerce > Status > Logs에 소스 wcp_paymob_pay로 기록합니다. 오류와 거부된 콜백은 항상 기록됩니다. 키, 토큰, 고객 데이터는 기록되지 않습니다. 기본값: 꺼짐.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. 플러그인을 비활성화해도 아무것도 삭제되지 않습니다. 주문에 저장된 Paymob ID는 유지됩니다. 기본값: 꺼짐.

체크아웃

고객은 결제 수단(기본값은 Paymob)을 선택하고 주문합니다. 플러그인은 주문 통화로 된 주문 총액에 대해 새 Paymob 주문을 등록하고, 고객의 이름, 이메일, 전화번호, 청구지 주소를 Paymob에 전달한 뒤, 고객을 해당 국가의 Paymob 결제 페이지로 보냅니다. 고객은 그곳에서 연동에 포함된 방법, 예를 들어 카드 또는 모바일 월렛으로 결제합니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 Paymob이 서명된 거래로 확인한 뒤에야 결제 완료로 표시됩니다. 결제가 완료되었거나, 대기 중이거나, 승인된 경우 고객은 주문 접수 페이지로 이동합니다.

결제가 거절되면 고객은 Your Paymob payment was not completed. Please try again or choose another payment method. 메시지와 함께 체크아웃으로 돌아갑니다(결제를 Pay for order 페이지에서 시작했다면 그 페이지로 돌아갑니다). 새 시도마다 새로운 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.가 표시됩니다. 기술적인 원인은 로그에 기록됩니다.

이 결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 동작합니다. Pay for order 페이지에서는 쇼핑몰 통화 대신 주문 통화를 확인합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다.

플러그인은 Paymob 페이지에서 일회성 결제만 처리합니다. 저장된 카드, 구독, 사이트에 내장된 카드 입력 양식, WooCommerce에서의 환불은 지원하지 않습니다.

주문

주문 상태

Pending payment: 고객이 Paymob으로 이동했지만 아직 결제하지 않았거나, Paymob이 아직 결제를 확인하지 않았습니다.

Processing: Paymob이 결제를 확인했습니다. 다운로드 가능한 가상 상품만 있는 주문은 WooCommerce 기본값인 완료됨으로 바뀝니다. 주문 메모에는 Paymob 거래, 금액, 카드 종류와 끝 네 자리가 표시됩니다. 거래 ID는 Paymob 거래 ID입니다.

On hold: 결제가 Paymob에서 대기 중입니다(예: 현금 또는 키오스크 결제). 또는 Paymob이 금액을 승인만 하고 캡처하지 않았습니다(Paymob 대시보드에서 캡처하세요. 캡처 콜백이 도착하면 주문이 완료됩니다). 또는 결제된 금액이나 통화가 주문과 다릅니다. 또는 취소된 주문에 대한 결제가 도착했습니다. 이유는 주문 메모에 설명됩니다.

Failed: Paymob이 대기 중인 주문의 결제를 거절했습니다. 고객은 다시 결제할 수 있습니다.

이미 결제가 완료된 주문에 두 번째 결제가 성공적으로 도착해도 주문은 변경되지 않습니다. 메모에서 Paymob 대시보드를 통해 중복 결제를 환불하라고 안내합니다. 이전에 결제되었던 취소된 주문이나 환불된 주문에 대한 결제는 메모만 추가할 뿐, 주문을 다시 열지 않습니다.

환불

WooCommerce에서의 환불은 지원하지 않습니다. Paymob 대시보드에서 결제를 환불하거나 무효화하세요. Paymob이 환불 또는 무효화를 보고하면 주문에 메모가 추가되며, 주문 상태는 변경되지 않습니다. 예를 들어 WooCommerce에서 수동 환불을 하는 등 주문을 직접 업데이트하세요.

라이선스 키

플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 동작합니다. 라이선스 블록은 WooCommerce > Settings > Payments > Paymob 상단에 있습니다. 키를 License key에 붙여 넣고 Activate를 클릭하세요. 블록에는 상태(예: 라이선스 유효 기간)와 도메인이 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하고, Remove key로 이 사이트에서 키를 제거할 수 있습니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

키 하나는 도메인 하나에서 사용할 수 있습니다. 사이트에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하세요.

활성 키가 없으면 체크아웃에서 고객에게 Paymob이 표시되지 않습니다. 그래도 결제가 시작되면 고객에게 This payment method is not available. Please choose another one.가 표시됩니다. 로그인한 쇼핑몰 관리자는 (unlicensed — visible to admins only) 표시와 함께 결제 수단이 계속 보이므로, 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 페이지와 WooCommerce 페이지에 알림이 표시됩니다. 기존 주문에는 영향이 없습니다. 이미 시작된 결제는 계속 확인됩니다.

라이선스가 만료되어도 플러그인은 계속 동작하지만, 업데이트와 지원에는 갱신이 필요합니다. 상태는 백그라운드에서 자동으로 다시 확인됩니다.

문제 해결

체크아웃에 Paymob이 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 네 가지 값(API key, Integration ID, iFrame ID, HMAC secret)이 모두 입력되었는지, 쇼핑몰 통화가 선택한 Paymob country의 통화인지 확인하세요. 설정 페이지는 무엇인가 빠져 있으면 경고를 표시합니다. 다중 통화 Paymob 계정을 사용하는 개발자는 paymob_p_supported_currencies 필터로 허용 통화를 늘릴 수 있습니다.

결제는 완료되었지만 주문이 Pending payment 상태에 머묾: 콜백이 쇼핑몰에 도달하지 않고 있습니다. 사용 중인 연동의 Transaction processed callback과 Transaction response callback이 설정 페이지의 URL과 정확히 일치하는지, 그리고 HMAC secret이 같은 Paymob 계정의 것인지 확인하세요. 거부된 콜백은 디버그 로그가 꺼져 있어도 WooCommerce > Status > Logs에 소스 wcp_paymob_pay의 경고로 기록됩니다.

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

콜백이 Not configured로 응답함: HMAC 비밀키가 비어 있습니다. 비밀키를 입력하세요. Paymob이 콜백을 다시 시도합니다.

콜백이 locked로 응답함: 고객의 복귀 등 다른 요청이 같은 순간 주문을 업데이트하고 있었습니다. Paymob이 콜백을 다시 시도합니다.

고객이 주문할 때 오류를 봄: Debug log를 켜고 로그를 확인하세요. Paymob payments are temporarily unavailable은 잘못된 API 키 또는 누락된 값을 의미합니다. Paymob could not start the payment는 잘못된 연동 ID나 불완전한 청구 정보 등의 이유로 Paymob이 요청을 거부했다는 뜻입니다. This order cannot be paid with Paymob은 주문 총액이 0이라는 뜻입니다.

결제 후 주문이 On hold 상태임: 주문 메모를 확인하세요. 결제가 대기 중이거나(현금 또는 키오스크), 거래가 승인만 되었거나(Paymob 대시보드에서 캡처하세요), 금액이나 통화가 일치하지 않았거나, 주문이 취소된 후에 결제가 도착한 경우입니다. 이유는 주문 메모에 설명되어 있습니다.

테스트 결제: Paymob 테스트 연동의 ID를 Integration ID에 입력하고 그 연동에 콜백 URL을 설정하세요. 실제 결제에는 실제 연동의 ID를 다시 입력하세요.

라이선스 블록에 오류가 표시됨: 블록의 메시지를 따르세요. 예를 들어 키가 다른 도메인에서 이미 사용 중이라면 vibefox.net 계정에서 슬롯을 해제하고 Check now를 클릭하세요. 사이트 주소가 바뀌었다면 Check now를 클릭해 새 도메인에 키를 활성화하세요. 라이선스 서버에 연결할 수 없으면 플러그인은 마지막으로 확인된 상태로 계속 동작합니다.

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화한 뒤 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정과 로그는 Clean uninstall이 켜져 있었던 경우에만 삭제됩니다. 그렇지 않으면 나중에 다시 설치할 때를 위해 남아 있습니다. 기존 주문은 결제 메모, 거래 ID, Paymob ID를 그대로 유지합니다.

Paymob은 해당 소유자의 상표입니다. 이 플러그인은 Paymob과 제휴하거나 Paymob의 승인을 받은 것이 아닙니다.