VibeFox OpenPay for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

WooCommerce: 8.0 이상, 설치되어 활성화되어 있어야 합니다. WooCommerce 없이는 플러그인을 활성화할 수 없습니다.

PHP: 8.0 이상.

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

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

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

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

설치

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

2. Activate를 클릭합니다.

3. 설정을 엽니다: WooCommerce > Settings > Payments > OpenPay > Manage. 또는 플러그인 페이지에서 플러그인 이름 아래의 Settings를 클릭합니다.

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

5. Account country를 선택하고 샌드박스 및 운영 키를 입력합니다(구성 항목 참조).

6. 권장: OpenPay 대시보드에 웹훅 URL을 추가합니다(구성 항목 참조).

7. Enable / Disable을 켜고 저장합니다. OpenPay 샌드박스 테스트 카드로 결제를 테스트한 다음, 실제 결제를 받으려면 Sandbox mode 선택을 해제합니다.

구성

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > OpenPay. 입력란 위에는 현재 모드의 키가 불완전한 경우(이때 체크아웃에서 결제 수단이 숨겨짐), 선택한 계정 국가가 쇼핑몰 통화를 허용하지 않는 경우 경고가 표시되며, 샌드박스 모드가 켜져 있는 동안에는 Sandbox mode is enabled — no real charges are made.가 표시됩니다. 결제 수단 목록에서는 현재 모드에 키 3개가 모두 입력될 때까지 OpenPay가 설정 필요 상태로 표시되며, 샌드박스 모드가 켜져 있는 동안에는 테스트 모드 배지가 표시됩니다.

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

일반

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: Use the OpenPay sandbox (test keys, no real charges)는 키와 API를 모두 샌드박스로 전환합니다. 켜져 있는 동안 체크아웃에 SANDBOX MODE 배지가 표시됩니다. 기본값: 켬. 실제 결제를 받으려면 선택을 해제합니다.

Sandbox Merchant ID: 샌드박스 대시보드의 Merchant ID, Settings (Configuración), API 키.

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

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

Live Merchant ID: 운영 대시보드의 Merchant ID, Settings (Configuración), API 키.

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

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

플러그인 1.0 버전의 키(키 한 세트와 샌드박스 플래그)는 샌드박스 또는 운영 필드로 자동 이전됩니다.

웹훅

웹훅은 필수는 아니지만 권장합니다. 고객이 3D Secure 페이지에서 돌아오지 않을 때(예: 브라우저를 닫은 경우)에도 결제를 확인합니다. OpenPay 대시보드에서 Settings > Webhooks로 이동하여 이 설정 섹션에 표시된 URL을 추가합니다. 형식은 다음과 같습니다: https://your-site/wc-api/webhook_wc_openpay/. 설정에 표시된 그대로 정확히 복사하십시오. 사용하는 각 모드(샌드박스와 운영)의 대시보드에 웹훅을 추가합니다.

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

다음 이벤트를 선택합니다:

OpenPay는 웹훅에 서명하지 않으므로 플러그인은 알림 자체를 절대 신뢰하지 않습니다. 알림은 청구를 찾는 데만 사용하며, 그 후 주문이 결제된 모드의 비공개 키로 OpenPay API에서 청구 내역을 읽습니다. 이 쇼핑몰이 생성하지 않은 청구에 대한 알림은 무시됩니다.

고급

Debug log: Log payment steps (errors are always logged)를 선택하면 결제 단계가 WooCommerce > Status > Logs에 소스 wcp_openpay_gateway로 기록됩니다. 이 옵션이 꺼져 있어도 오류와 경고는 기록됩니다. 키, 카드 데이터, 고객 정보는 절대 기록되지 않습니다. 기본값: 끔.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. 기본값: 끔.

체크아웃

고객은 결제 수단(기본값 Credit or debit card (OpenPay))을 선택하고 Cardholder name, Card number, Expiry (MM/YY), Card code (CVV)를 입력합니다. 주문이 제출되면 openpay.js가 브라우저에서 카드를 일회용 토큰으로 바꾸고, OpenPay의 사기 방지 라이브러리가 기기 세션 ID를 추가합니다. 쇼핑몰로 전송되는 것은 이 두 값뿐입니다.

그다음 플러그인은 주문 합계에 대해 주문 통화로 3D Secure가 적용된 청구를 만들고, OpenPay가 제공하는 고객 은행의 3D Secure 페이지로 고객을 보냅니다. 각 시도에는 OpenPay에서 고유한 주문 참조(주문 번호와 짧은 접미사)가 부여됩니다. 청구 설명은 Order #, 주문 번호, 사이트 이름입니다. 고객의 이름, 이메일, 전화번호는 OpenPay에 전달되며, OpenPay에 고객 계정은 만들어지지 않습니다. 고객이 3D Secure 페이지에 있는 동안 주문은 결제 대기 상태로 남습니다.

고객이 돌아오면 플러그인은 OpenPay API에서 청구 내역을 읽습니다. 주문은 OpenPay가 확인한 후에만 결제 완료로 표시됩니다. 청구는 이 주문에 속해야 하며, 완료된 상태여야 하고, 주문의 합계 금액 및 통화와 정확히 일치해야 합니다. 결과가 아직 확인되지 않았다면, 주문 접수 페이지에 We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again.가 표시됩니다. 그 후 웹훅이 주문을 업데이트합니다.

카드가 거절되거나 3D Secure가 실패하면, 고객은 The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. 메시지와 함께 Pay for order 페이지로 돌아가 다시 결제할 수 있습니다. 새 시도 전에 플러그인은 주문의 이전 청구를 확인합니다. 실제로 결제가 완료되었다면 두 번째 청구 없이 주문을 결제 완료로 표시합니다. 아직 처리 중이면 고객에게 이전 결제가 아직 처리 중이며 다시 결제하지 말아야 한다는 안내가 표시됩니다. 상태를 확인할 수 없으면 새 시도를 하지 않고, 몇 분 후에 다시 시도하도록 고객에게 안내합니다.

거절된 카드에는 명확한 메시지가 표시됩니다. 예를 들어 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의 기술적 오류는 고객에게 절대 표시되지 않으며, 주문 메모와 로그에 기록됩니다.

이 결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. WooCommerce High-Performance Order Storage(HPOS)와 호환됩니다. 비활성화되어 있거나, 현재 모드의 키가 불완전하거나, 주문 통화를 계정 국가가 허용하지 않으면 체크아웃에서 숨겨집니다.

이 플러그인은 카드 결제만 받으며 즉시 캡처합니다. 저장된 카드, 구독, 무이자 할부(MSI) 또는 분할 결제, 카드 포인트 결제, 현금, SPEI, PSE 또는 CoDi 결제는 지원하지 않으며, 승인과 캡처를 나누어 처리하지도 않습니다.

주문 및 환불

주문 상태

결제 대기: 고객이 3D Secure 단계에 있거나 아직 결제를 마치지 않았습니다. 메모에 청구 ID가 표시됩니다.

처리 중: 결제가 확인되었습니다. 이는 결제 후 WooCommerce의 표준 상태이며, 다운로드 가능한 가상 상품만 있는 주문은 완료로 바뀝니다. 주문 메모에는 청구 ID와 모드(운영 또는 샌드박스)가 표시됩니다. 거래 ID는 OpenPay 청구 ID입니다.

보류: 청구가 진행 중이고 아직 캡처되지 않았거나, OpenPay가 주문과 금액 또는 통화가 다른 완료된 청구를 보고한 경우(주문은 결제 완료로 표시되지 않으며 메모에 차이가 표시됩니다), 또는 이미 취소된 주문에 결제가 들어온 경우입니다. OpenPay 대시보드에서 주문을 확인한 뒤 그곳에서 주문을 처리하거나 결제를 환불하십시오.

실패: 청구 생성 시 카드가 거절되었거나, 최근 시도가 실패, 취소 또는 만료되었습니다. 고객은 다시 결제할 수 있습니다.

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

환불

멕시코와 페루 계정의 경우: 주문을 열고 Refund를 클릭한 다음 금액을 입력하고 Refund via Credit or debit card (OpenPay)를 클릭합니다(버튼에는 결제 수단 제목이 표시됩니다). 전액 및 부분 환불을 지원합니다. 환불은 주문이 결제된 모드와 계정 국가로 전송되므로, 환불해야 할 샌드박스 주문이 남아 있는 동안에는 샌드박스 키를 계속 입력해 두십시오. OpenPay가 환불을 거절하면 WooCommerce가 OpenPay refund failed: ...와 같은 오류를 표시하며, 환불은 기록되지 않습니다. 성공한 환불은 OpenPay 환불 ID와 함께 주문 메모에 추가됩니다.

공식 OpenPay 플러그인과 마찬가지로, OpenPay Colombia는 API를 통한 카드 환불을 지원하지 않습니다. 콜롬비아에서는 환불 버튼이 제공되지 않으며, OpenPay 대시보드에서 청구를 환불해야 합니다.

OpenPay 대시보드에서 이루어진 환불과 차지백은 웹훅으로 전달되며, 주문 메모에 한 번만 추가됩니다. WooCommerce 환불로 자동 기록되지는 않습니다. 필요하다면 OpenPay 버튼을 사용하지 않고 WooCommerce에서 수동 환불을 생성하십시오.

라이선스 키

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

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

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

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

문제 해결

체크아웃에 OpenPay가 표시되지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 현재 모드의 키 3개가 모두 입력되었는지(샌드박스 모드에서는 샌드박스 키, 운영 모드에서는 운영 키) 확인하십시오. 쇼핑몰 통화가 Account country에서 허용되는지도 확인하십시오(멕시코: MXN, USD / 콜롬비아: COP, USD / 페루: PEN, USD). 설정 페이지는 각 경우에 경고를 표시합니다.

결제는 완료되었지만 주문이 결제 대기 상태로 남아 있음: 고객이 3D Secure 페이지에서 돌아오지 않았고 웹훅이 작동하지 않습니다. 사용 중인 모드의 OpenPay 대시보드에 웹훅 URL이 설정에 표시된 그대로, 위에 나열된 이벤트와 함께 추가되었는지 확인하십시오. 주문이 결제된 모드의 키가 입력되어 있는지도 확인하십시오. 키가 없으면 웹훅은 not configured로 응답하고, OpenPay는 나중에 다시 시도합니다.

웹훅이 ignored (unknown order)로 응답함: 이 청구는 이 쇼핑몰이 해당 주문을 위해 생성한 것이 아닙니다. 예를 들어 같은 OpenPay 계정의 다른 쇼핑몰 청구입니다. 아무것도 변경되지 않습니다.

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

웹훅이 busy로 응답함: 같은 순간에 다른 요청이 주문을 업데이트하고 있었습니다. OpenPay가 웹훅을 다시 시도합니다.

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

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

「This test card cannot be used for real payments」: 샌드박스 모드가 꺼져 있는데 샌드박스 테스트 카드가 사용되었습니다.

결제 후 주문이 보류 상태임: 주문 메모를 확인하십시오. 청구가 아직 진행 중이거나, 결제된 금액 또는 통화가 주문과 다르거나, 주문이 취소된 후에 결제가 도착한 것입니다.

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

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

제거

플러그인을 비활성화해도 모든 데이터는 유지됩니다. 완전히 제거하려면 Plugins 페이지에서 비활성화한 후 삭제하십시오. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정, 저장된 웹훅 확인 코드, 플러그인 로그는 Delete data on uninstall이 켜져 있는 경우에만 삭제되며, 그렇지 않으면 이후 재설치를 위해 남겨집니다. 주문 데이터는 항상 보존됩니다. 기존 주문은 결제 메모, 거래 ID, 재설치 후 환불에 필요한 청구 데이터를 유지합니다.

OpenPay는 각 소유자의 상표입니다. 이 플러그인은 OpenPay와 제휴하거나 OpenPay의 승인을 받은 것이 아닙니다.