VibeFox OpenPay for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

HTTPS: 카드 양식이 체크아웃 페이지에 있으므로 쇼핑몰은 HTTPS를 사용해야 합니다.

OpenPay 계정: 멕시코, 콜롬비아 또는 페루의 OpenPay 계정. 해당 계정의 Merchant ID, 비공개 키(sk_...), 공개 키(pk_...)가 필요합니다. 샌드박스와 운영 대시보드의 Merchant ID 및 키는 서로 다르며, 모듈은 이를 분리하여 관리합니다.

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

카드는 체크아웃 페이지에 입력하지만, 브라우저에서 openpay.js가 읽고 토큰으로 변환합니다. 카드 필드에는 이름이 없으며 서버로 전송되지 않습니다. 카드 양식이 귀하의 페이지에 있으므로 PCI DSS 적용 범위는 SAQ A-EP입니다. 자세한 내용은 거래 은행(acquirer)에 문의하십시오.

설치

1. 관리자 페이지에서 Modules > Module Manager로 이동한 후 Upload a module을 클릭합니다. 모듈 ZIP 파일을 선택합니다.

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

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

4. Account country를 선택하고 샌드박스 및 운영 키를 입력합니다(설정 참조).

5. 권장: OpenPay 대시보드에 웹훅 URL을 추가합니다(설정 참조).

6. Enable / Disable을 켜고 Save를 클릭합니다. OpenPay 샌드박스 테스트 카드로 결제를 테스트한 후, 실제 결제를 받으려면 Sandbox mode를 끕니다.

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

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox OpenPay Gateway > Configure. 각 섹션에는 자체 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. 필드 위쪽에서 페이지는 현재 모드의 키가 불완전할 때(이 경우 결제 수단이 체크아웃에서 숨겨짐), 쇼핑몰의 기본 통화가 선택한 계정 국가에서 허용되지 않을 때 경고하며, 샌드박스 모드가 켜져 있는 동안 Sandbox mode is enabled — no real charges are made.를 표시합니다.

저장할 때 키를 검사합니다. Merchant ID에는 문자와 숫자만 포함할 수 있고, 비공개 키는 sk_로, 공개 키는 pk_로 시작해야 합니다. 잘못된 값은 저장되지 않으며, 이전 값이 유지되고 오류가 표시됩니다(예: Sandbox: The private key must start with sk_.). 결제 수단은 활성화되어 있지만 현재 모드의 키가 불완전하면, 체크아웃에서 게이트웨이가 계속 숨겨진다는 메시지도 표시됩니다. Title이 비어 있으면 Enter a title for the payment method. 메시지와 함께 저장이 거부됩니다.

OpenPay

Enable / Disable: Enable OpenPay card payments는 결제 수단을 켜거나 끕니다. 기본값: 꺼짐.

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

Description: 체크아웃에서 카드 양식 위에 표시되는 텍스트입니다. 기본값: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).

OpenPay 계정

Merchant ID, 비공개 키(sk_), 공개 키(pk_)는 OpenPay 대시보드의 Settings (Configuración)에 있습니다. 이 섹션에는 멕시코, 콜롬비아, 페루의 샌드박스 및 운영 대시보드 링크가 있습니다.

Account country: OpenPay 계정의 국가입니다. OpenPay API, 해당 국가의 openpay.js 라이브러리, 허용되는 통화를 결정합니다. 기본값: Mexico.

Sandbox mode: OpenPay 샌드박스를 사용합니다(테스트 키, 실제 청구 없음). 키와 API를 모두 샌드박스로 전환합니다. 켜져 있는 동안 체크아웃에 SANDBOX MODE 배지가 표시됩니다. 기본값: 켜짐. 실제 결제를 받으려면 끄십시오.

Sandbox Merchant ID: 샌드박스 대시보드의 Settings (Configuración), API 키에 있는 Merchant ID입니다.

Sandbox Private Key: 샌드박스 비공개 키입니다. sk_로 시작합니다. 서버에서만 사용되며 절대 공유하지 마십시오.

Sandbox Public Key: 샌드박스 공개 키입니다. pk_로 시작합니다. openpay.js가 브라우저에서 카드를 토큰화하는 데 사용합니다.

Live Merchant ID: 운영 대시보드의 Settings (Configuración), API 키에 있는 Merchant ID입니다.

Live Private Key: 운영 비공개 키(sk_...)입니다.

Live Public Key: 운영 공개 키(pk_...)입니다.

저장된 비공개 키는 다시 표시되지 않습니다. 필드는 비어 있으며 Saved — leave empty to keep it.를 표시합니다. 변경하려는 경우에만 새 값을 입력하십시오.

Clear saved secrets: 비공개 키를 체크하고 Save를 클릭하면 삭제됩니다. 필드를 비워 두면 저장된 값이 유지됩니다.

Webhook

웹훅은 필수는 아니지만 권장됩니다. 고객이 3D Secure 페이지에서 돌아오지 않을 때(예: 브라우저를 닫은 경우) 결제를 확인합니다. OpenPay 대시보드에서 Settings > Webhooks로 이동하여 이 섹션의 Webhook URL에 표시된 URL을 추가합니다. 친숙한 URL을 사용하는 경우 https://your-shop/module/wcp_openpay_gateway/webhook와 같은 형태이며, /en/과 같은 언어 코드가 붙을 수도 있습니다. 설정에 표시된 그대로 정확하게 복사하십시오. 사용하는 각 모드(샌드박스와 운영)의 대시보드에 웹훅을 추가하십시오.

웹훅을 추가하면 OpenPay가 이 URL로 확인 코드를 보냅니다. 코드는 도착 날짜와 함께 이 섹션에 표시되므로, OpenPay 대시보드에서 웹훅을 확인할 수 있습니다.

다음 이벤트를 선택하십시오(이 섹션에도 나열되어 있습니다).

OpenPay는 웹훅에 서명하지 않으므로, 모듈은 알림 자체를 절대 신뢰하지 않습니다. 알림은 결제를 찾는 데만 사용하며, 이후 결제가 이루어진 모드와 계정 국가의 비공개 키로 OpenPay API에서 결제를 읽어옵니다. 이 쇼핑몰이 생성하지 않은 결제에 대한 알림은 무시됩니다. 웹훅은 쇼핑몰이 점검 모드에 있는 동안에도 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다.

고급

Debug log: 결제 단계를 모듈 폴더의 logs/wc_opy_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 꺼져 있어도 오류와 경고는 기록됩니다. 키, 카드 데이터, 고객 정보는 절대 기록되지 않습니다. 기본값: 꺼짐.

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

Delete data on uninstall: 켜져 있으면 모듈을 제거할 때 게이트웨이 설정, 저장된 웹훅 확인 코드, 로그가 삭제됩니다. 주문의 OpenPay 결제 기록은 결제 내역이므로 항상 보관되어, 재설치 후에도 주문을 환불할 수 있습니다. 기본값: 꺼짐.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 Credit or debit card (OpenPay))을 선택하고 Cardholder name, Card number, Expiry (MM/YY), Card code (CVV)를 입력합니다. 샌드박스 모드에서는 양식에 SANDBOX MODE — Test environment. No real charges will be made.가 표시됩니다. 고객이 확인하면 openpay.js가 브라우저에서 카드를 일회용 토큰으로 변환하고, 사기 방지 라이브러리가 기기 세션 ID를 추가합니다. 귀하의 쇼핑몰로는 이 두 값과 장바구니 번호만 전송됩니다. 양식이 불완전하면 양식 아래에 Please fill in all card fields.가 표시됩니다.

그런 다음 모듈은 장바구니 통화로 장바구니 합계에 대한 3D Secure 결제를 생성하고, 고객을 OpenPay가 제공하는 은행의 3D Secure 페이지로 보냅니다. 각 시도는 고유한 OpenPay 주문 참조 번호를 받습니다. 결제 설명은 Cart #, 장바구니 번호, 쇼핑몰 이름입니다. 고객의 이름, 이메일, 전화번호는 OpenPay에 전달되며, OpenPay에 고객 계정은 만들어지지 않습니다. 이 시점에는 아직 주문이 존재하지 않습니다.

고객이 돌아오면 모듈은 OpenPay API에서 결제를 읽어옵니다. OpenPay가 확인한 후에만 주문이 결제 완료로 표시됩니다. 결제는 이 장바구니에 속해야 하고, 완료되어야 하며, 장바구니 합계 및 통화와 정확히 일치해야 합니다. 이후 주문이 생성되고 고객은 Your card payment has been received.가 표시된 주문 확인 페이지를 봅니다. OpenPay가 결제가 진행 중이라고 보고하면, 주문은 Awaiting OpenPay payment 상태로 생성되고 페이지에는 We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again.가 표시됩니다. 결과를 아직 알 수 없으면, 같은 문구와 Check again 버튼, Back to checkout 버튼이 있는 Payment confirmation 페이지가 표시되며, 웹훅이 도착하는 즉시 주문이 생성됩니다. 진행 중이던 결제가 나중에 실패하면, 주문 확인 페이지에 Your OpenPay card payment was not completed. Please contact us about this order.가 표시됩니다.

카드가 거절되거나 3D Secure가 실패하면 고객은 The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card.가 표시된 체크아웃으로 돌아가며, 다시 결제할 수 있습니다. 장바구니는 유지됩니다. 새 시도 전에 모듈은 장바구니의 이전 결제를 확인합니다. 실제로 결제가 완료되었다면, 두 번째 청구 없이 그 결제로부터 주문이 생성됩니다. 아직 진행 중이면 주문은 Awaiting OpenPay payment 상태로 생성됩니다. 상태를 확인할 수 없으면 새로운 청구가 이루어지지 않으며, 고객에게는 We could not confirm the status of your previous payment attempt. Please try again in a few minutes.가 표시됩니다. 이미 주문이 있는 장바구니는 다시 청구되지 않습니다.

거절된 카드에는 명확한 메시지가 표시됩니다(예: The card has insufficient funds. Please use another card., The card has expired. Please use another card. 또는 The security code (CVV) is not valid. Please check it and try again.). OpenPay의 기술적 오류는 고객에게 절대 표시되지 않으며, 로그로 전달됩니다.

결제와 확인 사이에 장바구니의 쿠폰이 더 이상 유효하지 않게 되면, 쿠폰은 주문에서 제거됩니다. 고객이 할인된 가격으로 결제했으므로, 주문은 메모와 함께 OpenPay payment on hold 상태가 됩니다.

결제 수단이 비활성화되어 있거나, 현재 모드의 키가 불완전하거나, 장바구니 통화가 계정 국가에서 허용되지 않으면, 결제 수단은 체크아웃에서 숨겨집니다.

이 모듈은 즉시 캡처되는 카드 결제만 받습니다. 저장된 카드, 구독, 무이자 할부 또는 분할 결제, 카드 포인트 결제, 현금, SPEI, PSE 또는 CoDi 결제는 지원하지 않으며, 승인과 캡처를 분리하여 처리하는 기능도 없습니다.

주문 및 환불

주문 상태

아직 주문 없음: 고객이 3D Secure 페이지에 있거나, 결제를 완료하지 않았거나, 카드가 거절되었습니다. 장바구니만 존재합니다.

Payment accepted: 결제가 확인되었습니다. 결제는 OpenPay 청구 ID를 거래 ID로 하여 기록되며, 메모에는 청구 ID와 모드(운영 또는 샌드박스)가 표시됩니다.

Awaiting OpenPay payment: OpenPay가 청구를 진행 중(아직 캡처되지 않음)으로 보고합니다. 청구가 완료되면 주문은 Payment accepted로, 실패하면 Payment error로 바뀝니다.

OpenPay payment on hold: OpenPay가 장바구니와 다른 금액 또는 통화의 완료된 청구를 보고했거나(주문은 결제 완료로 표시되지 않으며, 메모에 차이가 표시됨), 쿠폰이 제거되었거나, 이미 취소되었거나 환불된 주문에 대한 결제가 도착했습니다(결제는 기록됨). 주문을 확인하여 처리하거나, OpenPay 대시보드에서 결제를 환불하십시오.

Payment error: 진행 중이던 청구가 실패했거나, 취소되었거나, 만료되었습니다.

Refunded: 모듈을 통해 청구 금액 전액이 환불되었습니다.

이미 결제 완료된 주문에 두 번째 완료된 청구가 도착하면, 주문은 변경되지 않습니다. WARNING으로 시작하는 메모가 표시되며, OpenPay 대시보드에서 중복 청구를 환불하도록 요청합니다.

OpenPay 결제 블록

주문 페이지에는 OpenPay payment 블록이 표시되며, 여기에는 청구 ID, 청구 상태, 환경 및 계정 국가, 청구 금액과 주문 합계, 환불 금액, 샌드박스 결제에 대한 Sandbox 배지, 환불 내역, 주문의 OpenPay notes가 포함됩니다.

환불

멕시코 및 페루 계정의 경우: OpenPay payment 블록에 금액을 입력합니다(아직 환불되지 않은 금액이 자동으로 채워집니다). 필요하면 사유를 입력하고 Refund via OpenPay를 클릭합니다. Refund this amount through OpenPay? This cannot be undone. 질문을 확인하십시오. 전액 및 부분 환불을 지원하며, 금액은 OpenPay가 청구한 금액을 넘을 수 없습니다. 주문을 편집할 권한이 있어야 합니다. 환불은 결제가 이루어진 모드와 계정 국가의 키로 전송되므로, 해당 모드의 키가 설정되어 있어야 합니다. 샌드박스 주문을 아직 환불해야 한다면 샌드박스 키를 유지하십시오. OpenPay가 환불을 수락하지 않으면 블록에 오류가 표시되며(예: OpenPay refund failed: ...), 환불은 기록되지 않습니다. 환불이 성공하면 OpenPay 환불 ID와 함께 환불 내역과 메모에 추가됩니다. 전액 환불은 주문을 Refunded로 설정합니다. 부분 환불은 상태를 변경하지 않습니다. 환불은 OpenPay가 결제를 확인한 후에만 가능하며, 금액 불일치로 OpenPay payment on hold 상태가 된 주문은 모듈을 통해 환불되지 않습니다.

OpenPay Colombia는 공식 OpenPay 플러그인과 마찬가지로 API를 통한 카드 환불을 지원하지 않습니다. 콜롬비아 결제의 경우 블록에 환불 양식이 제공되지 않으며, OpenPay 대시보드에서 결제를 환불하십시오.

모듈은 신용 전표를 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 OpenPay를 통해 돈을 돌려주지 않습니다.

OpenPay 대시보드에서 이루어진 환불과 차지백은 웹훅으로 전달되며, 메모에 한 번만 추가됩니다. 주문 상태와 신용 전표는 자동으로 변경되지 않습니다. 필요한 경우 수동으로 업데이트하십시오.

라이선스 키

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

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

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

문제 해결

체크아웃에 OpenPay가 나타나지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 현재 모드에 세 가지 키가 모두 있는지 확인하십시오. 샌드박스 모드에서는 샌드박스 키, 운영 모드에서는 운영 키가 필요합니다. 장바구니 통화가 Account country에서 허용되는지도 확인하십시오(멕시코: MXN, USD / 콜롬비아: COP, USD / 페루: PEN, USD). 설정 페이지는 각 경우에 경고를 표시합니다. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인하십시오.

결제는 완료되었지만 주문이 생성되지 않음: 고객이 3D Secure 페이지에서 돌아오지 않았고 웹훅이 작동하지 않습니다. 사용 중인 모드의 OpenPay 대시보드에 웹훅 URL이 설정에 표시된 그대로, 위에 나열된 이벤트와 함께 추가되어 있는지 확인하십시오. 결제가 이루어진 모드의 키가 입력되어 있는지 확인하십시오. 키가 없으면 웹훅은 not configured로 응답하고, OpenPay는 나중에 다시 시도합니다. 주문은 고객이 쇼핑몰로 돌아오거나 같은 장바구니를 다시 결제하려고 할 때도 생성됩니다.

웹훅이 ignored (unknown order)로 응답함: 이 쇼핑몰이 만들지 않은 청구입니다(예: 같은 OpenPay 계정의 다른 쇼핑몰 청구). 아무것도 변경되지 않습니다.

웹훅이 verification failed로 응답함: 청구를 읽기 위해 OpenPay API에 연결할 수 없었습니다. OpenPay가 웹훅을 다시 시도합니다.

웹훅이 busy로 응답함: 같은 시점에 다른 요청이 장바구니를 업데이트하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). OpenPay가 웹훅을 다시 시도합니다. 이유를 보려면 Debug log를 켜십시오.

고객에게 The secure card form could not be loaded가 표시됨: OpenPay의 openpay.js 또는 사기 방지 라이브러리가 브라우저에서 로드되지 않았거나, 기기 세션 ID를 만들 수 없었습니다. 고객에게 페이지를 새로 고치고 다시 시도하도록 요청하십시오.

고객에게 The payment could not be processed right now가 표시됨: OpenPay가 요청을 거부했거나 응답하지 않았습니다. 이유는 로그에 있습니다. 잘못된 Merchant ID 또는 비공개 키가 흔한 원인입니다. OpenPay가 응답하지 않았다면, 고객이 다시 결제하기 전에 OpenPay 대시보드에서 청구를 확인하십시오.

고객에게 This test card cannot be used for real payments가 표시됨: 샌드박스 모드가 꺼져 있는 동안 샌드박스 테스트 카드가 사용되었습니다.

결제 후 주문이 OpenPay payment on hold 상태임: 블록의 OpenPay notes를 확인한 후(주문 상태 참조), 주문을 처리하거나 결제를 환불하십시오.

모드 관련 메시지와 함께 환불이 실패함: 주문이 샌드박스 또는 운영 모드에서 결제되었으며, 해당 모드의 키가 설정되어 있지 않습니다. 키를 입력한 후 다시 시도하십시오.

The order is being updated right now으로 환불이 실패함: 웹훅 또는 다른 요청이 같은 시점에 주문을 업데이트하고 있었습니다. 잠시 후 다시 시도하십시오.

제거

Modules > Module Manager로 이동하여 VibeFox OpenPay Gateway 옆의 메뉴를 열고 Uninstall을 선택합니다. 이 모듈의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Delete data on uninstall이 켜져 있으면 게이트웨이 설정, 저장된 웹훅 확인 코드, 로그가 삭제됩니다. 꺼져 있으면 나중에 재설치할 수 있도록 모든 설정이 유지됩니다. OpenPay 청구 및 환불 기록과 주문 상태 Awaiting OpenPay payment, OpenPay payment on hold는 항상 보관되므로, 이전에 결제된 주문은 재설치 후에도 환불할 수 있습니다. 기존 주문은 결제 메모와 거래 ID를 유지합니다.

OpenPay는 각 소유자의 상표입니다. 이 모듈은 OpenPay와 제휴하거나 OpenPay의 승인을 받지 않았습니다.